Metadata-Version: 2.4
Name: prisma-flow
Version: 0.2.0
Summary: Lightweight Python tools for generating PRISMA-style flow diagrams without system dependencies.
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: prisma,systematic-review,scoping-review,evidence-synthesis,literature-review,svg,python,open-science
Author: Open Science Labs Incubator contributors
Requires-Python: >=3.10,<4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Text Processing :: Markup
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: png
Provides-Extra: yaml
Requires-Dist: douki (>=0.12.1) ; extra == "dev"
Requires-Dist: makim (==1.29.0) ; extra == "dev"
Requires-Dist: mypy (>=1.10) ; extra == "dev"
Requires-Dist: pre-commit (>=3) ; extra == "dev"
Requires-Dist: pydantic (>=2)
Requires-Dist: pytest (>=8) ; extra == "dev"
Requires-Dist: pytest-cov (>=5) ; extra == "dev"
Requires-Dist: pyyaml (>=6) ; extra == "yaml"
Requires-Dist: resvg (>=0.1.2) ; extra == "png"
Requires-Dist: ruff (>=0.6) ; extra == "dev"
Project-URL: Documentation, https://osl-incubator.github.io/prisma-flow/
Project-URL: Homepage, https://github.com/osl-incubator/prisma-flow
Project-URL: Issues, https://github.com/osl-incubator/prisma-flow/issues
Project-URL: Repository, https://github.com/osl-incubator/prisma-flow
Description-Content-Type: text/markdown

# prisma-flow

![CI](https://img.shields.io/github/actions/workflow/status/osl-incubator/prisma-flow/ci.yml?logo=github&label=CI)
[![Python Versions](https://img.shields.io/pypi/pyversions/prisma-flow)](https://pypi.org/project/prisma-flow/)
[![Package Version](https://img.shields.io/pypi/v/prisma-flow?color=blue)](https://pypi.org/project/prisma-flow/)
![License](https://img.shields.io/pypi/l/prisma-flow?color=blue)

`prisma-flow` is a lightweight Python package for generating PRISMA-style flow
diagrams for evidence synthesis workflows.

PRISMA means **Preferred Reporting Items for Systematic reviews and
Meta-Analyses**. `prisma-flow` is an independent Python implementation for
generating diagrams based on PRISMA 2020 flow diagram structures; it is not the
PRISMA reporting guideline itself and is not affiliated with or endorsed by the
PRISMA Executive.

Unlike Graphviz-based tools, `prisma-flow` does not require system-level graph
layout binaries. Unlike Mermaid-based tools, it does not require Node or Mermaid
CLI. The default renderer is a pure-Python, template-based SVG generator.

The project is designed for systematic reviews, scoping reviews, evidence
syntheses, and literature review workflows.

## Features

- Pure-Python SVG rendering by default
- Standalone HTML export
- Mermaid text export without Mermaid CLI
- JSON input/output in the base install
- Optional YAML input/output via `prisma-flow[yaml]`
- Optional PNG method that clearly reports the missing optional dependency
- Inline SVG display in notebook frontends
- Python API and `prisma-flow` command-line interface
- PRISMA count validation with errors and warnings

## Installation

```bash
pip install prisma-flow
```

or:

```bash
uv add prisma-flow
```

Optional YAML support:

```bash
uv add "prisma-flow[yaml]"
```

Optional PNG support, when a supported backend is added:

```bash
uv add "prisma-flow[png]"
```

## Python API

```python
from prismaflow import new_review

flow = new_review(
    records_identified_databases=1240,
    records_identified_registers=50,
    records_removed_duplicates=210,
    records_removed_automation=0,
    records_removed_other=0,
    records_screened=1080,
    records_excluded=950,
    reports_sought=130,
    reports_not_retrieved=10,
    reports_assessed=120,
    reports_excluded={
        "Wrong population": 30,
        "Wrong intervention": 20,
        "Wrong outcome": 15,
        "Not primary research": 15,
    },
    studies_included=40,
)

report = flow.validate()
print(report.format_text())

flow.to_svg("prisma.svg")
flow.to_html("prisma.html")
flow.to_mermaid("prisma.mmd")
flow.to_json("review.json")
```

## CLI usage

Validate input data:

```bash
prisma-flow validate examples/basic_new_review.json
```

Render SVG:

```bash
prisma-flow render examples/basic_new_review.json -o prisma.svg
```

Render other base-install formats:

```bash
prisma-flow render examples/basic_new_review.json --format html -o prisma.html
prisma-flow render examples/basic_new_review.json --format mermaid -o prisma.mmd
```

If validation fails, the CLI prints a report and exits with a non-zero status:

```text
Validation failed:
- records_screened should equal identified records minus removed records. Expected: 1080 Found: 1090
```

## Data model

The v0.1 implementation supports the PRISMA 2020 new-review databases/registers
template:

```python
from prismaflow import (
    EligibilityStage,
    IdentificationStage,
    IncludedStage,
    PrismaFlow,
    PrismaTemplate,
    ScreeningStage,
)

flow = PrismaFlow(
    template=PrismaTemplate.PRISMA_2020_NEW_DATABASES_REGISTERS,
    identification=IdentificationStage(
        records_identified_databases=1240,
        records_identified_registers=50,
    ),
    screening=ScreeningStage(
        records_removed_duplicates=210,
        records_removed_automation=0,
        records_removed_other=0,
        records_screened=1080,
        records_excluded=950,
    ),
    eligibility=EligibilityStage(
        reports_sought=130,
        reports_not_retrieved=10,
        reports_assessed=120,
        reports_excluded={"Wrong population": 30},
    ),
    included=IncludedStage(studies_included=40),
)
```

## Dependency policy

SVG, HTML, Mermaid, and JSON work with the base install. YAML is optional. PNG
is intentionally optional and not implemented as a required renderer in v0.1.

The package does **not** require Graphviz, Cairo, CairoSVG, Node, Mermaid CLI,
Inkscape, Playwright, browser engines, Matplotlib, or Plotly.

## PRISMA acknowledgement and citation

The PRISMA 2020 reporting guideline, checklist, and flow diagram templates were
developed by the PRISMA 2020 authors and are maintained through the PRISMA
Executive. When using PRISMA-style diagrams in reports, manuscripts, or
presentations, cite the original PRISMA 2020 publications:

- Page MJ, McKenzie JE, Bossuyt PM, Boutron I, Hoffmann TC, Mulrow CD, et al.
  The PRISMA 2020 statement: an updated guideline for reporting systematic
  reviews. _BMJ_. 2021;372:n71. doi:
  [10.1136/bmj.n71](https://doi.org/10.1136/bmj.n71).
- Page MJ, Moher D, Bossuyt PM, Boutron I, Hoffmann TC, Mulrow CD, et al. PRISMA
  2020 explanation and elaboration: updated guidance and exemplars for reporting
  systematic reviews. _BMJ_. 2021;372:n160. doi:
  [10.1136/bmj.n160](https://doi.org/10.1136/bmj.n160).

See the official [PRISMA website](https://www.prisma-statement.org/) and
[PRISMA 2020 flow diagram page](https://www.prisma-statement.org/prisma-2020-flow-diagram)
for source templates and usage guidance.

## Development

```bash
conda env create -f conda/dev.yaml
conda activate prismaflow
poetry config virtualenvs.create false
poetry install --extras "dev yaml"
```

Run the same workflow through Makim:

```bash
makim tests.linter
makim tests.unit
makim package.build
makim docs.build
makim all.ci
```

## Documentation

The documentation site is built with Quarto:

```bash
quarto render docs
```

Preview locally:

```bash
quarto preview docs
```

## License

BSD-3-Clause.

