Metadata-Version: 2.4
Name: aion-clinical
Version: 1.0.5
Summary: Formal temporal and causal structure for consistent clinical data across systems.
Author-email: Friedhelm Matten <licensing@iscad-it.de>
License: EUPL-1.2
Project-URL: Homepage, https://codeberg.org/fm2-project/aion
Project-URL: Repository, https://codeberg.org/fm2-project/aion
Project-URL: Documentation, https://codeberg.org/fm2-project/aion/wiki
Project-URL: Bug Tracker, https://codeberg.org/fm2-project/aion/issues
Project-URL: Changelog, https://codeberg.org/fm2-project/aion/src/branch/main/CHANGELOG.md
Keywords: FHIR,HL7,clinical-informatics,formal-methods,Allen-algebra,temporal-logic,differential-privacy,causal-inference,openEHR,health-informatics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1
Provides-Extra: fhir
Requires-Dist: fhir.resources>=7.0; extra == "fhir"
Provides-Extra: db
Requires-Dist: sqlalchemy>=2.0; extra == "db"
Requires-Dist: alembic>=1.13; extra == "db"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn[standard]>=0.28; extra == "api"
Provides-Extra: nlp
Requires-Dist: sentence-transformers>=2.2; extra == "nlp"
Provides-Extra: causal
Requires-Dist: pgmpy>=0.1.25; extra == "causal"
Provides-Extra: formal
Requires-Dist: z3-solver>=4.12; extra == "formal"
Provides-Extra: reports
Requires-Dist: pandas>=2.0; extra == "reports"
Requires-Dist: openpyxl>=3.1; extra == "reports"
Requires-Dist: jinja2>=3.1; extra == "reports"
Provides-Extra: all
Requires-Dist: fhir.resources>=7.0; extra == "all"
Requires-Dist: sqlalchemy>=2.0; extra == "all"
Requires-Dist: alembic>=1.13; extra == "all"
Requires-Dist: fastapi>=0.110; extra == "all"
Requires-Dist: uvicorn[standard]>=0.28; extra == "all"
Requires-Dist: pandas>=2.0; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: jinja2>=3.1; extra == "all"
Requires-Dist: z3-solver>=4.12; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: hypothesis>=6.0; extra == "dev"
Requires-Dist: coverage>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: networkx>=3.0; extra == "dev"
Requires-Dist: pydantic>=2.0; extra == "dev"

# AION — Structural Consistency for Clinical Data

Formal temporal and causal structure for consistent clinical data across systems.

[![Tests](https://img.shields.io/badge/tests-326%20passing-brightgreen)](https://codeberg.org/fm2-project/aion)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-EUPL--1.2-blue)](LICENSE)
[![FHIR R4](https://img.shields.io/badge/FHIR-R4-orange)](https://hl7.org/fhir/R4/)
[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.19548857-blue)](https://doi.org/10.5281/zenodo.19548857)

---

Clinical data systems often produce inconsistent results.

Not because of missing interfaces —  
but because **time, semantics and causality are not modelled consistently**.

AION makes clinical data **consistent and verifiable** across systems.

It provides a formal, executable structure to:

- represent clinical events over time  
- define and validate relationships between them  
- ensure consistent interpretation across systems  
- enable reproducible analytics and reliable AI  

Most systems exchange clinical data.

AION ensures that this data is interpreted consistently.

---

## Quick Start

```bash
pip install aion-clinical
```

```python
from aion.core import Interval, classify
import datetime

dt = lambda h: datetime.datetime(2024, 1, 1, h, 0)

anaesthesia = Interval(dt(7), dt(12))
operation   = Interval(dt(8), dt(11))

print(classify(anaesthesia, operation))
# -> AllenRelation.CONTAINS
```

---

## Why AION?

Most systems can exchange clinical data.

The harder problem begins afterwards:

- data is interpreted differently across systems
- temporal relations remain implicit
- causal assumptions are hidden in project-specific logic
- analytics become difficult to compare and reproduce

AION addresses this structural layer directly.

Instead of modelling isolated data points only, AION models:

- **intervals instead of points**
- **relations instead of implicit assumptions**
- **causal structures instead of static data**
- **verifiable consistency instead of hidden transformation logic**

---

## What is AION?

AION is a formal, executable model for clinical information systems.

It generalises earlier formal models (FM-1, FM-2 / CAIRN)  
into a domain-independent structure for clinical data.

---

## Core Capabilities

### Temporal Model
- Complete Allen interval algebra (13 relations)
- Fuzzy intervals with probabilistic reasoning

### Data Model
- Universal clinical event model (6-tuple)
- Type system with hierarchy and schema evolution

### Query & Analytics
- Cohort algebra
- Temporal pattern languages

### Causal Inference
- Causal graphs
- Do-operator
- Structure learning

### AI Integration
- Formal AI component model
- Explainability (Shapley, counterfactuals)

### Privacy
- Differential privacy (Laplace / Gaussian)
- Federated computation

### Interoperability
- FHIR mapping via structural homomorphism

---

### Example: Cohort Query

```python
from aion.query.cohort import query_event_sequence

q = query_event_sequence("Diagnosis", "Procedure")
cohort = q.evaluate(ctx)
```

---

### Example: Causal Analysis

```python
from aion.causal.graph import CausalGraph
from aion.causal.do import DoOperator

g = CausalGraph()
g.add_edge("Diagnosis", "Procedure")

do = DoOperator(g, data)
result = do.intervene("Procedure", "Outcome")
```

---

## Test Suite

```bash
pytest aion/tests/
# 326 tests, ~2s runtime
```

---

## Architecture

```text
aion/
├── core/          Allen algebra (13 relations), type system σ(τ),
│                  event 6-tuple, fuzzy intervals, process DAG
├── abstraction/   Episode formation B_{Φ,Δ}, clinical trajectories
├── query/         Cohort algebra, RTP patterns, TCFG, predicates
├── causal/        Causal graph, do-operator, backdoor adjustment,
│                  PC algorithm, bootstrap structure learning
├── privacy/       ε-DP Laplace/Gaussian, federated model, LDP
├── ai/            AI components A_l = (X,Y,f_θ,L,θ*), Π_l operator,
│                  feature extraction Ψ, risk estimation
├── explain/       Shapley attribution, counterfactual Δ*_cf,
│                  sufficient explanation S*_suf, Π_l^+ gate
├── schema/        Versioned type system, 7 schema change ops,
│                  migration function μ_{v→v'}
└── adapters/
    └── fhir/      Structural homomorphism (h_T, h_σ), Q_map index
```

---

## Key Concepts

### Event 6-Tuple (AION §5)

```python
e = (p, a, τ, [t^B, t^E], α, ρ)
```

- `p` patient, `a` stay, `τ` type, `[t^B,t^E]` interval, `α` attributes, `ρ` references

---

## Positioning

AION is not:

- a data format
- a data warehouse
- a FHIR replacement

AION is:

> **the structural consistency layer beneath clinical data systems**

---

## License & Citation

**EUPL-1.2** — open source. Commercial licence: `licensing@iscad-it.de`

```bibtex
@software{aion2026,
  title  = {AION: Algebraic Interval Ontology for Clinical Networks},
  author = {Matten, Friedhelm},
  year   = {2026},
  url    = {https://codeberg.org/fm2-project/aion},
  doi    = {10.5281/zenodo.19548857}
}
```

© Friedhelm Matten, ISCaD GmbH
