Metadata-Version: 2.5
Name: fyron
Version: 0.3.8
Summary: Fyron is an open-source Python toolkit for interoperable healthcare data and AI workflows. It provides unified access to FHIR data via REST APIs and relational (SQL-backed) FHIR servers, integrates DICOM imaging sources, and enables semantic exploration of clinical narratives using modern language models.
Project-URL: Homepage, https://github.com/bitsandflames/fyron
Project-URL: Repository, https://github.com/bitsandflames/fyron
Project-URL: Documentation, https://fyron.bitsandflames.ai/
Author-email: Bits & Flames <hello@bitsandflames.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: DICOM,FHIR,LLM,NLP,clinical,healthcare
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: dicomweb-client<0.60.0,>=0.59.1
Requires-Dist: fhirpathpy<3.0.0,>=2.1.0
Requires-Dist: pandas<3.0.0,>=2.2.0
Requires-Dist: psycopg<4.0.0,>=3.1.19
Requires-Dist: pydicom<3.0.0,>=2.4.4
Requires-Dist: pyjwt<3.0.0,>=2.9.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.1
Requires-Dist: requests<3.0.0,>=2.32.0
Requires-Dist: retrying<2.0.0,>=1.3.3
Requires-Dist: simpleitk<3.0.0,>=2.3.1
Requires-Dist: tqdm<5.0.0,>=4.66.0
Provides-Extra: all
Requires-Dist: boruta<0.4.0,>=0.3.0; extra == 'all'
Requires-Dist: boto3<2.0.0,>=1.34.0; extra == 'all'
Requires-Dist: highdicom<0.23,>=0.22; extra == 'all'
Requires-Dist: joblib<2.0.0,>=1.3.0; extra == 'all'
Requires-Dist: lifelines<1.0.0,>=0.30.0; extra == 'all'
Requires-Dist: matplotlib<4.0.0,>=3.8.0; extra == 'all'
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'all'
Requires-Dist: opencv-python-headless<5.0.0,>=4.8.0; extra == 'all'
Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == 'all'
Requires-Dist: pyradiomics<3.1.0,>=3.0.1; (python_version < '3.12') and extra == 'all'
Requires-Dist: scikit-learn<2.0.0,>=1.4.0; extra == 'all'
Requires-Dist: scikit-survival<1.0.0,>=0.23.0; extra == 'all'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'all'
Requires-Dist: shap<1.0.0,>=0.45.0; extra == 'all'
Requires-Dist: xgboost<3.0.0,>=2.0.0; extra == 'all'
Provides-Extra: audit
Provides-Extra: boruta
Requires-Dist: boruta<0.4.0,>=0.3.0; extra == 'boruta'
Provides-Extra: curate
Provides-Extra: descriptive
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'descriptive'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'descriptive'
Provides-Extra: dicom-seg
Requires-Dist: highdicom<0.23,>=0.22; extra == 'dicom-seg'
Provides-Extra: excel
Requires-Dist: openpyxl<4.0.0,>=3.1.0; extra == 'excel'
Provides-Extra: explainability
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'explainability'
Requires-Dist: scikit-learn<2.0.0,>=1.4.0; extra == 'explainability'
Requires-Dist: shap<1.0.0,>=0.45.0; extra == 'explainability'
Provides-Extra: feature-selection
Requires-Dist: boruta<0.4.0,>=0.3.0; extra == 'feature-selection'
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'feature-selection'
Requires-Dist: scikit-learn<2.0.0,>=1.4.0; extra == 'feature-selection'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'feature-selection'
Provides-Extra: ml
Requires-Dist: joblib<2.0.0,>=1.3.0; extra == 'ml'
Requires-Dist: matplotlib<4.0.0,>=3.8.0; extra == 'ml'
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'ml'
Requires-Dist: scikit-learn<2.0.0,>=1.4.0; extra == 'ml'
Requires-Dist: xgboost<3.0.0,>=2.0.0; extra == 'ml'
Provides-Extra: radiomics
Requires-Dist: pyradiomics<3.1.0,>=3.0.1; (python_version < '3.12') and extra == 'radiomics'
Provides-Extra: reporting
Provides-Extra: s3
Requires-Dist: boto3<2.0.0,>=1.34.0; extra == 's3'
Provides-Extra: statistics
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'statistics'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'statistics'
Provides-Extra: survival
Requires-Dist: lifelines<1.0.0,>=0.30.0; extra == 'survival'
Requires-Dist: matplotlib<4.0.0,>=3.8.0; extra == 'survival'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'survival'
Provides-Extra: survival-ml
Requires-Dist: lifelines<1.0.0,>=0.30.0; extra == 'survival-ml'
Requires-Dist: matplotlib<4.0.0,>=3.8.0; extra == 'survival-ml'
Requires-Dist: scikit-survival<1.0.0,>=0.23.0; extra == 'survival-ml'
Requires-Dist: scipy<2.0.0,>=1.11.0; extra == 'survival-ml'
Provides-Extra: validation
Requires-Dist: numpy<2.0.0,>=1.26.0; extra == 'validation'
Requires-Dist: scikit-learn<2.0.0,>=1.4.0; extra == 'validation'
Provides-Extra: visualization
Requires-Dist: opencv-python-headless<5.0.0,>=4.8.0; extra == 'visualization'
Description-Content-Type: text/markdown

![Fyron Banner](images/FYRON-Banner.png)

<div align="center">
  <a href="https://pypi.org/project/fyron/"><img alt="PyPI" src="https://img.shields.io/pypi/v/fyron?color=0B0B0C" /></a>
  <img alt="Python" src="https://img.shields.io/pypi/pyversions/fyron?color=0B0B0C" />
  <a href="https://github.com/bitsandflames/fyron/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/bitsandflames/fyron/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="SECURITY.md"><img alt="Security policy" src="https://img.shields.io/badge/security-policy-0B0B0C" /></a>
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-0B0B0C" /></a>
  <a href="PUBLIC_BETA.md"><img alt="Public beta" src="https://img.shields.io/badge/status-public%20beta-FF6A1A" /></a>
  <img alt="FHIR" src="https://img.shields.io/badge/FHIR-enabled-FF6A1A" />
  <img alt="DICOM" src="https://img.shields.io/badge/DICOM-supported-FF6A1A" />
  <img alt="Survival ML" src="https://img.shields.io/badge/survival%20ML-supported-FF6A1A" />
  <a href="https://fyron.bitsandflames.ai/"><img alt="Docs" src="https://img.shields.io/badge/docs-Fyron-0B0B0C" /></a>
</div>

# Fyron

The research buddy we wished we had when we were starting out.

Healthcare research often starts with a question that matters. Then comes the work nobody put in the study proposal: finding the right data, understanding how a hospital stores it, and getting systems built in different decades to agree on what it means.

An HL7 message is not a research-ready table. A DICOM study is more than a folder of images. FHIR gives data a shared structure, but FHIR servers differ in their profiles, search capabilities, and implementations. With REST endpoints, you need to work through authentication and pagination. With SQL databases, you encounter different dialects, schemas, and local conventions. Across institutions, even familiar fields can carry different meanings. Before the first analysis, there is already a great deal to understand.

Fyron is our way of sharing what we learn along that journey. Built by Bits & Flames, it is an open Python toolkit for healthcare researchers, clinical data scientists, and imaging AI teams. Its current modules help with FHIR REST and SQL access, DICOM workflows, data preparation, cohort construction, image curation, statistical analysis, machine learning, and scientific plotting. Synthetic cohort and imaging examples give you somewhere to learn and test without starting with patient data.

We want Fyron to feel like a knowledgeable colleague beside you: a useful function when you need one, an example that makes the next step clearer, and code you can open to understand the assumptions. It cannot remove every infrastructure barrier or decide which method is right for your study. But it can help make the path less lonely, less repetitive, and easier to share.

[Documentation](https://fyron.bitsandflames.ai/) · [Getting Started](https://fyron.bitsandflames.ai/getting-started/) · [Example Gallery](https://fyron.bitsandflames.ai/example-gallery/) · [Curate](https://fyron.bitsandflames.ai/applications/curate/) · [Citation](#citation)

## Why We Build Fyron

We remember how much there was to learn at the beginning, and we are still learning. Getting data out was only the first step. Then came missing values, inconsistent identifiers, image quality checks, selection criteria, endpoint definitions, statistical assumptions, and the question of whether someone else could reproduce what we had done.

Along the way, useful solutions accumulated in notebooks, small scripts, and conversations with colleagues. Too often, that knowledge stayed inside one project or one team. We build Fyron because the next researcher should not have to start from the same blank page.

Our vision is common ground for the wider healthcare research community: a place to find usable modules, scripts, snippets, and applications, but also to compare approaches, ask questions, and improve methods together. A clinician reviewing images, a student preparing a first cohort, and an engineer connecting hospital systems may need different tools. They should still be able to learn from one another's work.

We like to think of Fyron as a fireplace for research code and shared experience. A place to gather after working through a difficult problem. Bring the script that finally worked, the question you are still wrestling with, or the lesson that could spare someone else a week of trial and error. Around that fireplace, there is room for people just starting out and those with years of experience. You do not have to arrive with a solution to belong.

The warmth comes from people helping one another. The lasting value comes from turning those exchanges into documented examples, tested modules, and tools that researchers can take back to their own work. That is the kind of place we hope to build together.

Take the parts that help you. Use one function, adapt an example, launch Curate for data selection, generate a small synthetic dataset, or assemble a larger workflow. You do not need to adopt all of Fyron to benefit from it, and you do not need to be an experienced developer to help shape it.

We build on the generosity and expertise of the open-source scientific community, including projects such as pandas, scikit-learn, and lifelines. Fyron is a contribution to that shared effort, not a replacement for it. Our experience is a starting point, not the whole picture. We hope researchers across institutions and disciplines will bring the questions, perspectives, and practical lessons that help it grow.

## What Fyron Enables

**Extract → Screen → Analyze → Publish**

| Stage | Useful starting points |
| --- | --- |
| Extract | FHIR REST/SQL queries, FHIRPath extraction, DICOMweb downloads, documents, and local files |
| Screen | Curate image review, cohort joins and endpoints, missingness checks, DICOM/NIfTI QC, BOA features, dataset preparation, and small synthetic cohort/imaging datasets for examples and tests |
| Analyze | Descriptive statistics, regression, survival analysis, classification, feature selection, calibration, and model validation |
| Publish | Matplotlib figures, reporting tables, cohort-flow summaries, and provenance manifests |

Start with the [module guide](https://fyron.bitsandflames.ai/modules/) for the full toolkit map. Individual helpers return familiar DataFrames, dictionaries, model objects, figures, or manifests so the next step stays yours to choose.

## Install

With uv:

```bash
uv add fyron
```

Or with pip:

```bash
pip install fyron
```

Choose extras for the work you need:

| Research task | Install with uv |
| --- | --- |
| Survival analysis | `uv add "fyron[survival]"` |
| Survival ML and censoring-aware validation | `uv add "fyron[survival-ml]"` |
| Classification and validation | `uv add "fyron[ml,validation]"` |
| Local image cohort review | `uv add "fyron[curate]"` |

See [Getting Started](https://fyron.bitsandflames.ai/getting-started/) for dependencies and additional extras. Prefer targeted extras for lean environments. `fyron[all]` provides the full local environment; the radiomics dependency currently requires Python 3.10–3.11.

## Curate

Fyron Curate is our local image cohort review app. Use it to review image quality, screen a dataset, or select an image cohort before analysis, even if the rest of your study uses other software.

![Fyron Curate gallery with synthetic placeholder tiles, selection context, and accepted/rejected review controls](docs/assets/curate-synthetic-gallery.png)

*The actual Curate interface with fictional demo records and generated placeholder tiles. No real medical images or patient data are shown.*

Curate runs through Docker Compose, stores review metadata in PostgreSQL, and exports accepted images without changing the uploaded originals. It helps organize review decisions; your study protocol still defines what should be accepted or rejected.

Install the extra, ensure Docker Desktop or another Docker Compose runtime is running, and launch:

```bash
uv add "fyron[curate]"
fyron curate
```

Open [localhost:5174](http://localhost:5174/), create a cohort, add images or DICOM data, review the samples, and export your selections. Record your selection criteria and the version used so others can understand how the dataset was formed.

For volume-based preview folders:

```bash
uv add "fyron[visualization,curate]"
fyron dataset-curate-previews --input-dir ct_exports/ --output-dir curate_previews/
```

The [Curate documentation](https://fyron.bitsandflames.ai/applications/curate/) explains supported formats, preview generation, review controls, exports, and persistent storage.

**Using Curate for a paper's data selection? Please [cite Fyron](#citation), even if no other Fyron module is used.**

## Example Gallery

Find runnable synthetic workflows in the [Example Gallery](https://fyron.bitsandflames.ai/example-gallery/), from FHIR-to-cohort preparation and imaging QC to survival analysis, validation, and scientific plotting. Start small, inspect the outputs, and adapt the relevant steps to your research question.

<p align="center">
  <img alt="Risk score distribution" src="docs/assets/dummy-risk-score-distribution.png" width="42%" />
  <img alt="Forest estimates" src="docs/assets/dummy-forest-estimates.png" width="42%" />
</p>

## Built To Evolve

Healthcare research, Python tooling, and AI-assisted development are changing quickly. We want Fyron's direction to be informed by researchers using it in different settings: what helps, what does not transfer, and what is missing. Shared experience and careful review can turn useful ideas into documented, tested building blocks, rather than simply adding more code.

Fyron is in public beta. APIs may change, and mistakes can be found. Our commitment is to review feedback, test changes, document corrections and migration guidance, and say when earlier results need recalculation. We cannot promise permanent API stability or automatic scientific correctness. Pin versions for studies and keep the methods and parameters alongside your outputs.

See [Public Beta](PUBLIC_BETA.md), [API Design](https://fyron.bitsandflames.ai/api-design/), [Support](SUPPORT.md), and [release guidance](https://fyron.bitsandflames.ai/open-source-release-checklist/).

## Built For Responsible Research

Fyron is local-first and sends no telemetry on import. External calls happen when you configure clients or commands. Helpers keep clinical assumptions explicit, but software cannot choose an appropriate study design or validate a scientific conclusion for you.

Fyron is not a medical device, treatment recommendation system, or compliance platform. Researchers remain responsible for approvals, privacy, data governance, and validation. See [Security](SECURITY.md) and [Using Fyron In Research](https://fyron.bitsandflames.ai/repository-trust/).

## Build With The Research Community

Whether you work in a hospital, university, research group, or independently, your perspective is welcome. You do not need to be an experienced developer or arrive with finished code. A recurring research problem, a question about a method, or an example of where a workflow breaks can help us understand what needs to improve.

Have a useful snippet, a clearer example, a bug reproduction, or a tool that already solves the problem well? Share it. We would like to learn from your approach, discuss where it fits, and build on existing work rather than duplicate it. Contributions to documentation, testing, and scientific review matter alongside new modules.

Use [GitHub issues](https://github.com/bitsandflames/fyron/issues) for problems and ideas, or submit a pull request following [CONTRIBUTING.md](CONTRIBUTING.md). Keep shared examples synthetic and free of patient-identifying data, credentials, and private endpoints. Small, focused contributions are welcome; you do not need to propose a new framework.

Our hope is that each shared improvement makes the next study a little easier, including studies outside our own teams.

## Citation

If Fyron contributes to your paper, thesis, or other scientific work, please cite it. This includes using Fyron Curate for image review, dataset selection, or cohort screening, even when downstream analysis uses other software.

> Hosch, René, Borys, Katarzyna, and Woolley, Justin (2026).
> *Fyron: An Open Research Companion for Healthcare Interoperability, Data Science and AI*
> (Version 0.3.8) [Computer software].
> https://github.com/bitsandflames/fyron

Cite the version actually used. [CITATION.cff](CITATION.cff) provides machine-readable metadata; the [documentation](https://fyron.bitsandflames.ai/#citation) includes BibTeX. No DOI has been assigned yet. Curate uses the Fyron software citation, not a separate publication.

Citation is a scholarly request, not an additional license condition.

## License

MIT. See [LICENSE](LICENSE).
