Bits & Flames
bitsandflames/fyron

Audit And Provenance

fyron.audit creates lightweight JSON provenance manifests for reproducible analyses. Use it to record input files, output artifacts, parameters, package version, runtime metadata, and notes that explain how an analysis was produced.

The manifest is deliberately simple JSON so it can travel with paper supplements, internal reports, model artifacts, or archived cohort folders.

Install

bash
uv add fyron

Imports

python
from fyron import audit as fa

Core Concepts

ConceptMeaning
inputSource file used by an analysis, such as a cohort CSV, DICOM result table, or BOA feature table.
outputFile produced by an analysis, such as a table, figure, model artifact, or report.
parameterExplicit setting that affects the result, such as duration_col, event_col, covariates, thresholds, or random seed.
hashFile digest used to detect changes in inputs or outputs.
manifestJSON-serializable record that connects inputs, parameters, environment, and outputs.

API Contract

TopicContract
Input shapeFile paths, output paths, parameter dictionaries, notes, random seeds, and study/run metadata.
Required columns/filesExisting files are hashed when paths are supplied; missing paths can still be recorded as planned artifacts.
Return shapeJSON-serializable dictionaries or resolved output paths.
Saved artifactsProvenance JSON manifests, file hash records, and analysis-run metadata.
Failure modesUnreadable files, unwritable output paths, non-serializable parameter values, or missing study metadata needed for reviewer interpretation.

Function Guide

FunctionUse it whenReturns
hash_fileYou need a digest for one file.hex digest string
create_provenance_manifestYou need a JSON-ready record of an analysis.dict
analysis_run_manifestYou need a study-run manifest with analysis type, cohort ID, and seed.dict
write_manifestYou need to write the manifest to disk.output path

Minimal Example

python
from fyron import audit as fa

manifest = fa.create_provenance_manifest(
    title="BOA survival model analysis",
    inputs=["data/boa_features.csv", "data/outcomes.csv"],
    outputs=["results/cox_model_summary.csv", "figures/km_risk_group.png"],
    parameters={
        "duration_col": "time",
        "event_col": "event",
        "covariates": ["age", "stage", "l3_sma_cm2"],
        "random_state": 42,
    },
)

fa.write_manifest(manifest, "results/provenance.json")

For clinical AI studies, prefer the run-specific wrapper:

python
manifest = fa.analysis_run_manifest(
    title="Locked external validation",
    analysis_type="classification",
    cohort_id="validation-cohort-v1",
    inputs=["data/validation.csv"],
    outputs=["results/model_metrics.csv"],
    parameters={"threshold": 0.4, "model": "Random Forest"},
    random_seed=42,
)

Parameter Notes

ParameterPractical guidance
titleUse a human-readable analysis name.
inputsInclude raw or derived files that determine the result. Existing files receive hashes.
outputsInclude generated artifacts. Existing files receive hashes.
parametersRecord clinical and technical assumptions, not just model hyperparameters.
notesAdd free-text context such as cohort version, reviewer, or known limitations.

CLI Workflow

bash
fyron audit-manifest \
  --title "BOA survival model analysis" \
  --input data/boa_features.csv \
  --input data/outcomes.csv \
  --output results/cox_model_summary.csv \
  --output figures/km_risk_group.png \
  --param duration_col=time \
  --param event_col=event \
  --write results/provenance.json

Use the CLI after a table, model, or figure-producing script has run. It is also useful in pipeline jobs where provenance should be written even when the analysis code is outside Python.

What To Record

WorkflowUseful parameters
FHIR extractionresource_type, params, max_pages, partition dates, deduplicate_by
DICOM downloadendpoint label, output format, study/series UID columns, manifest path
BOA extractionfeature families, label maps, download_id mapping, number of workers
Survival analysisduration_col, event_col, group_col, covariates, tau
MLmodel type, split settings, class imbalance settings, random seed, selected features
Validationthreshold rule, calibration bins, subgroup columns, time horizon

Research Decision: Minimum Provenance

For papers and internal model reviews, record at least the cohort file, feature file, model/table/figure outputs, random seed, endpoint definition, threshold rule, and Fyron version. The manifest is not a substitute for a methods section, but it prevents silent drift between notebooks, exported tables, and final figures.

Common Pitfalls

  • Do not record only final outputs; include the cohort and feature inputs.
  • Record random seeds and threshold rules when models are involved.
  • Keep manifests next to exported artifacts so they are not separated from results.
  • Use stable file paths or archive manifests with the exact files they describe.