pycohortflow 0.1.2

Lightweight Cohort Flow Diagrams built on Matplotlib — with an interactive browser-based generator.

pycohortflow

Lightweight cohort flow diagrams built on Matplotlib.

Turn a plain Python list of cohort steps into a publication-ready vertical flow chart with a single function call. Colours, fonts, spacing, and box geometry are fully customisable via TOML configuration files.

No Python installed?

Use the Interactive Generator to build diagrams directly in your browser and export them as SVG, PNG or PDF.

Installation

pip install pycohortflow

Quick Start

from pycohortflow import plot_cohort_flow_diagram
import matplotlib.pyplot as plt

data = [
    {"heading": "Registered Patients", "N": 350,
     "description": "Total patients registered in database"},
    {"heading": "Screening", "N": 150,
     "exclusion_description": "Did not meet inclusion criteria"},
    {"heading": "Eligible", "N": 120,
     "exclusion_description": "Declined / Lost to follow-up"},
    {"heading": "Final Analysis", "N": 115,
     "exclusion_description": "Data incomplete"},
]

fig, ax = plot_cohort_flow_diagram(
    data,
    figure_title="Clinical Cohort Flow Diagram",
)
plt.show()

Built-in Styles

Two styles ship with the package:

# Clean white boxes (default)
fig, ax = plot_cohort_flow_diagram(data, style="white")

# Pastel gradient backgrounds
fig, ax = plot_cohort_flow_diagram(data, style="colorful")

# Transparent figure background (for slides / posters)
fig, ax = plot_cohort_flow_diagram(data, transparent=True)

Customisation

Create a TOML file with only the values you want to override:

[figure]
dpi = 300

[colors]
main_start = "#cce5ff"
main_end   = "#d4edda"

Then pass it when plotting:

fig, ax = plot_cohort_flow_diagram(data, style_config_path="my_style.toml")

See the full documentation for all available options.

Saving Figures

fig, ax = plot_cohort_flow_diagram(
    data,
    save_dir="output",
    img_name="flow_chart",
    save_format=["png", "svg", "pdf"],
)

Requirements

• Python >= 3.9
• Matplotlib >= 3.5

License

AGPL-3.0 license

---

Roadmap

• Add: Python-based PRISMA2020 style generation, if necessary
• Add: Small Diagram version
• Add: Verbose option for communication of saving options
• Add: Diagrams for multiple Arms (e.g. something like CONSORT style)