moseslukeprismagraphpy 0.1.0__tar.gz

moseslukeprismagraphpy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moses Luke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

moseslukeprismagraphpy-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: moseslukeprismagraphpy
+Version: 0.1.0
+Summary: Create PRISMA 2020 systematic review flow diagrams in Python (PNG, SVG, PDF and interactive HTML).
+Author: Moses Luke
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Moses-L/prismaflow
+Project-URL: Issues, https://github.com/Moses-L/prismaflow/issues
+Keywords: PRISMA,PRISMA 2020,systematic review,meta-analysis,flow diagram,evidence synthesis
+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: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: graphviz>=0.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# moseslukeprismagraphpy
+
+Create **PRISMA 2020** systematic review flow diagrams in Python. Give it your screening counts (in code or a CSV) and it produces a publication-ready diagram as PNG, SVG or PDF, plus an **interactive HTML** version in which readers can hover for tooltips and click boxes to open supporting files.
+
+It is built on Graphviz, so it runs in scripts, notebooks and CI pipelines without a browser.
+
+`pip install moseslukeprismagraphpy`, then `import moseslukeprismagraphpy` in Python or run the `prismagraph` command in a terminal. The source lives in the GitHub repository `Moses-L/prismaflow`.
+
+## Why this exists
+
+The [PRISMA2020 R package and Shiny app](https://doi.org/10.1002/cl2.1230) (Haddaway et al., 2022) made PRISMA 2020 diagrams easy for R users. `moseslukeprismagraphpy` offers the same kind of workflow for Python users. It is an independent reimplementation, not a port of that code, and it is not affiliated with the PRISMA group or the R package authors. Please also cite the original tool and the PRISMA 2020 statement if they informed your work (see [Citing](#citing)).
+
+## Features
+
+- PRISMA 2020 layout for new reviews, with optional **previous studies** and **other methods** (websites, organisations, citation searching) arms
+- Downstream numbers (screened, sought, assessed, included totals) are calculated for you, and impossible counts raise a clear error
+- Warns when the number of included reports does not match your assessed and excluded counts
+- CSV template so counts can be shared, versioned and re-run
+- Outputs: PNG, SVG, PDF, interactive HTML, Graphviz DOT
+- Command-line tool and Python API
+
+## Install
+
+```bash
+pip install moseslukeprismagraphpy
+```
+
+`moseslukeprismagraphpy` needs the Graphviz program (not only the Python wrapper):
+
+| System | Command |
+|---|---|
+| Ubuntu / Debian | `sudo apt install graphviz` |
+| macOS | `brew install graphviz` |
+| Windows | Installer from [graphviz.org/download](https://graphviz.org/download/); tick the option to add Graphviz to PATH, then restart the terminal |
+| conda | `conda install -c conda-forge graphviz` |
+
+Until it is on PyPI, install from source: `pip install git+https://github.com/Moses-L/prismaflow`.
+
+## Example output
+
+![Example PRISMA 2020 diagram with previous and other-methods arms](examples/example_full.png)
+
+## Quick start
+
+### From the command line
+
+```bash
+prismagraph template -o my_review.csv        # blank template
+# fill in the n column, then:
+prismagraph draw my_review.csv -o figures/prisma -f png svg html
+prismagraph draw --example -o demo -f png    # built-in worked example
+```
+
+### From Python
+
+```python
+from moseslukeprismagraphpy import PrismaData, render
+
+data = PrismaData(
+    counts={
+        "identified_databases": 1200,
+        "identified_registers": 40,
+        "duplicates": 250,
+        "excluded_automatic": 10,
+        "excluded_screening": 900,
+        "not_retrieved": 5,
+        "new_studies": 40,
+        "new_reports": 47,
+    },
+    reasons_db={"Wrong population": 20, "No outcome of interest": 25, "Wrong design": 15},
+    urls={"identified_databases": "https://osf.io/your-search-strategy"},
+    tooltips={"identified_databases": "PubMed, Embase, CENTRAL; searched 1 Nov 2026"},
+)
+print(data.validate())                       # list of warnings; raises on impossible counts
+render(data, "figures/prisma", formats=["png", "svg", "html"])
+```
+
+## CSV format
+
+Columns: `data, label, n, url, tooltip` (extra columns such as `notes` are ignored).
+
+| `data` value | Meaning |
+|---|---|
+| `identified_databases`, `identified_registers` | Records identified |
+| `duplicates`, `excluded_automatic`, `excluded_other` | Records removed before screening |
+| `excluded_screening` | Records excluded at title/abstract |
+| `not_retrieved` | Reports not retrieved |
+| `reason_db` | One row per full-text exclusion reason: put the reason in `label` and the count in `n` |
+| `new_studies`, `new_reports` | Studies and reports included |
+| `previous_studies`, `previous_reports` | Turns on the previous-version arm |
+| `other_websites`, `other_organisations`, `other_citation_searching` | Turns on the other-methods arm |
+| `other_sought`, `other_not_retrieved`, `reason_other` | Other-methods retrieval and exclusions |
+| `screened`, `sought`, `assessed`, `excluded_fulltext`, `other_assessed`, `other_excluded`, `total_studies` | Calculated boxes: leave `n` empty and use only `url` and `tooltip` |
+
+## Interactive HTML
+
+Add a `url` and/or `tooltip` to any row. In the HTML output, hovering shows the tooltip and clicking opens the link. SVG and PDF keep the links too; PNG does not. Link to your own protocols, search strategies or lists of DOIs. Avoid linking to exported database records or abstracts, because database terms of use and copyright may not allow sharing them.
+
+## Limitations
+
+- Phase labels ("Identification", "Screening", "Included") are horizontal boxes, not the rotated side banners of the official template.
+- Layout is automatic. Very long exclusion-reason lists make wide boxes, so keep reason text short.
+- Only the new-review templates with previous and other-methods arms are implemented. Please open an issue if you need something else.
+
+## Examples
+
+The `examples/` folder has a filled-in `example.csv`, a blank `template.csv`, and the matching PNG, SVG and interactive HTML output.
+
+## Development
+
+```bash
+git clone https://github.com/Moses-L/prismaflow && cd prismaflow
+pip install -e ".[dev]"
+pytest
+```
+
+## Citing
+
+If you use `moseslukeprismagraphpy`, please cite this software (see `CITATION.cff`) and the PRISMA 2020 statement:
+
+- Page MJ, McKenzie JE, Bossuyt PM, et al. The PRISMA 2020 statement: an updated guideline for reporting systematic reviews. *BMJ* 2021;372:n71. https://doi.org/10.1136/bmj.n71
+- Haddaway NR, Page MJ, Pritchard CC, McGuinness LA. PRISMA2020: An R package and Shiny app for producing PRISMA 2020-compliant flow diagrams, with interactivity for optimised digital transparency and Open Synthesis. *Campbell Systematic Reviews* 2022;18:e1230. https://doi.org/10.1002/cl2.1230
+
+## Licence
+
+MIT. See `LICENSE`.

moseslukeprismagraphpy-0.1.0/README.md

@@ -0,0 +1,126 @@
+# moseslukeprismagraphpy
+
+Create **PRISMA 2020** systematic review flow diagrams in Python. Give it your screening counts (in code or a CSV) and it produces a publication-ready diagram as PNG, SVG or PDF, plus an **interactive HTML** version in which readers can hover for tooltips and click boxes to open supporting files.
+
+It is built on Graphviz, so it runs in scripts, notebooks and CI pipelines without a browser.
+
+`pip install moseslukeprismagraphpy`, then `import moseslukeprismagraphpy` in Python or run the `prismagraph` command in a terminal. The source lives in the GitHub repository `Moses-L/prismaflow`.
+
+## Why this exists
+
+The [PRISMA2020 R package and Shiny app](https://doi.org/10.1002/cl2.1230) (Haddaway et al., 2022) made PRISMA 2020 diagrams easy for R users. `moseslukeprismagraphpy` offers the same kind of workflow for Python users. It is an independent reimplementation, not a port of that code, and it is not affiliated with the PRISMA group or the R package authors. Please also cite the original tool and the PRISMA 2020 statement if they informed your work (see [Citing](#citing)).
+
+## Features
+
+- PRISMA 2020 layout for new reviews, with optional **previous studies** and **other methods** (websites, organisations, citation searching) arms
+- Downstream numbers (screened, sought, assessed, included totals) are calculated for you, and impossible counts raise a clear error
+- Warns when the number of included reports does not match your assessed and excluded counts
+- CSV template so counts can be shared, versioned and re-run
+- Outputs: PNG, SVG, PDF, interactive HTML, Graphviz DOT
+- Command-line tool and Python API
+
+## Install
+
+```bash
+pip install moseslukeprismagraphpy
+```
+
+`moseslukeprismagraphpy` needs the Graphviz program (not only the Python wrapper):
+
+| System | Command |
+|---|---|
+| Ubuntu / Debian | `sudo apt install graphviz` |
+| macOS | `brew install graphviz` |
+| Windows | Installer from [graphviz.org/download](https://graphviz.org/download/); tick the option to add Graphviz to PATH, then restart the terminal |
+| conda | `conda install -c conda-forge graphviz` |
+
+Until it is on PyPI, install from source: `pip install git+https://github.com/Moses-L/prismaflow`.
+
+## Example output
+
+![Example PRISMA 2020 diagram with previous and other-methods arms](examples/example_full.png)
+
+## Quick start
+
+### From the command line
+
+```bash
+prismagraph template -o my_review.csv        # blank template
+# fill in the n column, then:
+prismagraph draw my_review.csv -o figures/prisma -f png svg html
+prismagraph draw --example -o demo -f png    # built-in worked example
+```
+
+### From Python
+
+```python
+from moseslukeprismagraphpy import PrismaData, render
+
+data = PrismaData(
+    counts={
+        "identified_databases": 1200,
+        "identified_registers": 40,
+        "duplicates": 250,
+        "excluded_automatic": 10,
+        "excluded_screening": 900,
+        "not_retrieved": 5,
+        "new_studies": 40,
+        "new_reports": 47,
+    },
+    reasons_db={"Wrong population": 20, "No outcome of interest": 25, "Wrong design": 15},
+    urls={"identified_databases": "https://osf.io/your-search-strategy"},
+    tooltips={"identified_databases": "PubMed, Embase, CENTRAL; searched 1 Nov 2026"},
+)
+print(data.validate())                       # list of warnings; raises on impossible counts
+render(data, "figures/prisma", formats=["png", "svg", "html"])
+```
+
+## CSV format
+
+Columns: `data, label, n, url, tooltip` (extra columns such as `notes` are ignored).
+
+| `data` value | Meaning |
+|---|---|
+| `identified_databases`, `identified_registers` | Records identified |
+| `duplicates`, `excluded_automatic`, `excluded_other` | Records removed before screening |
+| `excluded_screening` | Records excluded at title/abstract |
+| `not_retrieved` | Reports not retrieved |
+| `reason_db` | One row per full-text exclusion reason: put the reason in `label` and the count in `n` |
+| `new_studies`, `new_reports` | Studies and reports included |
+| `previous_studies`, `previous_reports` | Turns on the previous-version arm |
+| `other_websites`, `other_organisations`, `other_citation_searching` | Turns on the other-methods arm |
+| `other_sought`, `other_not_retrieved`, `reason_other` | Other-methods retrieval and exclusions |
+| `screened`, `sought`, `assessed`, `excluded_fulltext`, `other_assessed`, `other_excluded`, `total_studies` | Calculated boxes: leave `n` empty and use only `url` and `tooltip` |
+
+## Interactive HTML
+
+Add a `url` and/or `tooltip` to any row. In the HTML output, hovering shows the tooltip and clicking opens the link. SVG and PDF keep the links too; PNG does not. Link to your own protocols, search strategies or lists of DOIs. Avoid linking to exported database records or abstracts, because database terms of use and copyright may not allow sharing them.
+
+## Limitations
+
+- Phase labels ("Identification", "Screening", "Included") are horizontal boxes, not the rotated side banners of the official template.
+- Layout is automatic. Very long exclusion-reason lists make wide boxes, so keep reason text short.
+- Only the new-review templates with previous and other-methods arms are implemented. Please open an issue if you need something else.
+
+## Examples
+
+The `examples/` folder has a filled-in `example.csv`, a blank `template.csv`, and the matching PNG, SVG and interactive HTML output.
+
+## Development
+
+```bash
+git clone https://github.com/Moses-L/prismaflow && cd prismaflow
+pip install -e ".[dev]"
+pytest
+```
+
+## Citing
+
+If you use `moseslukeprismagraphpy`, please cite this software (see `CITATION.cff`) and the PRISMA 2020 statement:
+
+- Page MJ, McKenzie JE, Bossuyt PM, et al. The PRISMA 2020 statement: an updated guideline for reporting systematic reviews. *BMJ* 2021;372:n71. https://doi.org/10.1136/bmj.n71
+- Haddaway NR, Page MJ, Pritchard CC, McGuinness LA. PRISMA2020: An R package and Shiny app for producing PRISMA 2020-compliant flow diagrams, with interactivity for optimised digital transparency and Open Synthesis. *Campbell Systematic Reviews* 2022;18:e1230. https://doi.org/10.1002/cl2.1230
+
+## Licence
+
+MIT. See `LICENSE`.

moseslukeprismagraphpy-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moseslukeprismagraphpy"
+version = "0.1.0"
+description = "Create PRISMA 2020 systematic review flow diagrams in Python (PNG, SVG, PDF and interactive HTML)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Moses Luke" }]
+keywords = ["PRISMA", "PRISMA 2020", "systematic review", "meta-analysis", "flow diagram", "evidence synthesis"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = ["graphviz>=0.20"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+prismagraph = "moseslukeprismagraphpy.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Moses-L/prismaflow"
+Issues = "https://github.com/Moses-L/prismaflow/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

moseslukeprismagraphpy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moseslukeprismagraphpy-0.1.0/src/moseslukeprismagraphpy/__init__.py

@@ -0,0 +1,7 @@
+"""moseslukeprismagraphpy: PRISMA 2020 flow diagrams in Python."""
+
+from .data import PrismaData, example_data
+from .render import build_graph, render, to_html, to_svg
+
+__version__ = "0.1.0"
+__all__ = ["PrismaData", "example_data", "build_graph", "render", "to_html", "to_svg", "__version__"]

moseslukeprismagraphpy-0.1.0/src/moseslukeprismagraphpy/cli.py

@@ -0,0 +1,54 @@
+"""Command-line interface: ``prismagraph template`` and ``prismagraph draw``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .data import PrismaData, example_data
+from .render import ALL_FORMATS, render
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="prismagraph", description="PRISMA 2020 flow diagrams from a CSV.")
+    p.add_argument("--version", action="version", version=f"prismagraph {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    t = sub.add_parser("template", help="write a blank CSV template")
+    t.add_argument("-o", "--output", default="prisma_template.csv")
+
+    d = sub.add_parser("draw", help="draw a diagram from a filled-in CSV")
+    d.add_argument("csv", nargs="?", help="input CSV (omit with --example)")
+    d.add_argument("-o", "--output", default="prisma_flow", help="output path stem (default: prisma_flow)")
+    d.add_argument("-f", "--format", nargs="+", default=["png"], choices=ALL_FORMATS, help="one or more formats")
+    d.add_argument("--dpi", type=int, default=300, help="PNG resolution (default 300)")
+    d.add_argument("--title", default=None)
+    d.add_argument("--example", action="store_true", help="draw the built-in worked example")
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "template":
+        PrismaData.write_template(args.output)
+        print(f"Wrote {args.output}")
+        return 0
+
+    if not args.example and not args.csv:
+        d.error("provide a CSV file or use --example")
+    try:
+        data = example_data() if args.example else PrismaData.from_csv(args.csv)
+        for w in data.validate():
+            print(f"warning: {w}", file=sys.stderr)
+        for path in render(data, args.output, args.format, dpi=args.dpi, title=args.title):
+            print(f"Wrote {path}")
+    except FileNotFoundError as exc:
+        print(f"error: file not found: {exc.filename}", file=sys.stderr)
+        return 1
+    except (ValueError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())