Metadata-Version: 2.4
Name: pycohortflow
Version: 0.1.1
Summary: Lightweight Cohort Flow Diagrams built on Matplotlib.
Author: FSchwarz
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/fschwar4/pycohortflow
Project-URL: Documentation, https://fschwar4.github.io/pycohortflow/
Project-URL: Repository, https://github.com/fschwar4/pycohortflow
Project-URL: Issues, https://github.com/fschwar4/pycohortflow/issues
Keywords: cohort,flow diagram,matplotlib,clinical,consort
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib>=3.5
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="https://fschwar4.github.io/pycohortflow/_static/logo_wide.svg" alt="pycohortflow logo" width="100%" />
</p>

# 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.

## Installation

```bash
pip install pycohortflow
```

## Quick Start

```python
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:

<p align="center">
  <img src="https://fschwar4.github.io/pycohortflow/_static/clinical_flow_chart_white.png" alt="White style preview" width="45%" />
  <img src="https://fschwar4.github.io/pycohortflow/_static/clinical_flow_chart_colorful.png" alt="Colorful style preview" width="45%" />
</p>

```python
# 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:

```toml
[figure]
dpi = 300

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

Then pass it when plotting:

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

See the [full documentation](https://yourusername.github.io/pycohortflow/) for all available options.

## Saving Figures

```python
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

- [ ] python based PRISMA2020 style generation, if necessary
