spirotrace 0.0.1__py3-none-any.whl

spirotrace/__init__.py

@@ -0,0 +1,3 @@
+"""spirotrace: traceable extraction of lung function data from printed and scanned reports."""
+
+__version__ = "0.0.1"

spirotrace/checks/__init__.py

@@ -0,0 +1,5 @@
+"""Rule registry. Every check is a named rule with an id, a layer (ocr, range, layout, image, consistency, gli,
+cohort, free_text), a severity and a one-sentence rationale, and can be switched off by name.
+
+Not implemented yet.
+"""

spirotrace/cli.py

@@ -0,0 +1,32 @@
+"""Command line entry point: spirotrace <command>."""
+import argparse
+import sys
+
+from . import __version__
+
+COMMANDS = {
+    "init": "create a study project folder",
+    "run": "extract and check all reports in a project",
+    "review": "open the local review app",
+    "export": "write the dataset, data dictionary and QC report",
+    "template": "draft, test or survey a layout template",
+    "eval": "evaluate against a manually coded reference sample",
+}
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="spirotrace", description=__doc__)
+    ap.add_argument("--version", action="version", version=f"spirotrace {__version__}")
+    sub = ap.add_subparsers(dest="command", metavar="command")
+    for name, help_ in COMMANDS.items():
+        sub.add_parser(name, help=help_)
+    a = ap.parse_args(argv)
+    if a.command is None:
+        ap.print_help()
+        return 0
+    print(f"spirotrace {__version__}: '{a.command}' is not implemented yet.")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spirotrace/derive/__init__.py

@@ -0,0 +1,5 @@
+"""Derived variables computed from reviewed values only: GLI recalculation (rspiro), ATS/ERS 2022 pattern,
+severity, PRISm, bronchodilator response. Each derived value records the observations it came from.
+
+Not implemented yet.
+"""

spirotrace/evaluate/__init__.py

@@ -0,0 +1,5 @@
+"""Reference-standard evaluation: sampling, coding sheets, agreement and adjudication, accuracy, flag
+sensitivity and silent errors, ablation by check layer.
+
+Not implemented yet.
+"""

spirotrace/ingest/__init__.py

@@ -0,0 +1,4 @@
+"""Read each PDF once: page rotation and deskew, the text layer or an OCR engine, page images; cached by file hash.
+
+Not implemented yet.
+"""

spirotrace/layouts/__init__.py

@@ -0,0 +1,6 @@
+"""Layout templates (YAML: geometry and vocabulary only), page classification, table, field and free-text readers.
+
+Behaviour belongs in Python: a layout quirk is a named, tested handler that a template switches on.
+
+Not implemented yet.
+"""

spirotrace/privacy/__init__.py

@@ -0,0 +1,4 @@
+"""Masking and the export guard: everything written to share/ passes through here.
+
+Not implemented yet.
+"""

spirotrace/review/__init__.py

@@ -0,0 +1,4 @@
+"""Local review app (served on 127.0.0.1 only). Every reviewer action is appended to an event log.
+
+Not implemented yet.
+"""

spirotrace-0.0.1.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.1
+Name: spirotrace
+Version: 0.0.1
+Summary: Traceable extraction of lung function data from printed and scanned reports
+Author: Kirsty Hawke
+Project-URL: Homepage, https://github.com/hawkek/spirotrace
+Project-URL: Issues, https://github.com/hawkek/spirotrace/issues
+Keywords: spirometry,lung function,PDF extraction,OCR,data quality,GLI
+Classifier: Development Status :: 1 - Planning
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest >=7 ; extra == 'dev'
+
+# spirotrace
+
+**Traceable extraction of lung function data from printed and scanned reports.**
+
+> Status: early development. Nothing here is ready for use yet. The working prototype that this package replaces is not public; this repository is being built up from it module by module, with tests.
+
+## Statement of need
+
+Lung function results (spirometry, lung volumes, gas transfer) often reach researchers only as printed or scanned PDF reports, not as structured data. Typing them by hand is slow and error-prone, and generic PDF or OCR extraction gives values with no indication of which ones are wrong.
+
+spirotrace turns such reports into an audited, analysis-ready dataset with a measured error rate:
+
+- **Extraction.** Report layouts are described in template files (geometry and vocabulary); one reader handles every layout.
+- **Auditability.** Every value keeps its raw text, its position on the page, how it was read, and every human correction made to it (who, when, before, after).
+- **Physiology-informed checks.** Values are checked against each other and against reference equations (for example, the printed z-score against a GLI recalculation, FEV1/FVC against FEV1 and FVC, LLN against the sign of the z-score), so errors that look like plausible numbers are still caught.
+- **Measured reliability.** Built-in tools compare the extraction with a blinded manual reference sample and report accuracy, flag sensitivity and residual (silent) errors.
+- **Local by default.** Everything runs on the user's machine. Nothing is uploaded; there is no telemetry.
+
+Similar tools exist ([PFT-Extractor](https://github.com/lindseyboulet/PFT-Extractor), an R app for Vmax reports; [pft-extractor](https://github.com/Automate-Medical/pft-extractor), a cloud pipeline using Amazon Textract). Neither describes validation of the extracted values or detection of extraction errors.
+
+## Planned scope
+
+| Tier | Contents |
+| --- | --- |
+| Research MVP | Two report layouts, deterministic extraction, provenance on every value, core checks, review corrections as an event log, derived variables (ATS/ERS 2022 pattern, severity, PRISm, bronchodilator response) after review, GLI recalculation via [rspiro](https://cran.r-project.org/package=rspiro), reference-standard evaluation |
+| v1.0 | Add-your-own layout templates, a local browser review app, documentation |
+| Later | Installers for non-programmers, template editor, further OCR engines |
+
+## Data protection
+
+spirotrace is meant for clinical reports. Please:
+
+- **never** attach a report, a screenshot of one, or extracted values to an issue or pull request;
+- report layout problems with the masked, structure-only survey output instead (instructions will be in the docs);
+- check that your ethics and data-access approvals cover your use.
+
+Outputs written to a project's `share/` folder are masked or aggregate by default. Whether any file may be shared is a decision for your study's governance, not something the software can certify.
+
+## Installation
+
+Not yet. When the first usable release is out: `pip install spirotrace`.
+
+## Citation
+
+See [CITATION.cff](CITATION.cff). A software paper is planned.
+
+## Licence
+
+To be confirmed (an OSI-approved permissive licence is intended).

spirotrace-0.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+spirotrace/__init__.py,sha256=f144UATiXymL2-1UxOOP1mQpmW6MZxNnwoVc4E6OOlg,118
+spirotrace/cli.py,sha256=VtT9I4Etqq8fj90gQaYmZb9zg8Zzhd-Nmkk9POnNhig,1025
+spirotrace/checks/__init__.py,sha256=hmOqjq1o5xTFArp8ONF8ZhWgOxkkFt03Wi223ia18Po,232
+spirotrace/derive/__init__.py,sha256=VIn8WKuBlNLXdwwSUzO37SqPRqtal2IPTaD6dLz36pg,233
+spirotrace/evaluate/__init__.py,sha256=zM-CwRzddPtoMqt1Zzur-dZtArBJs6YhxmympqlfyoI,184
+spirotrace/ingest/__init__.py,sha256=lthu3IhWeX5L_KW6UoSGKWpdwKBGwPlrWxYZYr6BcYo,142
+spirotrace/layouts/__init__.py,sha256=EwxDPzv5Si4KLKi4hJkR-7l4yYVUGoT4xZvkKI0bXJM,242
+spirotrace/privacy/__init__.py,sha256=r4Y9YbeWSnfOGUhsKRJKZo9bC0f2jbLXW4qEWvJk-qg,109
+spirotrace/review/__init__.py,sha256=wKKZyABHWFVxl8CtrjPu2E29clI53KqdLQB4jBS7oKE,125
+spirotrace-0.0.1.dist-info/METADATA,sha256=Rfr0Lfo3Efg7w18IAcigaSm7MmhdCSgvU4Y7lHiXCdU,3993
+spirotrace-0.0.1.dist-info/WHEEL,sha256=uJjSjqPgdWYN2DV9Rmm5KOx1XdVgjoWyzqfTL-hbUxM,91
+spirotrace-0.0.1.dist-info/entry_points.txt,sha256=pqlOwDoV-QMhOJggyWl2sil1LIe-NW5r-SjyEUkpgbs,51
+spirotrace-0.0.1.dist-info/top_level.txt,sha256=LDUMb2gQyG31_uwRw_IZZ0AHPmIKIzT1BnJxAexPEIA,11
+spirotrace-0.0.1.dist-info/RECORD,,

spirotrace-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (68.1.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spirotrace-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spirotrace = spirotrace.cli:main

spirotrace-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+spirotrace