Explainability

fyron.explainability provides inspectable model-interpretation tables for fitted sklearn-compatible estimators. The module is intentionally table-first so explanations can be reviewed, plotted, and exported. SHAP support is optional and stays explicit because SHAP values are powerful but method-sensitive.

For inclusion/exclusion explanations, use Flow Explainability. A strong study usually keeps both artifacts: a cohort flow explaining who entered the analysis, and model explanation tables explaining which features influenced predictions.

Install

bash

uv add "fyron[explainability]"

Imports

python

from fyron import explainability as fe

API Contract

Topic	Contract
Input shape	Fitted sklearn-compatible estimator plus feature DataFrame/array; optional SHAP/background data for SHAP workflows.
Required columns	Feature names should match model inputs; contribution tables need row/patient, feature, value, and contribution columns.
Return shape	DataFrames for permutation importance, partial dependence, SHAP values, SHAP summaries, and reviewer-facing summaries.
Saved artifacts	Feature importance tables, SHAP/contribution tables, model explanation summaries, and patient-level driver tables.
Failure modes	Missing optional SHAP/sklearn support, unsupported estimator interface, mismatched feature names, expensive SHAP runs, or explanations mistaken for causal effects.

Function Reference

Function	Required	Optional	Returns
`permutation_importance_table(estimator, X, y, ...)`	fitted model, features, labels	feature names, repeats, scoring, random state	sorted importance DataFrame
`partial_dependence_table(estimator, X, ...)`	fitted model and feature table	features, names, grid resolution	long partial-dependence DataFrame
`shap_values_table(estimator, X, ...)`	fitted model and feature table	feature names, custom explainer, background data, max rows	long row-feature SHAP DataFrame
`shap_summary_table(estimator, X, ...)`	fitted model and feature table	feature names, custom explainer, background data, max rows	ranked mean absolute SHAP summary
`explain_model_summary(...)`	importance, SHAP, metrics, or QC tables	notes, feature column name	merged reviewer-facing feature summary
`explain_patient_prediction(...)`	long contribution table	row/patient selector, top N, column names	top positive and negative drivers

Example

python

importance = fe.permutation_importance_table(
    estimator=rf["model"],
    X=X_test,
    y=y_test,
    feature_names=X_test.columns,
    n_repeats=20,
    scoring="roc_auc",
)

pdp = fe.partial_dependence_table(
    estimator=rf["model"],
    X=X_test,
    features=["l3_sma_cm2", "age"],
)

shap_summary = fe.shap_summary_table(
    estimator=rf["model"],
    X=X_test,
    background_data=X_train.sample(100, random_state=42),
    max_rows=500,
)

Reviewer-Facing Summary

Use explain_model_summary to combine model explanation outputs with feature QC and validation metrics:

python

summary = fe.explain_model_summary(
    importance=importance,
    shap_summary=shap_summary,
    feature_qc=feature_qc,
    metrics={"auc": 0.82, "balanced_accuracy": 0.74},
    notes={"stage": "Clinically plausible direction."},
)

For a single patient or row, use a long contribution table such as shap_values_table output:

python

drivers = fe.explain_patient_prediction(
    shap_long,
    row_index=0,
    top_n=5,
)

SHAP Workflow

Use SHAP when you need feature-attribution tables for individual rows or a ranked global importance summary. Fyron returns plain DataFrames rather than SHAP plot objects:

shap_values_table returns one row per patient-row and feature with feature_value, shap_value, and abs_shap_value.
shap_summary_table aggregates those values into mean_abs_shap, mean_shap, median_abs_shap, n, and rank.
background_data should represent the training distribution; for large cohorts use a reviewed sample.
max_rows keeps expensive SHAP jobs bounded for notebooks and CI.

Use model explanations as inspection tools, not causal evidence. When a feature looks unexpectedly important, check leakage, missingness, coding artifacts, subgroup imbalance, target leakage through follow-up time, and clinical plausibility.