Export explanations

Calibrated explanations can be exported for offline analysis, dashboards, or QA reviews.

Serialize with schema v1

Use the collection helper to generate a schema-aligned payload that bundles the explanations and calibration metadata.

import json

batch = explainer.explain_factual(x_test[:10])
payload = batch.to_json()

with open("factual.json", "w", encoding="utf-8") as fh:
    json.dump(payload, fh, indent=2, default=str)

The payload includes:

  • collection: size, mode, feature names, thresholds, and runtime telemetry snapshot so integrations know how the explanations were generated.

  • explanations: each instance serialised via schema v1 to preserve rule weights, probabilistic outputs, and provenance.

Rehydrate exported explanations

CalibratedExplanations.from_json() returns domain-model objects that can be inspected or re-exported without rebuilding the explainer.

from calibrated_explanations.explanations import CalibratedExplanations

exported = CalibratedExplanations.from_json(payload)
for explanation in exported.explanations:
    print(explanation.task, explanation.prediction)

Pair the parsed explanations with the collection metadata to keep the calibration context alongside downstream analytics or dashboards.

Persist rule tables

import pandas

rows = []
for idx, exp in enumerate(batch):
    rows.append(
        {
            "instance": idx,
            "prediction": exp.predict,
            "low": exp.prediction_interval[0],
            "high": exp.prediction_interval[1],
        }
    )

df = pandas.DataFrame(rows)
df.to_parquet("factual_rules.parquet")

Store the rule payload separately (from the JSON export above) if you need feature-level detail inside analytics tools.

Streaming large exports

For large explanation collections, use the experimental streaming export to avoid loading all explanations into memory at once.

# Stream explanations as JSON Lines (default)
for chunk in explanations.to_json_stream(chunk_size=256, format="jsonl"):
    # Each chunk is a JSON string; write to file or process incrementally
    print(chunk)  # or fh.write(chunk + "\n")

# Or use chunked JSON arrays
for chunk in explanations.to_json_stream(chunk_size=256, format="chunked"):
    # Each chunk is a JSON array string like "[{...},{...},...]"
    print(chunk)

  • Status: Experimental in v0.10.1+.

  • Memory profile: Tested for < 200 MB peak usage with 10k explanations at chunk_size=256 (see reports/streaming_benchmark_v0.10.1.json for latest results).

  • Telemetry: Export metrics (rows, elapsed time, peak memory) are captured in collection metadata and explainer telemetry.

Optional extras

  • Telemetry attachment (optional). Persist telemetry snapshots only when compliance workflows require them:

    telemetry = explainer.runtime_telemetry
with open("factual.telemetry.json", "w", encoding="utf-8") as fh:
    json.dump(telemetry, fh, indent=2)

Include batch identifiers and timestamps in filenames so you can reconcile the payload with model monitoring pipelines.