dfc-kit 1.0.0__py3-none-any.whl

dfckit/artifacts/state_stability.py

@@ -0,0 +1,207 @@
+"""Machine-readable persistence for aligned repeated-fit state stability."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .._validation import validated_nonnegative_integer as _seed
+from ..states.alignment import StateAlignment
+from ..states.stability import RunStateStability
+from ._json import write_json_atomic
+
+FORMAT_NAME = "dfckit-state-stability"
+FORMAT_VERSION = 3
+
+
+def _optional_float(value: float | None) -> float | None:
+    if value is None:
+        return None
+    output = float(value)
+    if not np.isfinite(output) or output <= 0.0:
+        raise ValueError("sample_interval_seconds must be finite and positive")
+    return output
+
+
+def _json_values(values: NDArray[np.float64]) -> object:
+    array = np.asarray(values, dtype=float)
+    if np.isinf(array).any():
+        raise ValueError("state stability metrics cannot contain infinite values")
+    if array.ndim == 0:
+        return None if np.isnan(array) else float(array)
+    return [_json_values(item) for item in array]
+
+
+def _aggregate(values: NDArray[np.float64]) -> dict[str, object]:
+    array = np.asarray(values, dtype=float)
+    if array.ndim < 1 or array.shape[0] < 2:
+        raise ValueError("state stability aggregation requires at least two fitted values")
+    if np.isinf(array).any():
+        raise ValueError("state stability metrics cannot contain infinite values")
+    finite = np.isfinite(array)
+    counts = finite.sum(axis=0)
+    total = np.where(finite, array, 0.0).sum(axis=0)
+    mean = np.divide(
+        total,
+        counts,
+        out=np.full(counts.shape, np.nan, dtype=float),
+        where=counts > 0,
+    )
+    centered = np.where(finite, array - mean, 0.0)
+    variance = np.divide(
+        np.square(centered).sum(axis=0),
+        counts,
+        out=np.full(counts.shape, np.nan, dtype=float),
+        where=counts > 1,
+    )
+    standard_deviation = np.sqrt(variance)
+    return {
+        "by_fit": _json_values(array),
+        "mean": _json_values(mean),
+        "standard_deviation": _json_values(standard_deviation),
+        "valid_fit_count": np.asarray(counts, dtype=int).tolist(),
+    }
+
+
+def _fit_records(
+    *,
+    n_states: int,
+    reference_seed: int,
+    candidate_seeds: Sequence[int],
+    alignments: Sequence[StateAlignment],
+) -> list[dict[str, object]]:
+    seeds = (
+        _seed(reference_seed, "reference_seed"),
+        *(_seed(value, "candidate_seed") for value in candidate_seeds),
+    )
+    alignments = tuple(alignments)
+    if len(seeds) < 2:
+        raise ValueError("state stability requires at least two fits")
+    if len(alignments) != len(seeds) - 1:
+        raise ValueError("state stability alignment count does not match candidate fits")
+    records = [
+        {
+            "fit_index": 0,
+            "role": "reference",
+            "model_seed": seeds[0],
+            "candidate_to_reference": list(range(n_states)),
+            "matched_costs": [0.0] * n_states,
+            "cost_matrix": None,
+            "alignment_metric": "identity",
+        }
+    ]
+    for index, (seed, alignment) in enumerate(
+        zip(seeds[1:], alignments, strict=True),
+        start=1,
+    ):
+        if len(alignment.candidate_to_reference) != n_states:
+            raise ValueError("state stability alignment does not match n_states")
+        if alignment.reference_seed != seeds[0] or alignment.candidate_seed != seed:
+            raise ValueError("state stability alignment seed identity is inconsistent")
+        records.append(
+            {
+                "fit_index": index,
+                "role": "candidate",
+                "model_seed": seed,
+                "candidate_to_reference": alignment.candidate_to_reference.tolist(),
+                "matched_costs": alignment.matched_costs.tolist(),
+                "cost_matrix": alignment.cost_matrix.tolist(),
+                "alignment_metric": alignment.metric,
+            }
+        )
+    return records
+
+
+def _state_stability_payload(
+    runs: Sequence[RunStateStability],
+    *,
+    model_kind: str,
+    reference_seed: int,
+    candidate_seeds: Sequence[int],
+    alignments: Sequence[StateAlignment],
+    source_contract: str,
+    sample_interval_seconds: float | None,
+    allow_fit_subjects: bool,
+) -> dict[str, object]:
+    """Build a JSON-safe report with reference-numbered metrics for every fit."""
+    runs = tuple(runs)
+    if not runs:
+        raise ValueError("state stability report requires at least one run")
+    if model_kind not in {"kmeans-state", "gaussian-hmm-state"}:
+        raise ValueError("state stability model_kind is invalid")
+    if not str(source_contract).strip():
+        raise ValueError("state stability source_contract must be non-empty")
+    if not isinstance(allow_fit_subjects, (bool, np.bool_)):
+        raise TypeError("allow_fit_subjects must be boolean")
+    interval = _optional_float(sample_interval_seconds)
+    n_fits = runs[0].n_fits
+    n_states = runs[0].n_states
+    if any(run.n_fits != n_fits or run.n_states != n_states for run in runs):
+        raise ValueError("state stability runs must have identical fit and state counts")
+    fit_records = _fit_records(
+        n_states=n_states,
+        reference_seed=reference_seed,
+        candidate_seeds=candidate_seeds,
+        alignments=alignments,
+    )
+    if len(fit_records) != n_fits:
+        raise ValueError("state stability fit identities do not match metric fit count")
+    run_records = []
+    for run in runs:
+        run_records.append(
+            {
+                "subject": run.subject,
+                "session": run.session,
+                "acquisition_id": run.acquisition_id,
+                "n_samples": run.n_samples,
+                "n_sequences": run.n_sequences,
+                "occupancy": _aggregate(run.occupancy_by_fit),
+                "mean_dwell_samples": _aggregate(run.mean_dwell_samples_by_fit),
+                "mean_dwell_seconds": _aggregate(run.mean_dwell_seconds_by_fit),
+                "switch_rate": _aggregate(run.switch_rate_by_fit),
+                "transition_probabilities": _aggregate(
+                    run.transition_probabilities_by_fit
+                ),
+            }
+        )
+    subjects = list(dict.fromkeys(run.subject for run in runs))
+    return {
+        "format": FORMAT_NAME,
+        "format_version": FORMAT_VERSION,
+        "model_kind": model_kind,
+        "reference_seed": fit_records[0]["model_seed"],
+        "state_numbering": "reference-model state indices",
+        "dispersion_standard_deviation": (
+            "population standard deviation across fits (ddof=0); null when fewer "
+            "than two finite values are available"
+        ),
+        "n_fits": n_fits,
+        "n_states": n_states,
+        "n_runs": len(runs),
+        "n_sequences": sum(run.n_sequences for run in runs),
+        "n_samples": sum(run.n_samples for run in runs),
+        "subjects": subjects,
+        "source_contract": str(source_contract),
+        "sample_interval_seconds": interval,
+        "allow_fit_subjects": bool(allow_fit_subjects),
+        "fits": fit_records,
+        "runs": run_records,
+    }
+
+
+def write_state_stability(
+    runs: Sequence[RunStateStability],
+    path: str | Path,
+    **metadata: object,
+) -> Path:
+    """Atomically write an aligned repeated-fit stability report as strict JSON."""
+    payload = _state_stability_payload(runs, **metadata)
+    return write_json_atomic(path, payload)
+
+
+__all__ = [
+    "write_state_stability",
+]

dfckit/cli.py

@@ -0,0 +1,105 @@
+"""Small command-line adapters for the XCP-D-first workflows."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from .commands.parser import build_parser
+from .commands.reporting import (
+    compare_state_counts as _compare_state_counts,
+)
+from .commands.reporting import (
+    describe_states as _describe_states,
+)
+from .commands.reporting import (
+    infer_endpoints as _infer_endpoints,
+)
+from .commands.reporting import (
+    infer_state_metrics as _infer_state_metrics,
+)
+from .commands.reporting import (
+    summarize_information as _summarize_information,
+)
+from .commands.reporting import (
+    summarize_store as _summarize_store,
+)
+from .commands.source import (
+    build_store as _build_store,
+)
+from .commands.source import (
+    fixed_information as _fixed_information,
+)
+from .commands.source import (
+    inspect_xcpd as _inspect,
+)
+from .commands.stability import (
+    align_states as _align_states,
+)
+from .commands.stability import (
+    summarize_stability as _summarize_stability,
+)
+from .commands.states import (
+    fit_states as _fit_states,
+)
+from .commands.states import (
+    predict_states as _predict_states,
+)
+from .commands.states import (
+    score_states as _score_states,
+)
+from .commands.states import (
+    summarize_states as _summarize_states,
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    return build_parser()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run a CLI command and return a process-style status code."""
+    parser = _parser()
+    namespace = parser.parse_args(argv)
+    try:
+        if namespace.command == "inspect-xcpd":
+            result = _inspect(namespace)
+        elif namespace.command == "build-store":
+            result = _build_store(namespace)
+        elif namespace.command == "fixed-information":
+            result = _fixed_information(namespace)
+        elif namespace.command == "fit-states":
+            result = _fit_states(namespace)
+        elif namespace.command == "predict-states":
+            result = _predict_states(namespace)
+        elif namespace.command == "summarize-states":
+            result = _summarize_states(namespace)
+        elif namespace.command == "summarize-store":
+            result = _summarize_store(namespace)
+        elif namespace.command == "summarize-information":
+            result = _summarize_information(namespace)
+        elif namespace.command == "describe-states":
+            result = _describe_states(namespace)
+        elif namespace.command == "infer-state-metrics":
+            result = _infer_state_metrics(namespace)
+        elif namespace.command == "infer-paired-endpoints":
+            result = _infer_endpoints(namespace)
+        elif namespace.command == "score-states":
+            result = _score_states(namespace)
+        elif namespace.command == "compare-state-counts":
+            result = _compare_state_counts(namespace)
+        elif namespace.command == "align-states":
+            result = _align_states(namespace)
+        else:
+            result = _summarize_stability(namespace)
+    except (ImportError, OSError, RuntimeError, TypeError, ValueError) as error:
+        print(f"dfc-kit: error: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

dfckit/commands/__init__.py

@@ -0,0 +1 @@
+"""Internal command handlers used by :mod:`dfckit.cli`."""

dfckit/commands/parser.py

@@ -0,0 +1,354 @@
+"""Argument parser construction for the dfc-kit command line."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def _add_xcpd_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("root", type=Path, help="XCP-D derivatives root")
+    parser.add_argument(
+        "--atlas",
+        action="append",
+        required=True,
+        help="atlas name; repeat for multiple atlases",
+    )
+    parser.add_argument(
+        "--subject",
+        action="append",
+        help="optional BIDS subject label or value; repeat to select multiple subjects",
+    )
+    parser.add_argument("--session", help="optional BIDS session label or value")
+    parser.add_argument("--task", help="optional BIDS task label or value")
+    parser.add_argument("--space", help="optional XCP-D standard-space label")
+
+
+def _add_load_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--roi-selection",
+        type=Path,
+        help="JSON object mapping atlas names to ordered ROI-name arrays",
+    )
+    parser.add_argument(
+        "--minimum-coverage",
+        type=float,
+        default=None,
+        help="reject selected ROIs below this XCP-D coverage fraction",
+    )
+    parser.add_argument("--tr", type=float, default=None, help="run TR in seconds")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the complete command-line parser."""
+    parser = argparse.ArgumentParser(
+        prog="dfc-kit",
+        description="Censor-aware XCP-D to dynamic-connectivity workflows",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    inspect = subparsers.add_parser(
+        "inspect-xcpd",
+        help="list matching XCP-D acquisitions without loading time series",
+    )
+    _add_xcpd_arguments(inspect)
+
+    build = subparsers.add_parser(
+        "build-store",
+        help="load XCP-D acquisitions and stream a feature store",
+    )
+    _add_xcpd_arguments(build)
+    _add_load_arguments(build)
+    build.add_argument("output", type=Path, help="new FeatureStore directory")
+    build.add_argument(
+        "--method",
+        choices=("window-fc", "cap", "ets", "leida", "mtd"),
+        required=True,
+    )
+    build.add_argument("--chunk-size", type=int, default=128)
+    build.add_argument("--dtype", choices=("float32", "float64"), default="float64")
+    build.add_argument("--window-length", type=int, default=56)
+    build.add_argument("--window-step", type=int, default=8)
+    build.add_argument("--taper", choices=("hamming", "uniform"), default="hamming")
+    build.add_argument("--minimum-segment-length", type=int, default=20)
+
+    information = subparsers.add_parser(
+        "fixed-information",
+        help="estimate fixed-length block MI/CMI from XCP-D acquisitions",
+    )
+    _add_xcpd_arguments(information)
+    _add_load_arguments(information)
+    information.add_argument(
+        "output",
+        type=Path,
+        help="new fixed-information artifact directory",
+    )
+    information.add_argument(
+        "--information-groups",
+        type=Path,
+        required=True,
+        help="standalone JSON declaring named left, right, and conditioning ROI groups",
+    )
+    information.add_argument(
+        "--length",
+        action="append",
+        type=int,
+        required=True,
+        help="fixed retained-frame length; repeat for a sensitivity set",
+    )
+    information.add_argument("--draws", type=int, required=True)
+    information.add_argument("--sample-seed", type=int, required=True)
+    information.add_argument(
+        "--jobs",
+        type=int,
+        default=1,
+        help="validated execution parallelism (default: 1)",
+    )
+    information.add_argument(
+        "--window-schedule",
+        type=Path,
+        help="optional strict TSV freezing acquisition, length, draw, and original frame bounds",
+    )
+    information.add_argument("--k", type=int, default=3)
+    information.add_argument("--jitter", type=float, default=1e-10)
+    information.add_argument("--jitter-seed", type=int, default=20260811)
+    information.add_argument(
+        "--standardize",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="z-score each ROI within each fixed window (default: enabled)",
+    )
+
+    fit = subparsers.add_parser(
+        "fit-states",
+        help="fit a portable KMeans or Gaussian HMM model from a FeatureStore",
+    )
+    fit.add_argument("store", type=Path, help="existing FeatureStore directory")
+    fit.add_argument("output", type=Path, help="new fitted-model artifact directory")
+    fit.add_argument("--method", choices=("kmeans", "hmm"), required=True)
+    fit.add_argument("--n-states", type=int, required=True)
+    fit.add_argument("--seed", type=int, required=True)
+    fit.add_argument(
+        "--subject",
+        action="append",
+        help="fit only this subject; repeat for an explicit training cohort",
+    )
+    fit.add_argument(
+        "--n-init",
+        type=int,
+        default=None,
+        help="initializations (default: 10 for KMeans, 1 for HMM)",
+    )
+    fit.add_argument(
+        "--standardize-features",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+    )
+    fit.add_argument("--fitting-mode", choices=("streaming", "materialized"), default="streaming")
+    fit.add_argument("--algorithm", choices=("lloyd", "minibatch"), default="minibatch")
+    fit.add_argument("--batch-size", type=int, default=4096)
+    fit.add_argument("--max-iter", type=int, default=10)
+    fit.add_argument("--reassignment-ratio", type=float, default=0.01)
+    fit.add_argument("--init-sample-size", type=int, default=None)
+    fit.add_argument(
+        "--n-pca-components",
+        type=int,
+        default=None,
+        help="optional PCA dimension for KMeans; required for HMM",
+    )
+    fit.add_argument("--covariance-type", choices=("diag", "full"), default="diag")
+    fit.add_argument("--n-iter", type=int, default=200)
+    fit.add_argument("--tol", type=float, default=1e-3)
+    fit.add_argument("--pca-batch-size", type=int, default=4096)
+    fit.add_argument("--minimum-sequence-length", type=int, default=2)
+
+    predict = subparsers.add_parser(
+        "predict-states",
+        help="decode a FeatureStore with a saved KMeans or Gaussian HMM",
+    )
+    predict.add_argument("store", type=Path, help="FeatureStore to decode")
+    predict.add_argument("model", type=Path, help="saved fitted-model artifact")
+    predict.add_argument("output", type=Path, help="new state-prediction artifact directory")
+    predict.add_argument(
+        "--subject",
+        action="append",
+        help="decode only this subject; repeat for an explicit held-out cohort",
+    )
+    predict.add_argument(
+        "--allow-fit-subjects",
+        action="store_true",
+        help="explicitly allow decoding subjects used during model fitting",
+    )
+
+    summarize = subparsers.add_parser(
+        "summarize-states",
+        help="write occupancy, dwell, switch, and transition metrics as JSON",
+    )
+    summarize.add_argument("predictions", type=Path, help="state-prediction artifact directory")
+    summarize.add_argument("output", type=Path, help="new state-metrics JSON file")
+
+    summarize_features = subparsers.add_parser(
+        "summarize-store",
+        help="write acquisition-level statistics for every named FeatureStore feature",
+    )
+    summarize_features.add_argument("store", type=Path, help="FeatureStore to summarize")
+    summarize_features.add_argument("output", type=Path, help="new endpoint-summary JSON file")
+    summarize_features.add_argument(
+        "--statistic",
+        action="append",
+        choices=("mean", "variance", "standard_deviation", "minimum", "maximum"),
+        default=None,
+        help="statistic to compute; repeat for multiple statistics (default: mean)",
+    )
+
+    summarize_information = subparsers.add_parser(
+        "summarize-information",
+        help="extract acquisition-level MI and CMI endpoints from an audited artifact",
+    )
+    summarize_information.add_argument("artifact", type=Path)
+    summarize_information.add_argument("output", type=Path)
+
+    describe = subparsers.add_parser(
+        "describe-states",
+        help="describe state patterns using named ROI or edge features",
+    )
+    describe.add_argument("store", type=Path, help="FeatureStore used to fit the model")
+    describe.add_argument("model", type=Path, help="saved KMeans or Gaussian HMM artifact")
+    describe.add_argument("output", type=Path, help="new state-description JSON file")
+    describe.add_argument("--top-features", type=int, default=10)
+    describe.add_argument(
+        "--network-map",
+        type=Path,
+        help="optional JSON object mapping every model ROI to a network label",
+    )
+
+    infer_states = subparsers.add_parser(
+        "infer-state-metrics",
+        help="run paired sign-flip inference and declared-family FDR over state metrics",
+    )
+    infer_states.add_argument("metrics", type=Path, help="state-metrics JSON file")
+    infer_states.add_argument("output", type=Path, help="new inference artifact directory")
+    infer_states.add_argument("--condition-a", required=True)
+    infer_states.add_argument("--condition-b", required=True)
+    infer_states.add_argument(
+        "--metric",
+        action="append",
+        choices=(
+            "occupancy",
+            "mean_dwell_seconds",
+            "switch_rate",
+            "transition_probabilities",
+        ),
+        required=True,
+    )
+    infer_states.add_argument("--fdr-family", required=True)
+    infer_states.add_argument("--alpha", type=float, default=0.05)
+    infer_states.add_argument("--permutations", type=int, default=10_000)
+    infer_states.add_argument("--bootstrap", type=int, default=10_000)
+    infer_states.add_argument("--seed", type=int, required=True)
+    infer_states.add_argument("--exact", action="store_true")
+
+    infer_endpoints = subparsers.add_parser(
+        "infer-paired-endpoints",
+        help="run paired sign-flip inference over a named endpoint JSON artifact",
+    )
+    infer_endpoints.add_argument("endpoints", type=Path)
+    infer_endpoints.add_argument("output", type=Path)
+    infer_endpoints.add_argument("--condition-a", required=True)
+    infer_endpoints.add_argument("--condition-b", required=True)
+    infer_endpoints.add_argument("--fdr-family", required=True)
+    infer_endpoints.add_argument("--alpha", type=float, default=0.05)
+    infer_endpoints.add_argument("--permutations", type=int, default=10_000)
+    infer_endpoints.add_argument("--bootstrap", type=int, default=10_000)
+    infer_endpoints.add_argument("--seed", type=int, required=True)
+    infer_endpoints.add_argument("--exact", action="store_true")
+
+    score = subparsers.add_parser(
+        "score-states",
+        help="score a saved KMeans or HMM on held-out FeatureStore acquisitions",
+    )
+    score.add_argument("store", type=Path, help="FeatureStore to score")
+    score.add_argument("model", type=Path, help="saved fitted-model artifact")
+    score.add_argument("output", type=Path, help="new held-out score JSON file")
+    score.add_argument(
+        "--subject",
+        action="append",
+        help="score only this subject; repeat for an explicit held-out cohort",
+    )
+    score.add_argument(
+        "--allow-fit-subjects",
+        action="store_true",
+        help="explicitly allow scoring subjects used during model fitting",
+    )
+
+    compare = subparsers.add_parser(
+        "compare-state-counts",
+        help="compare complete candidate-state sets across subject-disjoint folds",
+    )
+    compare.add_argument("output", type=Path, help="new state-count comparison JSON file")
+    compare.add_argument(
+        "--score",
+        action="append",
+        type=Path,
+        required=True,
+        help=(
+            "score-states JSON artifact; repeat for every fold, state count, "
+            "and complete-fit seed"
+        ),
+    )
+
+    align = subparsers.add_parser(
+        "align-states",
+        help="align a candidate KMeans/HMM model and optional predictions to a reference",
+    )
+    align.add_argument("reference_model", type=Path, help="reference fitted-model artifact")
+    align.add_argument("candidate_model", type=Path, help="candidate fitted-model artifact")
+    align.add_argument("output_model", type=Path, help="new relabeled model artifact")
+    align.add_argument("alignment_output", type=Path, help="new alignment artifact directory")
+    align.add_argument(
+        "--alignment-metric",
+        choices=("auto", "euclidean", "pearson"),
+        default="auto",
+        help="state-pattern matching metric (default: auto; CAP uses pearson)",
+    )
+    align.add_argument(
+        "--predictions",
+        type=Path,
+        help="candidate state-prediction artifact to relabel",
+    )
+    align.add_argument(
+        "--predictions-output",
+        type=Path,
+        help="new aligned state-prediction artifact directory",
+    )
+    stability = subparsers.add_parser(
+        "summarize-stability",
+        help="decode, align, and summarize repeated-seed state models",
+    )
+    stability.add_argument("store", type=Path, help="FeatureStore to decode identically")
+    stability.add_argument("reference_model", type=Path, help="reference fitted-model artifact")
+    stability.add_argument("output", type=Path, help="new repeated-fit stability JSON file")
+    stability.add_argument(
+        "--candidate-model",
+        action="append",
+        type=Path,
+        required=True,
+        help="candidate fitted model; repeat for every additional seed",
+    )
+    stability.add_argument(
+        "--alignment-metric",
+        choices=("auto", "euclidean", "pearson"),
+        default="auto",
+        help="state-pattern matching metric (default: auto; CAP uses pearson)",
+    )
+    stability.add_argument(
+        "--subject",
+        action="append",
+        help="decode only this subject; repeat for an explicit held-out cohort",
+    )
+    stability.add_argument(
+        "--allow-fit-subjects",
+        action="store_true",
+        help="explicitly allow decoding subjects used during model fitting",
+    )
+    return parser