Results, reporting, and provenance

FitResult is the durable boundary between estimation and downstream analysis. It stores numerical output together with the information needed to interpret and reproduce it.

Result contents

Common fields include:

  • engine, method, objective, and log likelihood;

  • immutable parameter mapping;

  • ConvergenceReport;

  • fitted values, residuals, and conditional random effects where supported;

  • backend-specific extra values such as coefficient covariance and visit covariance;

  • structured diagnostics;

  • the compiled ModelIR;

  • RunManifest with data/model fingerprints, environment, options, warnings, timing, and reproducibility class.

Convenience properties include success and n_observations. Use summary() for human review and to_dict() for structured processing.

Portable result archives

path = result.save("result.json")
loaded = pymixef.FitResult.load(path)

assert loaded.parameters == result.parameters
assert loaded.manifest.model_ir_hash == result.manifest.model_ir_hash

Archives are JSON rather than pickle, so the payload is inspectable and does not execute arbitrary Python during load. A .sha256 sidecar detects content drift. Hashes provide integrity evidence, not identity, approval, confidentiality, or a digital signature.

pymixef.load is a convenience alias for FitResult.load.

Model and data fingerprints

fingerprint_model_ir hashes canonical semantic model content. fingerprint_data hashes the normalized analysis data contract. environment_snapshot records runtime context. Equivalent semantic IR should have the same semantic hash even when nonsemantic formatting differs.

Model hashes help answer “did the model change?” They do not establish that a model is identifiable or appropriate.

Reports

from pymixef import render_report

render_report(result, "report.md")
render_report(result, "report.html")
render_report(result, "report.pdf")
render_report(result, "report.docx")

The file suffix chooses Markdown, HTML, PDF, or Word. Install the report extra for optional formats. A generated report presents retained evidence; it does not replace scientific review or an organization’s controlled approval process.

Validation bundles

bundle = pymixef.create_validation_bundle(
    result,
    "analysis-evidence",
    include_data=False,
)
verification = pymixef.verify_validation_bundle(bundle)
assert verification["valid"]

A bundle contains a manifest, result, traceability material, and a human-readable README. Raw data are excluded by default; include data only with authorization and an appropriate privacy/security assessment.

verify_validation_bundle checks file integrity and internal consistency. traceability_matrix, classify_change, and change_impact connect requirements, implementation areas, tests, and change review.

Comparison evidence

Use compare to preserve mapping and conventions when checking PyMixEF output against another implementation. A close numerical comparison supports a particular model/data/software configuration; it should not be generalized beyond the tested space without evidence.

Reproducibility classes

The manifest’s ReproducibilityClass distinguishes deterministic behavior from calculations that require tolerances or recorded random seeds. Reproducibility means rerunning the declared computation under controlled conditions; it is not the same as replicating a scientific result on independent data.

API map