biomodels-client 0.1.0__tar.gz

biomodels_client-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.3
+Name: biomodels-client
+Version: 0.1.0
+Summary: Python client and import tools for the BioModelle API
+Keywords: wearables,apple-health,digital-health,fhir,loinc,physiology,sports-science,health-data,api
+Author: Torben Kimhofer
+License: GPL-3.0-or-later
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Python: >=3.9
+Project-URL: Documentation, https://biomodels.tkimhofer.dev/docs
+Project-URL: Homepage, https://biomodels.tkimhofer.dev
+Project-URL: Repository, https://github.com/tkimhofer/biomodels-client
+Description-Content-Type: text/markdown
+
+# Biomodels Client
+
+Python tools for importing wearable sensor data and interacting with the Biomodels API.
+
+The package provides utilities for importing, querying and analysing sensor data, preparing API payloads, 
+and submitting requests to the BioModelle API.
+
+https://biomodels.tkimhofer.dev/docs
+
+
+### Features
+* Import Apple Health exports (`"export.xml"` or `.zip`)
+* Query and explore sensor data using pandas and SQL
+* Prepare API payloads directly from sensor measurements
+* Submit requests to the BioModelle API
+
+### Installation
+
+```bash
+pip install biomodels-client
+```
+
+
+## Quick Start
+
+### Apple Health Export
+Open the **Health** app on iPhone, tap the profile picture, select **Export All Health Data**. 
+The generated ZIP archive contains an `export.xml` file that can be imported by `biomodels-client`.
+
+### 1. Import Apple Health data
+
+The importer accepts both `export.xml` files and Apple Health ZIP exports.
+
+```python
+from biomodels_client.database import SensorStore
+from biomodels_client.importers.apple_health import AppleHealthImporter
+
+db = SensorStore("wearables.sqlite")
+
+AppleHealthImporter(
+    "/path/to/apple_health_export/export.xml"
+).write_to(db)
+```
+
+### 2. Explore sensor data
+
+```python
+from biomodels_client.database import SensorStore
+
+db = SensorStore("wearables.sqlite")
+
+sources = db.query("""
+SELECT
+    source_name,
+    COUNT(*) AS n,
+    MIN(time_start) AS date_min,
+    MAX(time_end) AS date_max
+FROM measurements
+GROUP BY source_name
+ORDER BY n DESC
+""")
+
+print(sources)
+```
+
+### 3. Calculate TRIMP from wearable data
+
+```python
+from biomodels_client.client import BioModelleClient
+from biomodels_client.database import SensorStore
+
+db = SensorStore("wearables.sqlite")
+
+hr_ruhe = db.estimate_hr_rest(months=12)
+hr_max = db.estimate_hr_max(months=24)
+
+payload = db.trimp_payload(
+    start="2026-06-17 06:00",
+    end="2026-06-18 23:00",
+)
+
+client = BioModelleClient()
+
+result = client.trimp(
+    **payload,
+    geschlecht="m",
+    hr_ruhe=hr_ruhe,
+    hr_max=hr_max,
+)
+
+print(result)
+```
+
+## Example Scripts
+
+### Wearable Sensor Workflow
+
+```text
+examples/
+└── wearable_to_trimp/
+    ├── 01_import_apple_health.py
+    ├── 02_inspect_sensor_store.py
+    ├── 03_sensor_to_trimp.py
+    └── 04_submit_trimp.py
+```
+
+### API Reference
+
+```text
+examples/
+└── api_reference/
+    └── all_endpoints.py
+```
+
+## SensorStore
+
+The `SensorStore` class provides:
+
+```python
+db.select_heart_rate(...)
+db.select_best_heart_rate_source(...)
+
+db.estimate_hr_rest(...)
+db.estimate_hr_max(...)
+
+db.trimp_payload(...)
+
+db.query(...)
+de.execute(...)
+```
+
+for exploration and preparation of wearable sensor data.

biomodels_client-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["uv_build>=0.8.0,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "biomodels-client"
+version = "0.1.0"
+description = "Python client and import tools for the BioModelle API"
+readme = "readme.md"
+requires-python = ">=3.9"
+
+authors = [
+  {name = "Torben Kimhofer"}
+]
+
+license = { text = "GPL-3.0-or-later" }
+
+keywords = [
+  "wearables",
+  "apple-health",
+  "digital-health",
+  "fhir",
+  "loinc",
+  "physiology",
+  "sports-science",
+  "health-data",
+  "api"
+]
+
+dependencies = [
+    "requests",
+    "numpy",
+    "pandas",
+]
+
+[project.urls]
+Homepage = "https://biomodels.tkimhofer.dev"
+Documentation = "https://biomodels.tkimhofer.dev/docs"
+Repository = "https://github.com/tkimhofer/biomodels-client"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "biomodels_client"

biomodels_client-0.1.0/readme.md

@@ -0,0 +1,132 @@
+# Biomodels Client
+
+Python tools for importing wearable sensor data and interacting with the Biomodels API.
+
+The package provides utilities for importing, querying and analysing sensor data, preparing API payloads, 
+and submitting requests to the BioModelle API.
+
+https://biomodels.tkimhofer.dev/docs
+
+
+### Features
+* Import Apple Health exports (`"export.xml"` or `.zip`)
+* Query and explore sensor data using pandas and SQL
+* Prepare API payloads directly from sensor measurements
+* Submit requests to the BioModelle API
+
+### Installation
+
+```bash
+pip install biomodels-client
+```
+
+
+## Quick Start
+
+### Apple Health Export
+Open the **Health** app on iPhone, tap the profile picture, select **Export All Health Data**. 
+The generated ZIP archive contains an `export.xml` file that can be imported by `biomodels-client`.
+
+### 1. Import Apple Health data
+
+The importer accepts both `export.xml` files and Apple Health ZIP exports.
+
+```python
+from biomodels_client.database import SensorStore
+from biomodels_client.importers.apple_health import AppleHealthImporter
+
+db = SensorStore("wearables.sqlite")
+
+AppleHealthImporter(
+    "/path/to/apple_health_export/export.xml"
+).write_to(db)
+```
+
+### 2. Explore sensor data
+
+```python
+from biomodels_client.database import SensorStore
+
+db = SensorStore("wearables.sqlite")
+
+sources = db.query("""
+SELECT
+    source_name,
+    COUNT(*) AS n,
+    MIN(time_start) AS date_min,
+    MAX(time_end) AS date_max
+FROM measurements
+GROUP BY source_name
+ORDER BY n DESC
+""")
+
+print(sources)
+```
+
+### 3. Calculate TRIMP from wearable data
+
+```python
+from biomodels_client.client import BioModelleClient
+from biomodels_client.database import SensorStore
+
+db = SensorStore("wearables.sqlite")
+
+hr_ruhe = db.estimate_hr_rest(months=12)
+hr_max = db.estimate_hr_max(months=24)
+
+payload = db.trimp_payload(
+    start="2026-06-17 06:00",
+    end="2026-06-18 23:00",
+)
+
+client = BioModelleClient()
+
+result = client.trimp(
+    **payload,
+    geschlecht="m",
+    hr_ruhe=hr_ruhe,
+    hr_max=hr_max,
+)
+
+print(result)
+```
+
+## Example Scripts
+
+### Wearable Sensor Workflow
+
+```text
+examples/
+└── wearable_to_trimp/
+    ├── 01_import_apple_health.py
+    ├── 02_inspect_sensor_store.py
+    ├── 03_sensor_to_trimp.py
+    └── 04_submit_trimp.py
+```
+
+### API Reference
+
+```text
+examples/
+└── api_reference/
+    └── all_endpoints.py
+```
+
+## SensorStore
+
+The `SensorStore` class provides:
+
+```python
+db.select_heart_rate(...)
+db.select_best_heart_rate_source(...)
+
+db.estimate_hr_rest(...)
+db.estimate_hr_max(...)
+
+db.trimp_payload(...)
+
+db.query(...)
+de.execute(...)
+```
+
+for exploration and preparation of wearable sensor data.

biomodels_client-0.1.0/src/biomodels_client/client.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from typing import Literal
+import requests
+
+
+class BioModelleClient:
+    api_version = "v1"
+
+    def __init__(
+        self,
+        base_url: str = "https://biomodels.tkimhofer.dev",
+        timeout: int | float = 30,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"accept": "application/json"})
+
+    def endpoint(self, path, versioned: bool = True):
+        path = path.lstrip("/")
+
+        if versioned:
+            return f"{self.base_url}/{self.api_version}/{path}"
+
+        return f"{self.base_url}/{path}"
+
+    def _get(self, path: str, params: dict | None = None, versioned=True) -> dict:
+        r = self.session.get(
+            self.endpoint(path, versioned),
+            # f"{self.base_url}{path}",
+            params=params,
+            timeout=self.timeout,
+        )
+        return self._handle_response(r)
+
+    def _post(
+        self,
+        path: str,
+        params: dict | None = None,
+        payload: dict | None = None,
+        versioned = True
+    ) -> dict:
+        r = self.session.post(
+            self.endpoint(path, versioned),
+            params=params,
+            json=payload,
+            timeout=self.timeout,
+        )
+        return self._handle_response(r)
+
+    @staticmethod
+    def _handle_response(response: requests.Response) -> dict:
+        try:
+            data = response.json()
+        except ValueError:
+            data = response.text
+
+        if not response.ok:
+            raise RuntimeError(
+                f"BioModelle API error {response.status_code}: {data}"
+            )
+
+        return data
+
+    def health(self) -> dict:
+        return self._get("/health", versioned=False)
+
+    def bmi_bsa(self, gewicht_kg: float, groesse_cm: float) -> dict:
+        return self._get(
+            "/body/bmi-bsa",
+            params={
+                "gewicht_kg": gewicht_kg,
+                "groesse_cm": groesse_cm,
+            },
+        )
+
+    def body_shape(
+        self,
+        gewicht_kg: float,
+        groesse_cm: float,
+        taille_cm: float,
+        geschlecht: Literal["m", "w"],
+        huefte_cm: float | None = None,
+        koerperfett_prozent: float | None = None,
+    ) -> dict:
+        params = {
+            "gewicht_kg": gewicht_kg,
+            "groesse_cm": groesse_cm,
+            "taille_cm": taille_cm,
+            "geschlecht": geschlecht,
+        }
+
+        if huefte_cm is not None:
+            params["huefte_cm"] = huefte_cm
+
+        if koerperfett_prozent is not None:
+            params["koerperfett_prozent"] = koerperfett_prozent
+
+        return self._get("/body/body-shape", params=params)
+
+    def visceral_fat(
+        self,
+        gewicht_kg: float,
+        groesse_cm: float,
+        taille_cm: float,
+        geschlecht: Literal["m", "w"],
+        vai_tg_mmol_l: float | None = None,
+        vai_hdl_mmol_l: float | None = None,
+    ) -> dict:
+        params = {
+            "gewicht_kg": gewicht_kg,
+            "groesse_cm": groesse_cm,
+            "taille_cm": taille_cm,
+            "geschlecht": geschlecht,
+        }
+
+        if vai_tg_mmol_l is not None:
+            params["vai_tg_mmol_l"] = vai_tg_mmol_l
+
+        if vai_hdl_mmol_l is not None:
+            params["vai_hdl_mmol_l"] = vai_hdl_mmol_l
+
+        return self._get("/body/visceral-fat", params=params)
+
+    def tofi_risk(
+        self,
+        gewicht_kg: float,
+        groesse_cm: float,
+        taille_cm: float,
+    ) -> dict:
+        return self._get(
+            "/body/tofi-risk",
+            params={
+                "gewicht_kg": gewicht_kg,
+                "groesse_cm": groesse_cm,
+                "taille_cm": taille_cm,
+            },
+        )
+
+    def hr_max(self, alter: int | float) -> dict:
+        return self._get(
+            "/performance/hr-max",
+            params={"alter": alter},
+        )
+
+    def hr_zones(
+        self,
+        alter: int,
+        hr_ruhe: int | None = None,
+        hr_max: int | None = None,
+    ) -> dict:
+        params = {"alter": alter}
+
+        if hr_ruhe is not None:
+            params["hr_ruhe"] = hr_ruhe
+
+        if hr_max is not None:
+            params["hr_max"] = hr_max
+
+        return self._get("/performance/hr-zones", params=params)
+
+    def trimp(
+        self,
+        hr_bpm: list[float],
+        zeit_s: list[float],
+        geschlecht: Literal["m", "w"],
+        hr_ruhe: float,
+        hr_max: float,
+    ) -> dict:
+        return self._post(
+            "/performance/trimp",
+            params={
+                "geschlecht": geschlecht,
+                "hr_ruhe": hr_ruhe,
+                "hr_max": hr_max,
+            },
+            payload={
+                "hr_bpm": hr_bpm,
+                "zeit_s": zeit_s,
+            },
+        )
+
+    def critical_speed(
+        self,
+        laufleistung: list[dict[str, float]],
+    ) -> dict:
+        return self._post(
+            "/performance/critical-speed",
+            payload={"laufleistung": laufleistung},
+        )
+
+    def bmr(
+        self,
+        gewicht_kg: float,
+        groesse_cm: float,
+        alter: int,
+        geschlecht: Literal["m", "w"],
+        koerperfettanteil: float | None = None,
+    ) -> dict:
+        params = {
+            "gewicht_kg": gewicht_kg,
+            "groesse_cm": groesse_cm,
+            "alter": alter,
+            "geschlecht": geschlecht,
+        }
+
+        if koerperfettanteil is not None:
+            params["körperfettanteil"] = koerperfettanteil
+
+        return self._get("/metabolism/bmr", params=params)
+
+    def tdee(
+        self,
+        gewicht: float,
+        groesse: float,
+        alter: int,
+        geschlecht: Literal["m", "w"],
+        aktivitaetsfaktor: float = 1.55,
+        koerperfettanteil: float | None = None,
+    ) -> dict:
+        params = {
+            "gewicht": gewicht,
+            "groesse": groesse,
+            "alter": alter,
+            "geschlecht": geschlecht,
+            "aktivitaetsfaktor": aktivitaetsfaktor,
+        }
+
+        if koerperfettanteil is not None:
+            params["körperfettanteil"] = koerperfettanteil
+
+        return self._get("/metabolism/tdee", params=params)
+
+    def vo2max(
+        self,
+        gewicht_kg: float | None = None,
+        alter: int | None = None,
+        geschlecht: Literal["m", "w"] | None = None,
+        rockport_zeit_s: float | None = None,
+        rockport_hr_ende_bpm: int | None = None,
+        cooper_distanz_m: float | None = None,
+        uth_hr_ruhe_bpm: int | None = None,
+        uth_hr_max_bpm: int | None = None,
+    ) -> dict:
+        params = {
+            "gewicht_kg": gewicht_kg,
+            "alter": alter,
+            "geschlecht": geschlecht,
+            "rockport_zeit_s": rockport_zeit_s,
+            "rockport_hr_ende_bpm": rockport_hr_ende_bpm,
+            "cooper_distanz_m": cooper_distanz_m,
+            "uth_hr_ruhe_bpm": uth_hr_ruhe_bpm,
+            "uth_hr_max_bpm": uth_hr_max_bpm,
+        }
+
+        params = {k: v for k, v in params.items() if v is not None}
+
+        return self._get("/metabolism/vo2max", params=params)
+
+    def lactate_threshold(
+        self,
+        laufleistung: list[dict[str, float]],
+    ) -> dict:
+        return self._get(
+            "/metabolism/lactate-threshold",
+            params=None,
+            # NOTE: your spec says GET with requestBody.
+            # requests does not support json body in .get() nicely via helper.
+        )
+
+    def loinc(self, code: str) -> dict:
+        return self._get(f"/terminology/loinc/{code}")

biomodels_client-0.1.0/src/biomodels_client/database.py

@@ -0,0 +1,534 @@
+# src/biomodels_client/database.py
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+import pandas as pd
+from typing import Union, Optional
+import unicodedata
+
+class SensorStore:
+
+    def __init__(self, path: Union[str, Path] = "wearables.sqlite"):
+        self.path = Path(path)
+
+        self.con = sqlite3.connect(self.path)
+        self.con.row_factory = sqlite3.Row
+
+        self._create_schema()
+
+    def _create_schema(self):
+        self.con.execute("""
+        CREATE TABLE IF NOT EXISTS measurements (
+            id INTEGER PRIMARY KEY,
+            
+            record_hash TEXT UNIQUE,
+
+            source TEXT,
+            source_file TEXT,
+
+            provider TEXT,
+            source_name TEXT,
+            source_version TEXT,
+            device TEXT,
+
+            type TEXT,
+            hk_type TEXT,
+            loinc TEXT,
+
+            value REAL,
+            unit TEXT,
+
+            time_start TEXT,
+            time_end TEXT,
+
+            workout_id TEXT
+        )
+        """)
+
+        self.con.execute("""
+        CREATE INDEX IF NOT EXISTS idx_measurements_type
+        ON measurements(type)
+        """)
+
+        self.con.execute("""
+        CREATE INDEX IF NOT EXISTS idx_measurements_time
+        ON measurements(time_start)
+        """)
+
+        self.con.commit()
+
+    @staticmethod
+    def _clean_text(value):
+        if value is None:
+            return None
+
+        value = unicodedata.normalize("NFKC", value)
+        value = value.replace("\xa0", " ")
+        value = " ".join(value.split())
+
+        return value
+
+    def insert(self, record: dict):
+
+        source_name = self._clean_text(record.get("source_name"))
+        device = self._clean_text(record.get("device"))
+
+        self.con.execute("""
+        INSERT OR IGNORE INTO measurements (
+            record_hash,
+            source,
+            source_file,
+            provider,
+            source_name,
+            source_version,
+            device,
+            type,
+            hk_type,
+            loinc,
+            value,
+            unit,
+            time_start,
+            time_end,
+            workout_id
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        """, (
+            record.get("record_hash"),
+            record.get("source"),
+            record.get("source_file"),
+            record.get("provider"),
+            source_name,
+            record.get("source_version"),
+            device,
+            record.get("type"),
+            record.get("hk_type"),
+            record.get("loinc"),
+            record.get("value"),
+            record.get("unit"),
+            record.get("time_start"),
+            record.get("time_end"),
+            record.get("workout_id"),
+        ))
+
+    def commit(self):
+        self.con.commit()
+
+    def close(self):
+        self.con.close()
+
+
+    def select(
+        self,
+        measurement_type: str,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Retrieve measurements of a specified type.
+
+        Parameters
+        ----------
+        measurement_type : str
+            Measurement type (e.g. "heart_rate", "body_mass", "oxygen_saturation").
+        start, end : str, optional
+            Start and end datetime filters in format "YYYY-MM-DD HH:MM".
+
+        Returns
+        -------
+        pd.DataFrame
+            Measurements ordered by time.
+        """
+
+        sql = """
+        SELECT *
+        FROM measurements
+        WHERE type = ?
+        """
+
+        params = [measurement_type]
+
+        if start:
+            sql += " AND time_start >= ?"
+            params.append(start)
+
+        if end:
+            sql += " AND time_start <= ?"
+            params.append(end)
+
+        sql += " ORDER BY time_start"
+
+        return pd.read_sql_query(
+            sql,
+            self.con,
+            params=params,
+            parse_dates=["time_start", "time_end"],
+        )
+
+    def select_best_heart_rate_source(
+            self,
+            start: str,
+            end: str,
+    ) -> dict[str, any]:
+        """
+        Return the heart-rate source and device contributing the
+        largest number of measurements in a specified time range.
+
+        Parameters
+        ----------
+        start, end : str, optional
+            Start and end datetime filters in format "YYYY-MM-DD HH:MM".
+        """
+
+        sql = """
+        SELECT
+            COALESCE(source_name, '') AS source_name,
+            COALESCE(device, '') AS device,
+            COUNT(*) AS n
+        FROM measurements
+        WHERE type = 'heart_rate'
+          AND time_start >= ?
+          AND time_start <= ?
+        GROUP BY source_name, device
+        ORDER BY n DESC
+        LIMIT 1
+        """
+
+        row = self.con.execute(sql, (start, end)).fetchone()
+
+        if row is None:
+            raise ValueError("No heart-rate measurements found in selected time range.")
+
+        return {
+            "source_name": row["source_name"],
+            "device": row["device"],
+            "n_werte":  row["n"],
+        }
+
+        # return row["source_name"], row["device"], row["n"]
+
+    def select_heart_rate(
+            self,
+            start: Optional[str] = None,
+            end: Optional[str] = None,
+            source_name: Optional[str] = None,
+            device: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """
+        Retrieve heart-rate measurements.
+
+        Parameters
+        ----------
+        start, end : str, optional
+            Inclusive datetime filters (e.g. "2026-06-17 08:00").
+        source_name : str, optional
+            Restrict results to a specific source.
+        device : str, optional
+            Restrict results to a specific device.
+
+        Returns
+        -------
+        pd.DataFrame
+            Heart-rate measurements ordered by time.
+        """
+
+        sql = """
+        SELECT *
+        FROM measurements
+        WHERE type = 'heart_rate'
+        """
+
+        params = []
+
+        if start:
+            sql += " AND time_start >= ?"
+            params.append(start)
+
+        if end:
+            sql += " AND time_start <= ?"
+            params.append(end)
+
+        if source_name is not None:
+            sql += " AND COALESCE(source_name, '') = ?"
+            params.append(source_name)
+
+        if device is not None:
+            sql += " AND COALESCE(device, '') = ?"
+            params.append(device)
+
+        sql += " ORDER BY time_start"
+
+        return pd.read_sql_query(
+            sql,
+            self.con,
+            params=params,
+            parse_dates=["time_start", "time_end"],
+        )
+
+    def select_body_mass(self):
+
+        return self.select(
+            measurement_type="body_mass"
+        )
+
+    def trimp_payload(
+            self,
+            start: str,
+            end: str,
+            max_gap_s: float = 10 * 60,
+    ) -> dict:
+
+        """
+            Prepare a TRIMP endpoint payload from heart-rate measurements.
+
+            Heart-rate records are selected from the source/device with the
+            highest number of observations within the requested time range.
+            Measurements are ordered chronologically and converted into
+            heart-rate/time interval pairs suitable for submission to the
+            BioModelle TRIMP endpoint.
+
+            Intervals larger than `max_gap_s` are discarded to avoid assigning
+            excessive duration to isolated measurements separated by long
+            recording gaps.
+
+            Parameters
+            ----------
+            start : str
+                Start datetime.
+            end : str
+                End datetime.
+            max_gap_s : float, default=600
+                Maximum allowed interval between consecutive measurements [s].
+
+            Returns
+            -------
+            dict
+                Dictionary containing:
+
+                - hr_bpm : list[float]
+                    Heart-rate values [bpm].
+                - zeit_s : list[float]
+                    Corresponding interval durations [s].
+
+            Raises
+            ------
+            ValueError
+                If insufficient measurements are available or no valid
+                intervals remain after filtering.
+            """
+
+        hr_source = self.select_best_heart_rate_source(
+            start=start,
+            end=end,
+        )
+
+        df = self.select_heart_rate(
+            start=start,
+            end=end,
+            source_name=hr_source["source_name"],
+            device=hr_source["device"],
+        )
+
+        if len(df) < 2:
+            raise ValueError("At least two heart-rate measurements required.")
+
+        df = df.copy()
+        df["time_start"] = pd.to_datetime(df["time_start"], utc=True, errors="coerce")
+        df = df.dropna(subset=["time_start", "value"])
+
+        df = df.sort_values("time_start").reset_index(drop=True)
+
+        df["zeit_s"] = (
+            df["time_start"]
+            .shift(-1)
+            .sub(df["time_start"])
+            .dt.total_seconds()
+        )
+
+        df = df.iloc[:-1]
+        df = df[
+            (df["zeit_s"] > 0)
+            & (df["zeit_s"] <= max_gap_s)
+            ]
+
+        if len(df) == 0:
+            raise ValueError("No valid positive time intervals found.")
+
+        return {
+            "hr_bpm": df["value"].astype(float).tolist(),
+            "zeit_s": df["zeit_s"].astype(float).tolist(),
+        }
+
+    def query(self, sql: str, params=None) -> pd.DataFrame:
+
+        if params is None:
+            params = []
+
+        return pd.read_sql_query(
+            sql,
+            self.con,
+            params=params,
+        )
+
+    def execute(self, sql: str, params=None):
+
+        if params is None:
+            params = []
+
+        cur = self.con.execute(sql, params)
+        self.con.commit()
+
+        return cur
+
+    def estimate_hr_rest(
+            self,
+            months: int = 12,
+            night_start: int = 2,
+            night_end: int = 5,
+            lower_pct: float = 0.05,
+    ) -> float:
+
+        """
+            Estimate resting heart rate from wearable heart-rate measurements.
+
+            Uses measurements recorded during the night (default: 02:00-05:59)
+            within the last `months` months. The estimate is calculated as the
+            mean of the lowest `lower_pct` fraction of night-time heart-rate
+            values.
+
+            Parameters
+            ----------
+            months : int, default=12
+                Number of months to consider.
+            night_start : int, default=2
+                Start hour of the night-time window (24 h clock).
+            night_end : int, default=5
+                End hour of the night-time window (24 h clock).
+            lower_pct : float, default=0.05
+                Fraction of lowest night-time values used for estimation.
+
+            Returns
+            -------
+            float
+                Estimated resting heart rate [bpm].
+            """
+
+        sql = f"""
+        WITH recent_hr AS (
+            SELECT value, time_start
+            FROM measurements
+            WHERE type = 'heart_rate'
+              AND value IS NOT NULL
+              AND time_start >= datetime('now', '-{months} months')
+        ),
+        night_hr AS (
+            SELECT value
+            FROM recent_hr
+            WHERE CAST(strftime('%H', time_start) AS INTEGER)
+                  BETWEEN {night_start} AND {night_end}
+        ),
+        lowest_pct AS (
+            SELECT value
+            FROM night_hr
+            ORDER BY value
+            LIMIT (
+                SELECT MAX(
+                    1,
+                    CAST(COUNT(*) * {lower_pct} AS INTEGER)
+                )
+                FROM night_hr
+            )
+        )
+        SELECT AVG(value) AS hr_ruhe_bpm
+        FROM lowest_pct
+        """
+
+        row = self.con.execute(sql).fetchone()
+
+        if row is None or row[0] is None:
+            raise ValueError(
+                "Unable to estimate resting heart rate."
+            )
+
+        return round(float(row[0]), 1)
+
+    def estimate_hr_max(
+            self,
+            months: int = 12,
+            n_top: int = 20,
+    ) -> int:
+        """
+        Estimate maximum heart rate from wearable heart-rate measurements.
+
+        Uses measurements recorded within the last `months` months and
+        estimates HRmax from the highest observed heart-rate values.
+        Rather than returning the absolute maximum, which may be affected
+        by measurement artefacts or transient spikes, the estimate is
+        calculated as the minimum value among the `n_top` highest
+        heart-rate measurements.
+
+        Parameters
+        ----------
+        months : int, default=12
+            Number of months of heart-rate data to consider.
+
+        n_top : int, default=20
+            Number of highest heart-rate values used for estimation.
+            Larger values produce more conservative estimates.
+
+        Returns
+        -------
+        int
+            Estimated maximum heart rate [bpm].
+
+        Raises
+        ------
+        ValueError
+            If fewer than `n_top` heart-rate measurements are available.
+        """
+
+        sql = """
+        WITH recent_hr AS (
+            SELECT value
+            FROM measurements
+            WHERE type = 'heart_rate'
+              AND value IS NOT NULL
+              AND time_start >= datetime('now', ?)
+        ),
+        top_hr AS (
+            SELECT value
+            FROM recent_hr
+            ORDER BY value DESC
+            LIMIT ?
+        )
+        SELECT
+            COUNT(*) AS n_available,
+            (
+                SELECT MIN(value)
+                FROM top_hr
+            ) AS hr_max_bpm
+        FROM recent_hr
+        """
+
+        row = self.con.execute(
+            sql,
+            (f"-{months} months", n_top)
+        ).fetchone()
+
+        n = row["n_available"]
+
+        if n < n_top:
+            raise ValueError(
+                f"Insufficient heart-rate measurements for HRmax estimation. "
+                f"Found {n} values in the last {months} months, "
+                f"but at least {n_top} are required."
+            )
+
+        return int(round(float(row["hr_max_bpm"])))
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.commit()
+        self.close()

biomodels_client-0.1.0/src/biomodels_client/fixtures.py

@@ -0,0 +1,41 @@
+P1 = {
+    # anthropometry
+    "gewicht_kg": 90,
+    "groesse_cm": 180,
+    "taille_cm": 92,
+    "huefte_cm": 101,
+    "koerperfett_prozent": 18,
+
+    # demographics
+    "alter": 44,
+    "geschlecht": "m",
+
+    # cardiovascular
+    "hr_ruhe": 54,
+    "hr_max": 178,
+
+    # lipids
+    "vai_tg_mmol_l": 1.1,
+    "vai_hdl_mmol_l": 1.4,
+
+    # activity
+    "aktivitaetsfaktor": 1.7,
+
+    # VO2max
+    "cooper_distanz_m": 2800,
+    "rockport_zeit_s": 780,
+    "rockport_hr_ende_bpm": 128,
+}
+
+TRIMP_EXAMPLE = {
+    "hr_bpm": [100, 120, 140, 160],
+    "zeit_s": [300, 300, 300, 300],
+}
+
+CRITICAL_SPEED_EXAMPLE = {
+    "laufleistung": [
+        {"strecke_m": 700, "zeit_s": 180},  # 3 min
+        {"strecke_m": 1350, "zeit_s": 360},  # 6 min
+        {"strecke_m": 2500, "zeit_s": 720},  # 12 min
+    ]
+}

biomodels_client-0.1.0/src/biomodels_client/importers/apple_health.py

@@ -0,0 +1,215 @@
+import hashlib, json, zipfile
+import xml.etree.ElementTree as ET
+from decimal import Decimal
+from uuid import uuid4
+from pathlib import Path
+
+def iso(ts: str) -> str:
+    # Apple format: "YYYY-MM-DD HH:MM:SS ±HHMM/±HH:MM"
+    ts = ts.replace(" +0000", "Z").replace(" -0000", "Z")
+    # If not Z, convert " +0200" to "+02:00"
+    if len(ts) >= 5 and (ts[-5] in ["+", "-"]) and ts[-3] != ":":
+        ts = ts[:-5] + ts[-5:-2] + ":" + ts[-2:]
+    ts = ts.replace(" ", "T", 1)
+    return ts
+
+def to_ucum(value: str, hk_unit: str, target_ucum: str) -> tuple[Decimal, str]:
+    v = Decimal(value)
+
+    if target_ucum == "kg" and hk_unit in ("lb", "lbs"):
+        return (v * Decimal("0.45359237"), "kg")
+    if target_ucum == "/min" and hk_unit in ("count/min", "beats/min"):
+        return (v, "/min")
+    if target_ucum == "mg/dL" and hk_unit == "mmol/L":  # glucose conversion (glucose factor ~18.016)
+        return (v * Decimal("18.016"), "mg/dL")
+
+    return (v, target_ucum or hk_unit)
+
+
+# health kit to loinc + ucum
+HK_TO_LOINC = {
+    "HKQuantityTypeIdentifierBodyMass": {
+        "type": "body_mass",
+        "loinc": "29463-7",
+        "ucum": "kg",
+    },
+    "HKQuantityTypeIdentifierBodyMassIndex": {
+        "type": "bmi",
+        "loinc": "39156-5",
+        "ucum": "{score}",
+    },
+    "HKQuantityTypeIdentifierHeartRate": {
+        "type": "heart_rate",
+        "loinc": "8867-4",
+        "ucum": "/min",
+    },
+    "HKQuantityTypeIdentifierBloodGlucose": {
+        "type": "blood_glucose",
+        "loinc": "2345-7",
+        "ucum": "mg/dL",
+    },
+    "HKQuantityTypeIdentifierOxygenSaturation": {
+        "type": "oxygen_saturation",
+        "loinc": "59408-5",
+        "ucum": "%",
+    },
+    "HKQuantityTypeIdentifierStepCount": {
+        "type": "step_count",
+        "loinc": "41950-7",
+        "ucum": "{count}",
+    },
+}
+
+class AppleHealthImporter:
+
+    def __init__(self, path: str):
+        self.path = Path(path)
+
+        if self.path.suffix == ".zip":
+            outdir = self.path.with_suffix("")
+
+            if not outdir.exists():
+                with zipfile.ZipFile(self.path) as zf:
+                    zf.extractall(outdir)
+
+            self.xml_path = next(
+                p for p in outdir.rglob("export.xml")
+            )
+
+        else:
+            self.xml_path = self.path
+
+        self.ndjson_path = (
+            self.xml_path.parent / "export_biomodels.ndjson"
+        )
+
+    def records(self):
+        with self.xml_path.open("rb") as fh:
+            yield from self._iter_records(fh)
+
+    def observation(self, record, patient_ref="Patient/self"):
+        hk = record["type"]
+
+        if hk not in HK_TO_LOINC:
+            return None
+
+        if not record.get("value"):
+            return None
+
+        effective_time = record.get("endDate") or record.get("startDate")
+        if not effective_time:
+            return None
+
+    def _iter_records(self, fh):
+        context = ET.iterparse(fh, events=("end",))
+        for event, elem in context:
+            if elem.tag == "Record":
+                yield {
+                    "type": elem.attrib.get("type"),  # e.g. HKQuantityTypeIdentifierBodyMass
+                    "unit": elem.attrib.get("unit"),  # e.g. "kg", "count/min", "mg/dL"
+                    "value": elem.attrib.get("value"),
+                    "startDate": elem.attrib.get("startDate"),
+                    "endDate": elem.attrib.get("endDate"),
+                    "sourceName": elem.attrib.get("sourceName"),
+                    "sourceVersion": elem.attrib.get("sourceVersion"),
+                    "device": elem.attrib.get("device"),
+                }
+                elem.clear()
+
+    def measurement(self, record):
+        hk = record["type"]
+
+        if hk not in HK_TO_LOINC:
+            return None
+
+        if not record.get("value"):
+            return None
+
+        start_time = record.get("startDate")
+        end_time = record.get("endDate") or start_time
+
+        if not start_time:
+            return None
+
+        loinc = HK_TO_LOINC[hk]["loinc"]
+        target_ucum = HK_TO_LOINC[hk]["ucum"]
+
+        val, ucum = to_ucum(
+            record["value"],
+            record.get("unit"),
+            target_ucum,
+        )
+
+        row = {
+            "source": "apple_health",
+            "source_file": str(self.xml_path),
+
+            "provider": "Apple",
+            "source_name": record.get("sourceName"),
+            "source_version": record.get("sourceVersion"),
+            "device": record.get("device"),
+
+            "type": HK_TO_LOINC[hk].get("type"),
+            "hk_type": hk,
+            "loinc": loinc,
+
+            "value": float(val),
+            "unit": ucum,
+
+            "time_start": iso(start_time),
+            "time_end": iso(end_time),
+
+            "workout_id": None,
+        }
+
+        row["record_hash"] = self._record_hash(row)
+        return row
+
+    def write_to(self, store):
+        n_seen = 0
+        n_inserted = 0
+
+        for rec in self.records():
+            row = self.measurement(rec)
+
+            if row is None:
+                continue
+
+            n_seen += 1
+            before = store.con.total_changes
+            store.insert(row)
+            after = store.con.total_changes
+
+            if after > before:
+                n_inserted += 1
+
+        store.commit()
+
+        return {
+            "records_seen": n_seen,
+            "records_inserted": n_inserted,
+            "records_skipped": n_seen - n_inserted,
+            "database": str(store.path),
+        }
+
+    def to_ndjson(self, patient_ref="Patient/self"):
+        with open(self.ndjson_path, "w", encoding="utf-8") as out:
+            for rec in self.records():
+                obs = self.observation(rec, patient_ref=patient_ref)
+                if obs:
+                    out.write(json.dumps(obs, ensure_ascii=False) + "\n")
+
+    def _record_hash(self, row: dict) -> str:
+        key = {
+            "source": row.get("source"),
+            "hk_type": row.get("hk_type"),
+            "value": row.get("value"),
+            "unit": row.get("unit"),
+            "time_start": row.get("time_start"),
+            "time_end": row.get("time_end"),
+            "source_name": row.get("source_name"),
+            "device": row.get("device"),
+        }
+
+        raw = json.dumps(key, sort_keys=True, ensure_ascii=False)
+        return hashlib.sha256(raw.encode("utf-8")).hexdigest()