meridian_tools.model_selection

Model-selection helpers layered on top of ArviZ and Meridian.

Module: meridian_tools.model_selection

Functions

`has_log_likelihood`

def has_log_likelihood(candidate: Any) -> bool

Return whether the candidate exposes a non-empty log_likelihood group.

Accepts either an ArviZ InferenceData or any object with an .inference_data attribute (e.g. a fitted Meridian model).

Parameters:

candidate — ArviZ InferenceData or fitted Meridian model.

Returns: True if a non-empty log_likelihood group exists.

`compute_loo`

def compute_loo(
    candidate: Any,
    *,
    pointwise: bool = False,
    scale: str = "log",
) -> InformationCriterionResult

Compute PSIS-LOO for a Meridian model or InferenceData.

If the candidate is a fitted Meridian model without a log_likelihood group, the function automatically reconstructs it through attach_log_likelihood.

Parameters:

candidate — Fitted Meridian model or ArviZ InferenceData with log_likelihood.
pointwise — Include per-observation LOO values and Pareto k diagnostics.
scale — Scale for ELPD computation ("log", "negative_log", or "deviance").

Returns: An InformationCriterionResult with kind="loo".

Raises: ModelSelectionError if log-likelihood cannot be obtained.

`compute_waic`

def compute_waic(
    candidate: Any,
    *,
    pointwise: bool = False,
    scale: str = "log",
) -> InformationCriterionResult

Compute WAIC for a Meridian model or InferenceData.

Same automatic log-likelihood reconstruction as compute_loo.

Parameters:

candidate — Fitted Meridian model or ArviZ InferenceData with log_likelihood.
pointwise — Include per-observation WAIC values.
scale — Scale for ELPD computation.

Returns: An InformationCriterionResult with kind="waic".

Raises: ModelSelectionError if log-likelihood cannot be obtained.

`compare_models`

def compare_models(
    candidates: Mapping[str, Any],
    *,
    ic: str = "loo",
    scale: str = "log",
) -> pd.DataFrame

Compare multiple models with ArviZ compare.

Parameters:

candidates — Dictionary mapping model names to fitted Meridian models or InferenceData objects.
ic — Information criterion to use: "loo" or "waic".
scale — Scale for ELPD computation.

Returns: A pandas DataFrame with columns: model, rank, elpd_{ic}, p_{ic}, elpd_diff, weight, se, dse, warning, scale. Ranked by ELPD (rank 0 is best).

For a single candidate, returns a one-row DataFrame with rank=0, elpd_diff=0.0, and weight=1.0.

Raises:

ValueError if ic is not "loo" or "waic", or if candidates is empty.
ModelSelectionError if any candidate lacks log-likelihood data.

Classes

`ModelSelectionError`

class ModelSelectionError(RuntimeError)

Raised when information criteria cannot be computed.

Property	Type	Description
`reason_code`	`str \| None`	Structured code identifying the failure reason.

Known reason codes:

Code	Meaning
`missing_log_likelihood_group`	`InferenceData` has no `log_likelihood` group and cannot be reconstructed.
`holdout_fit_unsupported`	Model was fitted with a holdout mask.
`requires_fitted_meridian_model`	Missing posterior samples or ArviZ `InferenceData`.
`meridian_internal_seam_incompatible`	Meridian version lacks required reconstruction methods.

`InformationCriterionResult`

@dataclass(frozen=True)
class InformationCriterionResult

Summary of one information-criterion computation.

Attribute	Type	Description
`kind`	`str`	`"loo"` or `"waic"`.
`summary`	`dict[str, Any]`	Summary statistics (ELPD, p, SE, etc.).
`pointwise`	`pd.DataFrame \| None`	Per-observation values (if `pointwise=True`).