dfc-kit 1.0.0__py3-none-any.whl

dfckit/commands/reporting.py

@@ -0,0 +1,146 @@
+"""Command handlers that summarize, interpret, or infer from existing artifacts."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..artifacts import load_state_model_scores
+from ..inference.endpoints import (
+    _infer_paired_endpoints_file,
+    _write_paired_endpoint_inference,
+)
+from ..inference.state_metrics import (
+    _infer_paired_state_metrics_file,
+    _write_paired_state_inference,
+)
+from ..information.summary import summarize_information_artifact, write_information_summary
+from ..states import compare_state_model_scores
+from ..states.interpretation import (
+    describe_state_artifacts,
+    write_state_description,
+)
+from ..states.selection import _write_state_count_comparison
+from ..storage.summary import _summarize_store_file, _write_store_summary
+
+
+def describe_states(namespace: argparse.Namespace) -> dict[str, object]:
+    """Describe named features that distinguish fitted state patterns."""
+    payload = describe_state_artifacts(
+        namespace.store,
+        namespace.model,
+        top_features=namespace.top_features,
+        network_map_path=namespace.network_map,
+    )
+    output = write_state_description(payload, namespace.output)
+    return {
+        "output": str(output),
+        "model_kind": payload["model_kind"],
+        "feature_type": payload["feature_type"],
+        "n_states": payload["n_states"],
+        "n_features": payload["n_features"],
+        "network_map_applied": payload["network_map_applied"],
+    }
+
+
+def infer_state_metrics(namespace: argparse.Namespace) -> dict[str, object]:
+    """Run paired inference over selected state metrics."""
+    payload = _infer_paired_state_metrics_file(
+        namespace.metrics,
+        condition_a=namespace.condition_a,
+        condition_b=namespace.condition_b,
+        metrics=tuple(namespace.metric),
+        fdr_family=namespace.fdr_family,
+        alpha=namespace.alpha,
+        n_permutations=namespace.permutations,
+        n_bootstrap=namespace.bootstrap,
+        seed=namespace.seed,
+        exact=namespace.exact,
+    )
+    output = _write_paired_state_inference(payload, namespace.output)
+    counts = {
+        status: sum(result["result_status"] == status for result in payload["results"])
+        for status in ("positive", "negative", "not_testable")
+    }
+    return {
+        "output": str(output),
+        "contrast": payload["contrast"],
+        "fdr_family": payload["fdr_family"],
+        "n_endpoints": payload["n_endpoints"],
+        "n_tested": payload["n_tested"],
+        "status_counts": counts,
+    }
+
+
+def summarize_store(namespace: argparse.Namespace) -> dict[str, object]:
+    """Write acquisition-level feature statistics from a FeatureStore."""
+    statistics = tuple(namespace.statistic or ("mean",))
+    payload = _summarize_store_file(namespace.store, statistics)
+    output = _write_store_summary(payload, namespace.output)
+    return {
+        "output": str(output),
+        "source_contract": payload["source_contract"],
+        "feature_type": payload["feature_type"],
+        "n_features": payload["n_features"],
+        "n_acquisitions": payload["n_acquisitions"],
+        "statistics": payload["statistics"],
+    }
+
+
+def infer_endpoints(namespace: argparse.Namespace) -> dict[str, object]:
+    """Run paired inference over named acquisition-level endpoints."""
+    payload = _infer_paired_endpoints_file(
+        namespace.endpoints,
+        condition_a=namespace.condition_a,
+        condition_b=namespace.condition_b,
+        fdr_family=namespace.fdr_family,
+        alpha=namespace.alpha,
+        n_permutations=namespace.permutations,
+        n_bootstrap=namespace.bootstrap,
+        seed=namespace.seed,
+        exact=namespace.exact,
+    )
+    output = _write_paired_endpoint_inference(payload, namespace.output)
+    return {
+        "output": str(output),
+        "contrast": payload["contrast"],
+        "fdr_family": payload["fdr_family"],
+        "n_endpoints": payload["n_endpoints"],
+        "n_tested": payload["n_tested"],
+    }
+
+
+def summarize_information(namespace: argparse.Namespace) -> dict[str, object]:
+    """Extract acquisition-level endpoints from a fixed-information artifact."""
+    payload = summarize_information_artifact(namespace.artifact)
+    output = write_information_summary(payload, namespace.output)
+    return {
+        "output": str(output),
+        "lengths": payload["lengths"],
+        "groups": payload["groups"],
+        "n_endpoints": len(payload["rows"]),
+    }
+
+
+def compare_state_counts(namespace: argparse.Namespace) -> dict[str, object]:
+    """Aggregate complete held-out score grids into a state-count comparison."""
+    if namespace.output.exists() or namespace.output.is_symlink():
+        raise FileExistsError(
+            f"state-count comparison output path already exists: {namespace.output}"
+        )
+    reports = tuple(load_state_model_scores(path) for path in namespace.score)
+    comparison = compare_state_model_scores(
+        reports,
+    )
+    output = _write_state_count_comparison(comparison, namespace.output)
+    return {
+        "output": str(output),
+        "model_kind": comparison.model_kind,
+        "n_folds": comparison.selection.n_folds,
+        "n_candidates": comparison.selection.n_candidates,
+        "candidate_n_states": comparison.selection.candidate_n_states.tolist(),
+        "n_seeds": len(comparison.model_seeds),
+        "model_seeds": list(comparison.model_seeds),
+        "n_subjects": len(comparison.subjects),
+        "best_n_states": comparison.selection.best_n_states,
+        "one_standard_error_n_states": comparison.selection.one_standard_error_n_states,
+    }

dfckit/commands/source.py

@@ -0,0 +1,245 @@
+"""Command handlers that turn XCP-D outputs into analysis artifacts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+from ..connectivity import ETS, MTD, LEiDA, SlidingWindowFC
+from ..data import TimeSeriesDataset
+from ..information import (
+    compute_fixed_information,
+    load_fixed_window_schedule,
+    load_information_groups,
+    save_fixed_information,
+)
+from ..io import discover_xcpd_runs, load_xcpd_dataset
+from ..storage import (
+    write_cap_store,
+    write_instantaneous_edge_store,
+    write_leida_store,
+    write_window_fc_store,
+)
+
+
+def load_roi_selection(path: Path | None) -> dict[str, tuple[str, ...]] | None:
+    """Load and validate an atlas-to-ROI selection mapping."""
+    if path is None:
+        return None
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read ROI selection JSON {path}: {error}") from error
+    if not isinstance(raw, dict) or not raw:
+        raise ValueError("ROI selection must be a non-empty JSON object")
+    output: dict[str, tuple[str, ...]] = {}
+    for atlas, names in raw.items():
+        if not isinstance(atlas, str) or not atlas.strip():
+            raise ValueError("ROI selection atlas names must be non-empty strings")
+        if isinstance(names, str) or not isinstance(names, Sequence) or not names:
+            raise ValueError(f"ROI selection for {atlas!r} must be a non-empty array")
+        selected = tuple(str(name) for name in names)
+        if any(not name.strip() for name in selected) or len(set(selected)) != len(selected):
+            raise ValueError(f"ROI selection for {atlas!r} must contain unique non-empty names")
+        output[atlas] = selected
+    return output
+
+
+def xcpd_filters(
+    namespace: argparse.Namespace,
+    *,
+    subject: str | None = None,
+) -> dict[str, object]:
+    """Build the discovery filters shared by XCP-D commands."""
+    return {
+        "atlases": tuple(namespace.atlas),
+        "subject": subject,
+        "session": namespace.session,
+        "task": namespace.task,
+        "space": namespace.space,
+    }
+
+
+def selected_xcpd_subjects(namespace: argparse.Namespace) -> tuple[str | None, ...]:
+    """Normalize an optional repeated ``--subject`` selection."""
+    subjects = namespace.subject
+    if subjects is None:
+        return (None,)
+    values = tuple(str(subject).strip().removeprefix("sub-") for subject in subjects)
+    if any(not subject for subject in values):
+        raise ValueError("--subject values must be non-empty")
+    normalized = tuple(f"sub-{subject}" for subject in values)
+    unique = tuple(dict.fromkeys(normalized))
+    if len(unique) != len(subjects):
+        raise ValueError("--subject values must be unique")
+    return unique
+
+
+def discover_selected_xcpd_runs(namespace: argparse.Namespace):
+    """Discover runs for the selected subject set."""
+    discovered = []
+    for subject in selected_xcpd_subjects(namespace):
+        discovered.extend(
+            discover_xcpd_runs(namespace.root, **xcpd_filters(namespace, subject=subject))
+        )
+    return tuple(discovered)
+
+
+def inspect_xcpd(namespace: argparse.Namespace) -> dict[str, object]:
+    """Describe matching XCP-D acquisitions without loading their time series."""
+    files = discover_selected_xcpd_runs(namespace)
+    acquisitions = []
+    for item in files:
+        stem = item.outliers.name.removesuffix("_outliers.tsv")
+        entities = {
+            token.split("-", 1)[0]: token.split("-", 1)[1]
+            for token in stem.split("_")
+            if "-" in token
+        }
+        acquisitions.append(
+            {
+                "acquisition_id": stem,
+                "subject": entities.get("sub"),
+                "session": entities.get("ses"),
+                "task": entities.get("task"),
+                "atlases": [atlas.atlas for atlas in item.atlases],
+                "files": {
+                    atlas.atlas: {
+                        "timeseries": str(atlas.timeseries),
+                        "coverage": str(atlas.coverage),
+                    }
+                    for atlas in item.atlases
+                },
+                "outliers": str(item.outliers),
+                "motion": None if item.motion is None else str(item.motion),
+            }
+        )
+    return {"n_acquisitions": len(acquisitions), "acquisitions": acquisitions}
+
+
+def _load_selected_dataset(namespace: argparse.Namespace) -> TimeSeriesDataset:
+    selection = load_roi_selection(namespace.roi_selection)
+    datasets = tuple(
+        load_xcpd_dataset(
+            namespace.root,
+            roi_names=selection,
+            minimum_coverage=namespace.minimum_coverage,
+            tr=namespace.tr,
+            **xcpd_filters(namespace, subject=subject),
+        )
+        for subject in selected_xcpd_subjects(namespace)
+    )
+    return TimeSeriesDataset(tuple(run for item in datasets for run in item.runs))
+
+
+def build_store(namespace: argparse.Namespace) -> dict[str, object]:
+    """Build a disk-backed feature store from selected XCP-D runs."""
+    dataset = _load_selected_dataset(namespace)
+    if namespace.method == "window-fc":
+        estimator = SlidingWindowFC(
+            length=namespace.window_length,
+            step=namespace.window_step,
+            taper=namespace.taper,
+        )
+        store = write_window_fc_store(
+            namespace.output,
+            dataset.runs,
+            estimator,
+            chunk_size=namespace.chunk_size,
+            dtype=namespace.dtype,
+        )
+    elif namespace.method == "cap":
+        store = write_cap_store(
+            namespace.output,
+            dataset.runs,
+            chunk_size=namespace.chunk_size,
+            dtype=namespace.dtype,
+        )
+    elif namespace.method == "leida":
+        store = write_leida_store(
+            namespace.output,
+            dataset.runs,
+            LEiDA(minimum_segment_length=namespace.minimum_segment_length),
+            chunk_size=namespace.chunk_size,
+            dtype=namespace.dtype,
+        )
+    elif namespace.method == "ets":
+        store = write_instantaneous_edge_store(
+            namespace.output,
+            dataset.runs,
+            ETS(),
+            chunk_size=namespace.chunk_size,
+            dtype=namespace.dtype,
+        )
+    else:
+        store = write_instantaneous_edge_store(
+            namespace.output,
+            dataset.runs,
+            MTD(),
+            chunk_size=namespace.chunk_size,
+            dtype=namespace.dtype,
+        )
+    return {
+        "method": namespace.method,
+        "output": str(store.root),
+        "n_runs": dataset.n_runs,
+        "subjects": list(dataset.subjects),
+        "acquisition_ids": [run.acquisition_id for run in dataset.runs],
+        "n_sequences": store.n_sequences,
+        "n_samples": store.n_samples,
+        "n_chunks": store.n_chunks,
+        "n_features": store.n_features,
+        "format_version": store.format_version,
+    }
+
+
+def fixed_information(namespace: argparse.Namespace) -> dict[str, object]:
+    """Compute and persist fixed-length MI and CMI endpoints."""
+    if namespace.jobs < 1:
+        raise ValueError("--jobs must be at least 1")
+    dataset = _load_selected_dataset(namespace)
+    groups = load_information_groups(namespace.information_groups)
+    schedule = (
+        None
+        if namespace.window_schedule is None
+        else load_fixed_window_schedule(namespace.window_schedule)
+    )
+    artifact = compute_fixed_information(
+        dataset,
+        groups,
+        lengths=namespace.length,
+        draws=namespace.draws,
+        sample_seed=namespace.sample_seed,
+        schedule=schedule,
+        schedule_source=(
+            None if namespace.window_schedule is None else str(namespace.window_schedule)
+        ),
+        k=namespace.k,
+        jitter=namespace.jitter,
+        jitter_seed=namespace.jitter_seed,
+        standardize=namespace.standardize,
+        jobs=namespace.jobs,
+    )
+    output = save_fixed_information(artifact, namespace.output)
+    return {
+        "acquisition_ids": [item.acquisition_id for item in artifact.acquisitions],
+        "conditioning_rois": (
+            [] if artifact.groups.conditioning is None else list(artifact.groups.conditioning)
+        ),
+        "draws_per_length": artifact.draws_per_length,
+        "format_version": artifact.format_version,
+        "has_cmi": artifact.has_cmi,
+        "left_rois": list(artifact.groups.left),
+        "lengths": list(artifact.lengths),
+        "method": "fixed-information",
+        "n_draws": artifact.n_draws,
+        "n_runs": len(artifact.acquisitions),
+        "n_cells": artifact.n_cells,
+        "jobs": namespace.jobs,
+        "output": str(output),
+        "right_rois": list(artifact.groups.right),
+        "schedule_mode": artifact.schedule_mode,
+        "subjects": list(dataset.subjects),
+    }

dfckit/commands/stability.py

@@ -0,0 +1,288 @@
+"""Command handlers for state alignment and repeated-fit stability."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..artifacts import (
+    StatePredictions,
+    load_fitted_model,
+    load_state_predictions,
+    save_fitted_model,
+    save_state_alignment,
+    save_state_predictions,
+    write_state_stability,
+)
+from ..states.alignment import (
+    align_gaussian_hmm_emissions,
+    align_kmeans_centroids,
+    apply_gaussian_hmm_alignment,
+    apply_state_alignment,
+    relabel_gaussian_hmm_model,
+    relabel_kmeans_model,
+)
+from ..states.data import StateAssignments
+from ..states.hmm import GaussianHMMStateModel, GaussianHMMStateResult
+from ..states.kmeans import KMeansStateModel
+from ..states.stability import summarize_state_stability
+from ..states.streaming import predict_kmeans_store
+from ..states.streaming_hmm import predict_gaussian_hmm_store
+from ..storage import FeatureStore
+from .states import selected_store_subjects
+
+
+def _requested_alignment_metric(
+    namespace: argparse.Namespace,
+    model: KMeansStateModel | GaussianHMMStateModel,
+) -> str:
+    requested = getattr(namespace, "alignment_metric", "auto")
+    if requested == "auto":
+        return "pearson" if model.source_contract.startswith("cap:") else "euclidean"
+    return str(requested)
+
+
+def align_states(namespace: argparse.Namespace) -> dict[str, object]:
+    """Align a candidate model and optional predictions to a reference model."""
+    reference = load_fitted_model(namespace.reference_model)
+    candidate = load_fitted_model(namespace.candidate_model)
+    if type(reference) is not type(candidate):
+        raise TypeError("reference and candidate models must use the same state-model family")
+    alignment_metric = _requested_alignment_metric(namespace, reference)
+    if isinstance(reference, KMeansStateModel):
+        alignment = align_kmeans_centroids(
+            reference,
+            candidate,
+            metric=alignment_metric,
+        )
+        aligned_model = relabel_kmeans_model(candidate, alignment)
+        model_kind = "kmeans-state"
+    elif isinstance(reference, GaussianHMMStateModel):
+        alignment = align_gaussian_hmm_emissions(
+            reference,
+            candidate,
+            metric=alignment_metric,
+        )
+        aligned_model = relabel_gaussian_hmm_model(candidate, alignment)
+        model_kind = "gaussian-hmm-state"
+    else:
+        raise TypeError("align-states requires KMeans or Gaussian HMM model artifacts")
+
+    prediction_output = namespace.predictions_output
+    if (namespace.predictions is None) != (prediction_output is None):
+        raise ValueError("--predictions and --predictions-output must be provided together")
+    aligned_predictions = None
+    if namespace.predictions is not None:
+        predictions = load_state_predictions(namespace.predictions)
+        if predictions.model_kind != model_kind:
+            raise ValueError("prediction artifact and candidate model use different model families")
+        if predictions.model_seed != candidate.seed:
+            raise ValueError("prediction artifact seed does not match the candidate model")
+        if model_kind == "kmeans-state":
+            aligned_assignments = apply_state_alignment(predictions.assignments, alignment)
+            aligned_predictions = StatePredictions(
+                assignments=aligned_assignments,
+                model_kind=model_kind,
+                model_seed=candidate.seed,
+            )
+        else:
+            if predictions.posterior_probabilities is None or predictions.log_likelihood is None:
+                raise ValueError("HMM prediction artifact is missing posterior information")
+            result = GaussianHMMStateResult(
+                assignments=predictions.assignments,
+                posterior_probabilities=predictions.posterior_probabilities,
+                log_likelihood=predictions.log_likelihood,
+            )
+            aligned_result = apply_gaussian_hmm_alignment(result, alignment)
+            aligned_predictions = StatePredictions(
+                assignments=aligned_result.assignments,
+                model_kind=model_kind,
+                model_seed=candidate.seed,
+                posterior_probabilities=aligned_result.posterior_probabilities,
+                log_likelihood=aligned_result.log_likelihood,
+            )
+
+    output_paths = [namespace.output_model, namespace.alignment_output]
+    if aligned_predictions is not None:
+        output_paths.append(prediction_output)
+    normalized_outputs = [path.resolve(strict=False) for path in output_paths]
+    if len(set(normalized_outputs)) != len(normalized_outputs):
+        raise ValueError("align-states output paths must be distinct")
+    if any(path.exists() or path.is_symlink() for path in output_paths):
+        raise FileExistsError("one or more align-states output paths already exist")
+    alignment_path = save_state_alignment(alignment, namespace.alignment_output)
+    model_path = save_fitted_model(aligned_model, namespace.output_model)
+    prediction_path = None
+    if aligned_predictions is not None:
+        prediction_path = save_state_predictions(aligned_predictions, prediction_output)
+    return {
+        "model_kind": model_kind,
+        "reference_seed": alignment.reference_seed,
+        "candidate_seed": alignment.candidate_seed,
+        "candidate_to_reference": alignment.candidate_to_reference.tolist(),
+        "alignment_metric": alignment.metric,
+        "matched_costs": alignment.matched_costs.tolist(),
+        "output_model": str(model_path),
+        "alignment_output": str(alignment_path),
+        "predictions_output": None if prediction_path is None else str(prediction_path),
+    }
+
+
+def _repeated_fit_contract(
+    model: KMeansStateModel | GaussianHMMStateModel,
+) -> tuple[object, ...]:
+    common = (
+        type(model),
+        model.feature_keys,
+        model.source_contract,
+        model.sample_interval_seconds,
+        model.n_states,
+        model.fit_subjects,
+        model.fit_sample_count,
+        model.implementation,
+    )
+    if isinstance(model, KMeansStateModel):
+        return common + (
+            model.n_init,
+            model.max_iter,
+            model.algorithm,
+            model.standardize_features,
+            model.batch_size,
+            model.reassignment_ratio,
+            model.init_sample_size,
+        )
+    return common + (
+        model.fit_sequence_count,
+        model.omitted_short_sequence_count,
+        model.n_pca_components,
+        model.covariance_type,
+        model.n_init,
+        model.n_iter,
+        model.tol,
+        model.minimum_sequence_length,
+        model.pca_batch_size,
+    )
+
+
+def _require_complete_repeated_fit_provenance(
+    model: KMeansStateModel | GaussianHMMStateModel,
+) -> None:
+    if (
+        isinstance(model, KMeansStateModel)
+        and model.algorithm == "minibatch"
+        and "out-of-core" in model.implementation
+        and model.init_sample_size is None
+    ):
+        raise ValueError("out-of-core KMeans stability requires a recorded init_sample_size")
+    if (
+        isinstance(model, GaussianHMMStateModel)
+        and "IncrementalPCA" in model.implementation
+        and model.pca_batch_size is None
+    ):
+        raise ValueError("out-of-core HMM stability requires a recorded pca_batch_size")
+
+def _decode_assignments(
+    model: KMeansStateModel | GaussianHMMStateModel,
+    store: FeatureStore,
+    *,
+    subjects: tuple[str, ...] | None,
+    allow_fit_subjects: bool,
+) -> StateAssignments:
+    if isinstance(model, KMeansStateModel):
+        return predict_kmeans_store(
+            model,
+            store,
+            subjects=subjects,
+            allow_fit_subjects=allow_fit_subjects,
+        )
+    return predict_gaussian_hmm_store(
+        model,
+        store,
+        subjects=subjects,
+        allow_fit_subjects=allow_fit_subjects,
+    ).assignments
+
+
+def summarize_stability(namespace: argparse.Namespace) -> dict[str, object]:
+    """Align repeated state fits and summarize their run-level agreement."""
+    if namespace.output.exists() or namespace.output.is_symlink():
+        raise FileExistsError(f"state-stability output path already exists: {namespace.output}")
+    store = FeatureStore.open(namespace.store)
+    subjects = selected_store_subjects(store, namespace.subject)
+    reference = load_fitted_model(namespace.reference_model)
+    candidates = tuple(load_fitted_model(path) for path in namespace.candidate_model)
+    if not isinstance(reference, (KMeansStateModel, GaussianHMMStateModel)):
+        raise TypeError("summarize-stability requires a KMeans or Gaussian HMM reference")
+    if any(type(candidate) is not type(reference) for candidate in candidates):
+        raise TypeError("all stability models must use the same state-model family")
+    for model in (reference, *candidates):
+        _require_complete_repeated_fit_provenance(model)
+    if any(candidate.fit_subjects != reference.fit_subjects for candidate in candidates):
+        raise ValueError("stability models must use the same training subjects")
+    if any(candidate.fit_sample_count != reference.fit_sample_count for candidate in candidates):
+        raise ValueError("stability models must use the same fitted sample count")
+    reference_contract = _repeated_fit_contract(reference)
+    if any(_repeated_fit_contract(candidate) != reference_contract for candidate in candidates):
+        raise ValueError(
+            "stability models must share training subjects, fitted samples, and hyperparameters"
+        )
+    seeds = tuple(model.seed for model in (reference, *candidates))
+    if len(set(seeds)) != len(seeds):
+        raise ValueError("stability models must use distinct seeds")
+
+    reference_assignments = _decode_assignments(
+        reference,
+        store,
+        subjects=subjects,
+        allow_fit_subjects=namespace.allow_fit_subjects,
+    )
+    aligned_assignments = [reference_assignments]
+    alignments = []
+    alignment_metric = _requested_alignment_metric(namespace, reference)
+    for candidate in candidates:
+        candidate_assignments = _decode_assignments(
+            candidate,
+            store,
+            subjects=subjects,
+            allow_fit_subjects=namespace.allow_fit_subjects,
+        )
+        if isinstance(reference, KMeansStateModel):
+            alignment = align_kmeans_centroids(
+                reference,
+                candidate,
+                metric=alignment_metric,
+            )
+        else:
+            alignment = align_gaussian_hmm_emissions(
+                reference,
+                candidate,
+                metric=alignment_metric,
+            )
+        alignments.append(alignment)
+        aligned_assignments.append(apply_state_alignment(candidate_assignments, alignment))
+    stability = summarize_state_stability(aligned_assignments)
+    model_kind = "kmeans-state" if isinstance(reference, KMeansStateModel) else "gaussian-hmm-state"
+    output = write_state_stability(
+        stability,
+        namespace.output,
+        model_kind=model_kind,
+        reference_seed=reference.seed,
+        candidate_seeds=tuple(candidate.seed for candidate in candidates),
+        alignments=tuple(alignments),
+        source_contract=store.source_contract,
+        sample_interval_seconds=store.sample_interval_seconds,
+        allow_fit_subjects=namespace.allow_fit_subjects,
+    )
+    return {
+        "output": str(output),
+        "model_kind": model_kind,
+        "reference_seed": reference.seed,
+        "candidate_seeds": [candidate.seed for candidate in candidates],
+        "subjects": list(dict.fromkeys(run.subject for run in stability)),
+        "n_fits": len(aligned_assignments),
+        "n_states": reference.n_states,
+        "n_runs": len(stability),
+        "n_sequences": sum(run.n_sequences for run in stability),
+        "n_samples": sum(run.n_samples for run in stability),
+        "allow_fit_subjects": bool(namespace.allow_fit_subjects),
+        "alignment_metric": alignment_metric,
+    }