physiotrace 0.1.0a1__tar.gz

physiotrace-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayana Mussabayeva and Anuar Aimoldin
+
+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.

physiotrace-0.1.0a1/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: physiotrace
+Version: 0.1.0a1
+Summary: Behavioral audit of provenance reliance in frozen-encoder task heads (Recover, Stress, Intervene, Verify).
+Author: Anuar Aimoldin
+Author-email: Ayana Mussabayeva <ayana.mussabayeva@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AyanaMussabayeva/physiotrace
+Project-URL: Documentation, https://github.com/AyanaMussabayeva/physiotrace/blob/main/docs/tutorial.ipynb
+Project-URL: Source, https://github.com/AyanaMussabayeva/physiotrace
+Project-URL: Issues, https://github.com/AyanaMussabayeva/physiotrace/issues
+Project-URL: Changelog, https://github.com/AyanaMussabayeva/physiotrace/blob/main/CHANGELOG.md
+Keywords: foundation models,shortcut learning,provenance,EEG,ECG,robustness,audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: pandas>=2.0
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: matplotlib>=3.7; extra == "docs"
+Requires-Dist: nbformat>=5; extra == "docs"
+Requires-Dist: nbclient>=0.7; extra == "docs"
+Requires-Dist: ipykernel>=6; extra == "docs"
+Dynamic: license-file
+
+# physiotrace
+
+**Does your task head rely on how the data were recorded?**
+
+`physiotrace` audits a linear task head on a frozen encoder for reliance on
+acquisition provenance — device, site, reference, montage, scanner, batch —
+and certifies a remedy only when it is specific and safe. It works on
+embeddings, so any frozen model (EEG, ECG, imaging, omics) can be audited
+without retraining.
+
+Two common measurements do not answer this question. Shifted-transfer
+benchmarks can fail for unrelated reasons, and a provenance probe shows only
+that provenance is decodable, not that a head uses it. PhysioTRACE tests the
+head's behavior directly:
+
+| Step | Question | Output |
+|---|---|---|
+| **Recover** | How decodable is provenance from the embedding? | calibrated Linear Provenance Information (bits per unit) or conditional accessibility AUROC |
+| **Stress** | Does a head fitted under the provenance–target association degrade more than a control head when only that association is reversed on the same records? | excess vulnerability `G` with an identity-aware interval |
+| **Intervene** | Does removing a train-localized provenance component remove the failure? | `G` after removal |
+| **Verify** | Does the removal beat rank- and energy-matched random controls, and keep utility within a declared margin `δ`? | verdict |
+
+Every audit ends in one of three verdicts: **no reliance**, **reliance – remedy
+certified**, or **reliance – remedy not certified**.
+
+**New here? Start with the [tutorial](https://github.com/AyanaMussabayeva/physiotrace/blob/main/docs/tutorial.ipynb)**: bring your own
+embeddings, choose the settings, read the report, and avoid the mistakes that
+make an audit misleading.
+
+## Install
+
+```bash
+pip install --pre physiotrace         # 0.1.0a1 is a pre-release
+pip install --pre "physiotrace[plot]" # with matplotlib, for the tutorial figures
+```
+
+Python 3.10–3.13. Tested on every push from the oldest supported dependencies
+(numpy 1.24, scipy 1.10, scikit-learn 1.3, pandas 2.0) to the latest.
+
+## Quickstart
+
+### Observational data (for example device or site)
+
+```python
+import physiotrace as pt
+
+train = pt.Split(embeddings, y, u, clusters=patient_id)   # u: e.g. device A / device B
+test = pt.Split(test_embeddings, test_y, test_u, clusters=test_patient_id)
+
+report = pt.audit_observational(train, test, epsilon=0.01, delta=0.01)
+print(report)
+report.verdict        # pt.Verdict.REMEDY_CERTIFIED / REMEDY_NOT_CERTIFIED / NO_RELIANCE
+report.to_dict()      # JSON-serializable summary
+```
+
+```text
+PhysioTRACE audit (observational)
+  verdict: reliance, remedy certified
+  Recover   conditional_accessibility_auroc = 0.9946
+  Stress    G = 0.1384 [0.1228, 0.1539]  (epsilon = 0.01; 95% interval)
+  Intervene G after rank-1 removal = -0.0000 [-0.0013, 0.0012]  (100% reduction)
+  Verify    specific: yes (beats 100/100 random controls)
+            safe: yes (control-head AUROC, independent regime change -0.0000 [-0.0004, 0.0003], delta = 0.01)
+```
+
+(Output of [`examples/quickstart_synthetic.py`](https://github.com/AyanaMussabayeva/physiotrace/blob/main/examples/quickstart_synthetic.py), which also shows the other two
+verdicts, a cross-fitted audit, and a paired audit.)
+
+`y` and `u` can hold any two labels each (strings or numbers). `clusters`
+identifies who each record belongs to (patient, subject); it is the bootstrap
+unit, and a cluster on both sides of the split is rejected. `epsilon` is the
+smallest `G` that counts as reliance and `delta` the tolerated utility loss;
+declare both, and the localization `rank`, before looking at test results.
+
+The exposed head is fitted on the natural association and the control head
+with independence weights. Provenance is localized conditionally on the
+target, so removal does not by default discard population signal that sources
+differ in.
+
+To cross-fit over folds instead, as in the paper's PTB-XL audit:
+
+```python
+report = pt.audit_observational_crossfit(embeddings, y, u, folds=folds, clusters=patient_id)
+```
+
+### Checks
+
+Every report lists validity checks under `report.findings` and in
+`print(report)`: too few records in a `(y, u)` cell, a small effective sample
+or few effective clusters after reweighting, a very large weight, a stressed
+association too weak to test, a head that did not converge, missing clusters,
+and too few bootstrap draws. Checks never change the verdict; those of
+severity `warning` are also raised as `pt.PhysioTraceWarning`. Thresholds live
+in `pt.Gates`, and `pt.Gates.paper()` gives the stricter gates of the paper:
+
+```python
+report = pt.audit_observational(train, test, gates=pt.Gates.paper())
+```
+
+Common input mistakes fail early with a specific message: a target with more
+than two classes, a provenance factor with more than two groups, a patient in
+two folds or on both sides of the split, or a `(y, u)` combination with no
+records.
+
+### Paired views (for example EEG references of the same record)
+
+```python
+train = pt.PairedSplit(embeddings, y, views, records)   # one row per (record, view)
+report = pt.audit_paired(train, test, val=val, p_shortcut=0.6, delta=0.02)
+```
+
+The association is induced by a designed coupling at fixed marginals; each
+view serves in turn as the shortcut and `G` averages over them. Provenance is
+localized from within-record view contrasts without task labels.
+`report.details` adds decision flip rates across views and the same-record
+logit contrast.
+
+### Building blocks
+
+Every step is also available on its own:
+
+```python
+pt.lpi(train_h, train_u, val_h, val_u, test_h, test_u, test_clusters=subject)  # Recover
+tables = pt.observational_regimes(y_train, u_train)                             # Stress regimes
+w = pt.cell_weights(y_test, u_test, tables["reversed"])
+pt.weighted_auroc(y_test, scores, w)
+subspace, probe = pt.conditional_direction(z_train, y_train, u_train)           # Intervene
+subspace.remove(z_test)
+pt.random_subspaces(subspace.whitening, rank=1, n=100, seed=0)                  # Verify controls
+```
+
+`physiotrace.synthetic` generates embeddings with a known shortcut that
+reproduce each of the three verdicts on purpose.
+
+## Interpreting the result
+
+* A certified remedy supports the evaluated association and the linear
+  intervention, not safety under every deployment shift.
+* LPI and accessibility never yield a verdict on their own: a head can ignore
+  what a probe decodes.
+* Declare `epsilon`, `delta`, the rank, and the number of random controls
+  before looking at test results.
+* Keep every identity (patient, subject, record) inside one fold and pass it
+  as `clusters`; resampling windows or trials instead overstates precision.
+
+## Validation against the paper
+
+[`validation/`](https://github.com/AyanaMussabayeva/physiotrace/blob/main/validation) reproduces the published numbers of the PhysioTRACE paper from
+its saved artifacts:
+
+| Script | What is compared | Agreement |
+|---|---|---|
+| `validate_ecg_stress.py` | PTB-XL device audit: `G` before/after removal, its reduction, and the utility change for ECGFounder, CLEF-Small, metadata comparators, sensitivity cohorts, and the weak-association pair, with bootstrap intervals (18 quantities) | ≤ 1e-15 |
+| `validate_ecg_end_to_end.py` | The same audit end to end from ECGFounder embeddings recomputed with the paper's pipeline: `G` before/after removal with intervals, utility change, conditional accessibility, all 100 random-control `G`, four cohorts | ≤ 2e-5 (embeddings recomputed on different hardware) |
+| `validate_nmt_paired.py` | Paired NMT audit end to end from frozen embeddings (8 encoders): `G` before/after removal, all random-control `G`, paired logit contrast, selected `C`, verdict | ≤ 4e-8 |
+| | Calibrated LPI from the paper's exported probe states, including bootstrap intervals | ≤ 4e-8 |
+| | Calibrated LPI with probes refitted by `physiotrace` | ≤ 8e-4 bits (optimizer tolerance) |
+
+The paired NMT run whitened with an SVD; pass `whitening="svd"` to draw the
+identical random controls. Both methods give the same projections.
+
+## Status
+
+Version 0.1 (development). Binary targets with binary provenance
+(observational, target-conditional localization of any rank; rank 1 as in the
+paper) or `K` paired views. Multiclass targets, regression
+endpoints, and multi-encoder pooling are planned.
+
+## License
+
+MIT.

physiotrace-0.1.0a1/README.md

@@ -0,0 +1,171 @@
+# physiotrace
+
+**Does your task head rely on how the data were recorded?**
+
+`physiotrace` audits a linear task head on a frozen encoder for reliance on
+acquisition provenance — device, site, reference, montage, scanner, batch —
+and certifies a remedy only when it is specific and safe. It works on
+embeddings, so any frozen model (EEG, ECG, imaging, omics) can be audited
+without retraining.
+
+Two common measurements do not answer this question. Shifted-transfer
+benchmarks can fail for unrelated reasons, and a provenance probe shows only
+that provenance is decodable, not that a head uses it. PhysioTRACE tests the
+head's behavior directly:
+
+| Step | Question | Output |
+|---|---|---|
+| **Recover** | How decodable is provenance from the embedding? | calibrated Linear Provenance Information (bits per unit) or conditional accessibility AUROC |
+| **Stress** | Does a head fitted under the provenance–target association degrade more than a control head when only that association is reversed on the same records? | excess vulnerability `G` with an identity-aware interval |
+| **Intervene** | Does removing a train-localized provenance component remove the failure? | `G` after removal |
+| **Verify** | Does the removal beat rank- and energy-matched random controls, and keep utility within a declared margin `δ`? | verdict |
+
+Every audit ends in one of three verdicts: **no reliance**, **reliance – remedy
+certified**, or **reliance – remedy not certified**.
+
+**New here? Start with the [tutorial](https://github.com/AyanaMussabayeva/physiotrace/blob/main/docs/tutorial.ipynb)**: bring your own
+embeddings, choose the settings, read the report, and avoid the mistakes that
+make an audit misleading.
+
+## Install
+
+```bash
+pip install --pre physiotrace         # 0.1.0a1 is a pre-release
+pip install --pre "physiotrace[plot]" # with matplotlib, for the tutorial figures
+```
+
+Python 3.10–3.13. Tested on every push from the oldest supported dependencies
+(numpy 1.24, scipy 1.10, scikit-learn 1.3, pandas 2.0) to the latest.
+
+## Quickstart
+
+### Observational data (for example device or site)
+
+```python
+import physiotrace as pt
+
+train = pt.Split(embeddings, y, u, clusters=patient_id)   # u: e.g. device A / device B
+test = pt.Split(test_embeddings, test_y, test_u, clusters=test_patient_id)
+
+report = pt.audit_observational(train, test, epsilon=0.01, delta=0.01)
+print(report)
+report.verdict        # pt.Verdict.REMEDY_CERTIFIED / REMEDY_NOT_CERTIFIED / NO_RELIANCE
+report.to_dict()      # JSON-serializable summary
+```
+
+```text
+PhysioTRACE audit (observational)
+  verdict: reliance, remedy certified
+  Recover   conditional_accessibility_auroc = 0.9946
+  Stress    G = 0.1384 [0.1228, 0.1539]  (epsilon = 0.01; 95% interval)
+  Intervene G after rank-1 removal = -0.0000 [-0.0013, 0.0012]  (100% reduction)
+  Verify    specific: yes (beats 100/100 random controls)
+            safe: yes (control-head AUROC, independent regime change -0.0000 [-0.0004, 0.0003], delta = 0.01)
+```
+
+(Output of [`examples/quickstart_synthetic.py`](https://github.com/AyanaMussabayeva/physiotrace/blob/main/examples/quickstart_synthetic.py), which also shows the other two
+verdicts, a cross-fitted audit, and a paired audit.)
+
+`y` and `u` can hold any two labels each (strings or numbers). `clusters`
+identifies who each record belongs to (patient, subject); it is the bootstrap
+unit, and a cluster on both sides of the split is rejected. `epsilon` is the
+smallest `G` that counts as reliance and `delta` the tolerated utility loss;
+declare both, and the localization `rank`, before looking at test results.
+
+The exposed head is fitted on the natural association and the control head
+with independence weights. Provenance is localized conditionally on the
+target, so removal does not by default discard population signal that sources
+differ in.
+
+To cross-fit over folds instead, as in the paper's PTB-XL audit:
+
+```python
+report = pt.audit_observational_crossfit(embeddings, y, u, folds=folds, clusters=patient_id)
+```
+
+### Checks
+
+Every report lists validity checks under `report.findings` and in
+`print(report)`: too few records in a `(y, u)` cell, a small effective sample
+or few effective clusters after reweighting, a very large weight, a stressed
+association too weak to test, a head that did not converge, missing clusters,
+and too few bootstrap draws. Checks never change the verdict; those of
+severity `warning` are also raised as `pt.PhysioTraceWarning`. Thresholds live
+in `pt.Gates`, and `pt.Gates.paper()` gives the stricter gates of the paper:
+
+```python
+report = pt.audit_observational(train, test, gates=pt.Gates.paper())
+```
+
+Common input mistakes fail early with a specific message: a target with more
+than two classes, a provenance factor with more than two groups, a patient in
+two folds or on both sides of the split, or a `(y, u)` combination with no
+records.
+
+### Paired views (for example EEG references of the same record)
+
+```python
+train = pt.PairedSplit(embeddings, y, views, records)   # one row per (record, view)
+report = pt.audit_paired(train, test, val=val, p_shortcut=0.6, delta=0.02)
+```
+
+The association is induced by a designed coupling at fixed marginals; each
+view serves in turn as the shortcut and `G` averages over them. Provenance is
+localized from within-record view contrasts without task labels.
+`report.details` adds decision flip rates across views and the same-record
+logit contrast.
+
+### Building blocks
+
+Every step is also available on its own:
+
+```python
+pt.lpi(train_h, train_u, val_h, val_u, test_h, test_u, test_clusters=subject)  # Recover
+tables = pt.observational_regimes(y_train, u_train)                             # Stress regimes
+w = pt.cell_weights(y_test, u_test, tables["reversed"])
+pt.weighted_auroc(y_test, scores, w)
+subspace, probe = pt.conditional_direction(z_train, y_train, u_train)           # Intervene
+subspace.remove(z_test)
+pt.random_subspaces(subspace.whitening, rank=1, n=100, seed=0)                  # Verify controls
+```
+
+`physiotrace.synthetic` generates embeddings with a known shortcut that
+reproduce each of the three verdicts on purpose.
+
+## Interpreting the result
+
+* A certified remedy supports the evaluated association and the linear
+  intervention, not safety under every deployment shift.
+* LPI and accessibility never yield a verdict on their own: a head can ignore
+  what a probe decodes.
+* Declare `epsilon`, `delta`, the rank, and the number of random controls
+  before looking at test results.
+* Keep every identity (patient, subject, record) inside one fold and pass it
+  as `clusters`; resampling windows or trials instead overstates precision.
+
+## Validation against the paper
+
+[`validation/`](https://github.com/AyanaMussabayeva/physiotrace/blob/main/validation) reproduces the published numbers of the PhysioTRACE paper from
+its saved artifacts:
+
+| Script | What is compared | Agreement |
+|---|---|---|
+| `validate_ecg_stress.py` | PTB-XL device audit: `G` before/after removal, its reduction, and the utility change for ECGFounder, CLEF-Small, metadata comparators, sensitivity cohorts, and the weak-association pair, with bootstrap intervals (18 quantities) | ≤ 1e-15 |
+| `validate_ecg_end_to_end.py` | The same audit end to end from ECGFounder embeddings recomputed with the paper's pipeline: `G` before/after removal with intervals, utility change, conditional accessibility, all 100 random-control `G`, four cohorts | ≤ 2e-5 (embeddings recomputed on different hardware) |
+| `validate_nmt_paired.py` | Paired NMT audit end to end from frozen embeddings (8 encoders): `G` before/after removal, all random-control `G`, paired logit contrast, selected `C`, verdict | ≤ 4e-8 |
+| | Calibrated LPI from the paper's exported probe states, including bootstrap intervals | ≤ 4e-8 |
+| | Calibrated LPI with probes refitted by `physiotrace` | ≤ 8e-4 bits (optimizer tolerance) |
+
+The paired NMT run whitened with an SVD; pass `whitening="svd"` to draw the
+identical random controls. Both methods give the same projections.
+
+## Status
+
+Version 0.1 (development). Binary targets with binary provenance
+(observational, target-conditional localization of any rank; rank 1 as in the
+paper) or `K` paired views. Multiclass targets, regression
+endpoints, and multi-encoder pooling are planned.
+
+## License
+
+MIT.

physiotrace-0.1.0a1/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "physiotrace"
+version = "0.1.0a1"
+description = "Behavioral audit of provenance reliance in frozen-encoder task heads (Recover, Stress, Intervene, Verify)."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  {name = "Ayana Mussabayeva", email = "ayana.mussabayeva@gmail.com"},
+  {name = "Anuar Aimoldin"},
+]
+keywords = ["foundation models", "shortcut learning", "provenance", "EEG", "ECG", "robustness", "audit"]
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+  "numpy>=1.24",
+  "scipy>=1.10",
+  "scikit-learn>=1.3",
+  "pandas>=2.0",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.7"]
+dev = ["pytest>=7"]
+docs = ["matplotlib>=3.7", "nbformat>=5", "nbclient>=0.7", "ipykernel>=6"]
+
+[project.urls]
+Homepage = "https://github.com/AyanaMussabayeva/physiotrace"
+Documentation = "https://github.com/AyanaMussabayeva/physiotrace/blob/main/docs/tutorial.ipynb"
+Source = "https://github.com/AyanaMussabayeva/physiotrace"
+Issues = "https://github.com/AyanaMussabayeva/physiotrace/issues"
+Changelog = "https://github.com/AyanaMussabayeva/physiotrace/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Small synthetic audits legitimately trip the validity checks; tests that
+# assert on warnings use pytest.warns.
+filterwarnings = ["ignore::physiotrace.diagnostics.PhysioTraceWarning"]

physiotrace-0.1.0a1/setup.cfg

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

physiotrace-0.1.0a1/src/physiotrace/__init__.py

@@ -0,0 +1,67 @@
+"""PhysioTRACE: behavioral audit of provenance reliance in frozen-encoder task heads.
+
+Recover how decodable provenance is, Stress fixed heads by reversing only the
+provenance--target association, Intervene by removing a train-localized
+provenance component, and Verify the remedy against matched random controls
+within a declared utility margin.
+"""
+
+from . import bootstrap, intervene, metrics, recover, stress, synthetic, weights
+from .audit import PairedSplit, Split, audit_observational, audit_observational_crossfit, audit_paired
+from .diagnostics import Finding, Gates, PhysioTraceWarning
+from .intervene import Subspace, Whitening, conditional_direction, paired_subspace, random_subspaces
+from .metrics import weighted_auroc
+from .recover import LPIResult, fit_calibrated_probe, lpi
+from .report import AuditReport
+from .stress import excess_vulnerability, regime_aurocs
+from .verify import Verdict
+from .weights import (
+    cell_weights,
+    designed_coupling_table,
+    fixed_marginal_table,
+    independence_weights,
+    observational_regimes,
+)
+
+try:
+    from importlib.metadata import PackageNotFoundError, version as _version
+
+    __version__ = _version("physiotrace")
+except PackageNotFoundError:  # running from a source tree without installation
+    __version__ = "0+unknown"
+
+__all__ = [
+    "AuditReport",
+    "Finding",
+    "Gates",
+    "PhysioTraceWarning",
+    "Split",
+    "audit_observational_crossfit",
+    "LPIResult",
+    "PairedSplit",
+    "Subspace",
+    "Verdict",
+    "Whitening",
+    "audit_observational",
+    "audit_paired",
+    "bootstrap",
+    "cell_weights",
+    "conditional_direction",
+    "designed_coupling_table",
+    "excess_vulnerability",
+    "fit_calibrated_probe",
+    "fixed_marginal_table",
+    "independence_weights",
+    "intervene",
+    "lpi",
+    "metrics",
+    "observational_regimes",
+    "paired_subspace",
+    "random_subspaces",
+    "recover",
+    "regime_aurocs",
+    "stress",
+    "synthetic",
+    "weighted_auroc",
+    "weights",
+]

physiotrace-0.1.0a1/src/physiotrace/_validation.py

@@ -0,0 +1,54 @@
+"""Small input checks shared across modules."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def as_matrix(values, *, name: str) -> np.ndarray:
+    array = np.asarray(values, dtype=np.float64)
+    if array.ndim != 2:
+        raise ValueError(f"{name} must be a two-dimensional array, got shape {array.shape}.")
+    if not np.isfinite(array).all():
+        raise ValueError(f"{name} contains non-finite values.")
+    return array
+
+
+def as_codes(values, *, name: str, n_levels: int | None = None) -> np.ndarray:
+    """Return non-negative integer codes; values must already be encoded."""
+
+    array = np.asarray(values)
+    if array.ndim != 1:
+        raise ValueError(f"{name} must be one-dimensional.")
+    if not np.issubdtype(array.dtype, np.integer):
+        if not np.issubdtype(array.dtype, np.number) or not np.all(np.equal(array, np.floor(array))):
+            raise ValueError(f"{name} must contain integer codes.")
+    codes = array.astype(np.int64)
+    if np.any(codes < 0):
+        raise ValueError(f"{name} must contain non-negative codes.")
+    if n_levels is not None and np.any(codes >= n_levels):
+        raise ValueError(f"{name} contains a code outside [0, {n_levels}).")
+    return codes
+
+
+def encode(values, levels=None) -> tuple[np.ndarray, tuple]:
+    """Encode arbitrary labels as integer codes in the order of ``levels``."""
+
+    array = np.asarray(values)
+    if levels is None:
+        levels = tuple(np.unique(array).tolist())
+    else:
+        levels = tuple(levels)
+    lookup = {level: code for code, level in enumerate(levels)}
+    try:
+        codes = np.fromiter((lookup[value] for value in array.tolist()), dtype=np.int64, count=len(array))
+    except KeyError as error:
+        raise ValueError(f"Value {error.args[0]!r} is not among the declared levels {levels}.") from None
+    return codes, levels
+
+
+def same_length(**arrays) -> int:
+    lengths = {name: len(value) for name, value in arrays.items()}
+    if len(set(lengths.values())) != 1:
+        raise ValueError(f"Inputs must have the same length, got {lengths}.")
+    return next(iter(lengths.values()))