Types

types

Type definitions for shap-monitor.

Classes

Period

Bases: NamedTuple

A time period defined by start and end dates.

Can be used as a tuple: Period(start, end) or with named fields: Period(start=date(2025, 1, 1), end=date(2025, 1, 7))

Backend

Bases: Protocol

Protocol for backend storage systems.

Any backend that implements the read, write, and delete methods can be used.

Functions

read

read(
    start_dt: datetime | date | None = None,
    end_dt: datetime | date | None = None,
    batch_id: str | None = None,
    model_version: str | None = None,
) -> DFrameLike

Read data from the backend.

Source code in shapmonitor/types.py

def read(
    self,
    start_dt: datetime | date | None = None,
    end_dt: datetime | date | None = None,
    batch_id: str | None = None,
    model_version: str | None = None,
) -> DFrameLike:
    """Read data from the backend."""
    ...

write

write(batch: ExplanationBatch) -> None

Write data to the backend.

Source code in shapmonitor/types.py

def write(self, batch: "ExplanationBatch") -> None:
    """Write data to the backend."""
    ...

delete

delete(cutoff_dt: datetime) -> None

Delete data before a certain datetime.

Source code in shapmonitor/types.py

def delete(self, cutoff_dt: datetime) -> None:
    """Delete data before a certain datetime."""
    ...

ExplanationLike

Bases: Protocol

Protocol for SHAP explanation objects.

Any SHAP explanation object that implements the values and base_values attributes can be used.

Attributes

values property

values: ArrayLike

Get SHAP values.

base_values property

base_values: ArrayLike

Get base values.

shape property

shape: tuple[int, ...]

Get shape of the explanation values.

ExplainerLike

Bases: Protocol

Protocol for SHAP explainer objects.

Any SHAP explainer (TreeExplainer, KernelExplainer, etc.) that implements the shap_values method can be used.

Functions

explain_row

explain_row(X: ArrayLike) -> ExplanationLike

Compute SHAP for a single input feature row.

Source code in shapmonitor/types.py

def explain_row(self, X: ArrayLike) -> ExplanationLike:
    """Compute SHAP for a single input feature row."""
    ...

ExplanationBatch dataclass

ExplanationBatch(
    timestamp: datetime,
    batch_id: str,
    model_version: str,
    n_samples: int,
    base_values: ArrayLike,
    shap_values: dict[str, ArrayLike],
    feature_values: dict[str, ArrayLike] | None = None,
    predictions: ArrayLike | None = None,
)

A batch of explanations to be stored.

This corresponds to one row in the Parquet backend. Feature-specific columns (shap_, feat_) are stored as dicts mapping feature names to arrays of values.

Functions

to_dataframe

to_dataframe() -> DataFrame

Convert the ExplanationBatch to a pandas DataFrame.

Source code in shapmonitor/types.py

def to_dataframe(self) -> pd.DataFrame:
    """Convert the ExplanationBatch to a pandas DataFrame."""
    data = {
        "timestamp": [self.timestamp] * self.n_samples,
        "batch_id": [self.batch_id] * self.n_samples,
        "model_version": [self.model_version] * self.n_samples,
        "base_value": self.base_values,
    }

    # Add SHAP values and feature values
    for feat_name, shap_vals in self.shap_values.items():
        data[f"shap_{feat_name}"] = shap_vals

    if self.feature_values is not None:
        for feat_name, feat_vals in self.feature_values.items():
            data[f"feat_{feat_name}"] = feat_vals

    # Add predictions if available
    if self.predictions is not None:
        data["prediction"] = self.predictions

    return pd.DataFrame(data)