prisma-flow 0.2.0

Lightweight Python tools for generating PRISMA-style flow diagrams without system dependencies.

prisma-flow

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

pip install prisma-flow

or:

uv add prisma-flow

Optional YAML support:

uv add "prisma-flow[yaml]"

Optional PNG support, when a supported backend is added:

uv add "prisma-flow[png]"

Python API

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:

prisma-flow validate examples/basic_new_review.json

Render SVG:

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

Render other base-install formats:

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:

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:

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

See the official PRISMA website and PRISMA 2020 flow diagram page for source templates and usage guidance.

Development

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:

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

Documentation

The documentation site is built with Quarto:

quarto render docs

Preview locally:

quarto preview docs

License

BSD-3-Clause.