dfc-kit 1.0.0__py3-none-any.whl

dfckit/connectivity/instantaneous.py

@@ -0,0 +1,253 @@
+"""Instantaneous edge products from ETS and MTD samples.
+
+ETS and MTD differ only in how they construct their time-aligned ROI rows.
+After that step both methods produce the same edge result, summaries, state
+sequences, and chunked stores.  The row representation is deliberately
+private: callers normally need the edge result, not another intermediate
+object to carry through the pipeline.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .._arrays import readonly_copy as _readonly
+from .._preprocessing import _segment_standardized_samples
+from ..data import TimeSeriesRun
+
+
+@dataclass(frozen=True)
+class _InstantaneousRows:
+    values: NDArray[np.float64]
+    starts: NDArray[np.int64]
+    ends: NDArray[np.int64]
+    segments: NDArray[np.int64]
+    roi_names: tuple[str, ...]
+    subject: str | None
+    session: str | None
+    sample_kind: str
+    contract: str
+    tr: float | None
+    acquisition_id: str | None
+
+
+class _InstantaneousEstimator:
+    """Small shared implementation for the two public estimators."""
+
+    def _rows(self, run: TimeSeriesRun) -> _InstantaneousRows:
+        raise NotImplementedError
+
+    def transform(self, run: TimeSeriesRun) -> InstantaneousEdgeResult:
+        return _result_from_rows(self._rows(run), materialize_edges=True)
+
+    def rss(self, run: TimeSeriesRun) -> InstantaneousEdgeResult:
+        return _result_from_rows(self._rows(run), materialize_edges=False)
+
+
+class ETS(_InstantaneousEstimator):
+    """Instantaneous edge products from segment-standardized BOLD values."""
+
+    def _rows(self, run: TimeSeriesRun) -> _InstantaneousRows:
+        values, indices, segments = _segment_standardized_samples(run, method_name="ETS")
+        return _InstantaneousRows(
+            values=values,
+            starts=indices,
+            ends=indices,
+            segments=segments,
+            roi_names=run.roi_names,
+            subject=run.subject,
+            session=run.session,
+            sample_kind="frame",
+            contract="ets:normalization=segment",
+            tr=run.tr,
+            acquisition_id=run.acquisition_id,
+        )
+
+
+def _standardized_derivatives(
+    run: TimeSeriesRun,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64], NDArray[np.int64]]:
+    """Return run-standardized derivatives without crossing censor gaps."""
+    values: list[NDArray[np.float64]] = []
+    starts: list[NDArray[np.int64]] = []
+    ends: list[NDArray[np.int64]] = []
+    segments: list[NDArray[np.int64]] = []
+    for segment_id, positions in enumerate(run.segments()):
+        if len(positions) < 2:
+            continue
+        values.append(np.diff(run.values[positions], axis=0))
+        original = run.original_indices[positions]
+        starts.append(original[:-1])
+        ends.append(original[1:])
+        segments.append(np.full(len(positions) - 1, segment_id, dtype=np.int64))
+    if not values:
+        raise ValueError("MTD requires at least one valid within-segment derivative")
+    derivatives = np.concatenate(values, axis=0)
+    scale = derivatives.std(axis=0, ddof=0)
+    invalid = np.flatnonzero((~np.isfinite(scale)) | (scale < 1e-8))
+    if len(invalid):
+        raise ValueError(f"MTD derivative scale is undefined for ROI indices {invalid.tolist()}")
+    standardized = (derivatives - derivatives.mean(axis=0)) / scale
+    if not np.isfinite(standardized).all():
+        raise ValueError("standardized MTD derivatives contain non-finite values")
+    return standardized, np.concatenate(starts), np.concatenate(ends), np.concatenate(segments)
+
+
+class MTD(_InstantaneousEstimator):
+    """Instantaneous edge products from standardized within-segment derivatives."""
+
+    def _rows(self, run: TimeSeriesRun) -> _InstantaneousRows:
+        values, starts, ends, segments = _standardized_derivatives(run)
+        return _InstantaneousRows(
+            values=values,
+            starts=starts,
+            ends=ends,
+            segments=segments,
+            roi_names=run.roi_names,
+            subject=run.subject,
+            session=run.session,
+            sample_kind="interval",
+            contract="mtd:difference=within-segment;normalization=run",
+            tr=run.tr,
+            acquisition_id=run.acquisition_id,
+        )
+
+
+@dataclass(frozen=True)
+class InstantaneousEdgeResult:
+    """One frame- or interval-aligned matrix of instantaneous edge products."""
+
+    features: NDArray[np.float64] | None
+    rss: NDArray[np.float64]
+    sample_start_frames: NDArray[np.int64]
+    sample_end_frames: NDArray[np.int64]
+    segment_ids: NDArray[np.int64]
+    edge_i: NDArray[np.int64]
+    edge_j: NDArray[np.int64]
+    roi_names: tuple[str, ...]
+    subject: str | None
+    session: str | None
+    sample_kind: str
+    source_contract: str
+    tr: float | None = None
+    acquisition_id: str | None = None
+
+    def __post_init__(self) -> None:
+        from .correlation import edge_index
+
+        features = None if self.features is None else np.asarray(self.features, dtype=float)
+        rss = np.asarray(self.rss, dtype=float)
+        starts = np.asarray(self.sample_start_frames, dtype=np.int64)
+        ends = np.asarray(self.sample_end_frames, dtype=np.int64)
+        segments = np.asarray(self.segment_ids, dtype=np.int64)
+        left = np.asarray(self.edge_i, dtype=np.int64)
+        right = np.asarray(self.edge_j, dtype=np.int64)
+        names = tuple(str(name) for name in self.roi_names)
+        if len(names) < 2 or len(set(names)) != len(names) or any(not name.strip() for name in names):
+            raise ValueError("roi_names must contain at least two unique non-empty names")
+        if rss.ndim != 1 or not len(rss) or not np.isfinite(rss).all():
+            raise ValueError("rss must be a non-empty finite one-dimensional array")
+        if any(array.ndim != 1 or len(array) != len(rss) for array in (starts, ends, segments)):
+            raise ValueError("sample metadata must align with rss")
+        if np.any(ends < starts) or np.any(segments < 0):
+            raise ValueError("sample intervals and segment IDs must be non-negative")
+        if len(starts) > 1 and np.any(np.diff(starts) <= 0):
+            raise ValueError("sample start frames must be strictly increasing")
+        expected_left, expected_right = edge_index(len(names))
+        if not np.array_equal(left, expected_left) or not np.array_equal(right, expected_right):
+            raise ValueError("edge endpoints must be the unique upper-triangular ROI order")
+        if features is not None:
+            if features.ndim != 2 or features.shape != (len(rss), len(left)):
+                raise ValueError("features must align with samples and edge endpoints")
+            if not np.isfinite(features).all():
+                raise ValueError("edge features contain non-finite samples")
+        if self.sample_kind not in {"frame", "interval"}:
+            raise ValueError("sample_kind must be 'frame' or 'interval'")
+        if self.sample_kind == "frame" and np.any(starts != ends):
+            raise ValueError("frame samples must have equal start and end frames")
+        if not str(self.source_contract).strip():
+            raise ValueError("source_contract must be non-empty")
+        if self.subject is not None and not str(self.subject).strip():
+            raise ValueError("subject cannot be empty")
+        if self.session is not None and not str(self.session).strip():
+            raise ValueError("session cannot be empty")
+        if self.tr is not None and (not np.isfinite(self.tr) or self.tr <= 0):
+            raise ValueError("tr must be finite and positive")
+        if self.acquisition_id is not None and not str(self.acquisition_id).strip():
+            raise ValueError("acquisition_id cannot be empty")
+        object.__setattr__(self, "features", None if features is None else _readonly(features))
+        object.__setattr__(self, "rss", _readonly(rss))
+        object.__setattr__(self, "sample_start_frames", _readonly(starts))
+        object.__setattr__(self, "sample_end_frames", _readonly(ends))
+        object.__setattr__(self, "segment_ids", _readonly(segments))
+        object.__setattr__(self, "edge_i", _readonly(left))
+        object.__setattr__(self, "edge_j", _readonly(right))
+        object.__setattr__(self, "roi_names", names)
+        object.__setattr__(self, "subject", None if self.subject is None else str(self.subject))
+        object.__setattr__(self, "session", None if self.session is None else str(self.session))
+        object.__setattr__(self, "source_contract", str(self.source_contract))
+        object.__setattr__(self, "acquisition_id", None if self.acquisition_id is None else str(self.acquisition_id))
+
+    @property
+    def n_samples(self) -> int:
+        return len(self.rss)
+
+    @property
+    def n_edges(self) -> int:
+        return len(self.edge_i)
+
+    @property
+    def n_rois(self) -> int:
+        return len(self.roi_names)
+
+    @property
+    def feature_keys(self) -> tuple[tuple[str, str], ...]:
+        return tuple(
+            (self.roi_names[int(left)], self.roi_names[int(right)])
+            for left, right in zip(self.edge_i, self.edge_j, strict=True)
+        )
+
+    def require_features(self) -> NDArray[np.float64]:
+        if self.features is None:
+            raise ValueError("this result contains RSS only and no materialized edge features")
+        return self.features
+
+    def cross_block(self, left: Sequence[int], right: Sequence[int]) -> NDArray[np.float64]:
+        from ._edge_products import cross_block_edge_summary
+
+        return cross_block_edge_summary(self, left, right)
+
+    def within_block(self, nodes: Sequence[int]) -> NDArray[np.float64]:
+        from ._edge_products import within_block_edge_summary
+
+        return within_block_edge_summary(self, nodes)
+
+
+def _result_from_rows(rows: _InstantaneousRows, *, materialize_edges: bool) -> InstantaneousEdgeResult:
+    from ._edge_products import edge_products, edge_rss
+    from .correlation import edge_index
+
+    left, right = edge_index(len(rows.roi_names))
+    return InstantaneousEdgeResult(
+        features=edge_products(rows.values) if materialize_edges else None,
+        rss=edge_rss(rows.values),
+        sample_start_frames=rows.starts,
+        sample_end_frames=rows.ends,
+        segment_ids=rows.segments,
+        edge_i=left,
+        edge_j=right,
+        roi_names=rows.roi_names,
+        subject=rows.subject,
+        session=rows.session,
+        sample_kind=rows.sample_kind,
+        source_contract=rows.contract,
+        tr=rows.tr,
+        acquisition_id=rows.acquisition_id,
+    )
+
+
+__all__ = ["ETS", "MTD", "InstantaneousEdgeResult"]

dfckit/connectivity/leida.py

@@ -0,0 +1,204 @@
+"""Censor-aware Leading Eigenvector Dynamics Analysis (LEiDA)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .._arrays import readonly_copy as _readonly
+from .._validation import validated_roi_indices
+from ..data import TimeSeriesRun
+
+
+def _validated_phase(values: ArrayLike) -> NDArray[np.float64]:
+    phase = np.asarray(values, dtype=float)
+    if phase.ndim != 2 or not len(phase) or phase.shape[1] < 2:
+        raise ValueError("phase must be a non-empty frames-by-ROI array with at least two ROIs")
+    if not np.isfinite(phase).all():
+        raise ValueError("phase contains non-finite values")
+    return phase
+
+
+@dataclass(frozen=True)
+class LEiDAResult:
+    """Instantaneous phase and leading phase-coherence geometry for one run."""
+
+    phase: NDArray[np.float64]
+    leading_vectors: NDArray[np.float64]
+    leading_eigenvalues: NDArray[np.float64]
+    original_indices: NDArray[np.int64]
+    segment_ids: NDArray[np.int64]
+    roi_names: tuple[str, ...]
+    subject: str | None
+    session: str | None
+    tr: float | None
+    minimum_segment_length: int
+    orientation: str
+    implementation: str
+    acquisition_id: str | None = None
+
+
+def analytic_phase(values: ArrayLike) -> NDArray[np.float64]:
+    """Return Hilbert phase after centering each ROI over one segment."""
+    data = np.asarray(values, dtype=float)
+    if data.ndim != 2 or data.shape[0] < 3 or data.shape[1] < 2:
+        raise ValueError("values must have at least three frames and two ROIs")
+    if not np.isfinite(data).all():
+        raise ValueError("values contain non-finite samples")
+    scale = data.std(axis=0, ddof=0)
+    invalid = np.flatnonzero((~np.isfinite(scale)) | (scale <= 1e-12))
+    if len(invalid):
+        raise ValueError(f"Hilbert phase is undefined for constant ROI indices {invalid.tolist()}")
+    try:
+        from scipy.signal import hilbert
+    except ModuleNotFoundError as error:
+        raise ModuleNotFoundError(
+            "LEiDA phase extraction requires the 'phase' extra: "
+            "pip install 'dfc-kit[phase]'"
+        ) from error
+    centered = data - data.mean(axis=0)
+    return _readonly(np.angle(hilbert(centered, axis=0)))
+
+
+def leading_phase_eigenvectors(
+    phase: ArrayLike,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Return oriented leading eigenvectors of instantaneous phase coherence.
+
+    The matrix with entries ``cos(phase_i - phase_j)`` has rank at most two.
+    Solving its equivalent two-dimensional eigensystem avoids materializing a
+    frames-by-ROI-by-ROI tensor.
+    """
+    angles = _validated_phase(phase)
+    cosine = np.cos(angles)
+    sine = np.sin(angles)
+    cosine_energy = np.sum(cosine**2, axis=1)
+    sine_energy = np.sum(sine**2, axis=1)
+    cross = np.sum(cosine * sine, axis=1)
+    direction = 0.5 * np.arctan2(
+        2.0 * cross,
+        cosine_energy - sine_energy,
+    )
+    vectors = (
+        cosine * np.cos(direction)[:, None]
+        + sine * np.sin(direction)[:, None]
+    )
+    norm = np.linalg.norm(vectors, axis=1)
+    if np.any(~np.isfinite(norm)) or np.any(norm <= 1e-12):
+        raise ValueError("leading phase eigenvector has undefined norm")
+    vectors /= norm[:, None]
+    vectors *= np.where(vectors.sum(axis=1, keepdims=True) < 0.0, -1.0, 1.0)
+
+    discriminant = np.sqrt(
+        (cosine_energy - sine_energy) ** 2 + 4.0 * cross**2
+    )
+    eigenvalues = (cosine_energy + sine_energy + discriminant) / 2.0
+    return _readonly(vectors), _readonly(eigenvalues)
+
+
+def cross_block_phase_coherence(
+    phase: ArrayLike,
+    left: Iterable[int],
+    right: Iterable[int],
+) -> NDArray[np.float64]:
+    """Return mean instantaneous phase coherence between two disjoint blocks."""
+    angles = _validated_phase(phase)
+    left_nodes = validated_roi_indices(
+        left,
+        n_rois=angles.shape[1],
+        label="left block",
+        minimum=1,
+    )
+    right_nodes = validated_roi_indices(
+        right,
+        n_rois=angles.shape[1],
+        label="right block",
+        minimum=1,
+    )
+    overlap = sorted(set(left_nodes.tolist()).intersection(right_nodes.tolist()))
+    if overlap:
+        raise ValueError(f"cross-block phase coherence requires disjoint blocks; overlap={overlap}")
+    values = np.cos(
+        angles[:, left_nodes, None] - angles[:, None, right_nodes]
+    ).mean(axis=(1, 2))
+    return _readonly(values)
+
+
+def within_block_phase_coherence(
+    phase: ArrayLike,
+    nodes: Iterable[int],
+) -> NDArray[np.float64]:
+    """Return off-diagonal mean instantaneous phase coherence within a block."""
+    angles = _validated_phase(phase)
+    selected = validated_roi_indices(
+        nodes,
+        n_rois=angles.shape[1],
+        label="within block",
+        minimum=2,
+    )
+    left, right = np.triu_indices(len(selected), k=1)
+    values = np.cos(
+        angles[:, selected[left]] - angles[:, selected[right]]
+    ).mean(axis=1)
+    return _readonly(values)
+
+
+class LEiDA:
+    """Extract leading phase-coherence vectors inside retained segments."""
+
+    def __init__(self, minimum_segment_length: int = 20) -> None:
+        if isinstance(minimum_segment_length, (bool, np.bool_)) or not isinstance(
+            minimum_segment_length, (int, np.integer)
+        ):
+            raise TypeError("minimum_segment_length must be an integer")
+        if minimum_segment_length < 3:
+            raise ValueError("minimum_segment_length must be at least three")
+        self.minimum_segment_length = int(minimum_segment_length)
+
+    def transform(self, run: TimeSeriesRun) -> LEiDAResult:
+        phases: list[NDArray[np.float64]] = []
+        vectors: list[NDArray[np.float64]] = []
+        eigenvalues: list[NDArray[np.float64]] = []
+        original_indices: list[NDArray[np.int64]] = []
+        segment_ids: list[NDArray[np.int64]] = []
+
+        for segment_id, positions in enumerate(run.segments()):
+            if len(positions) < self.minimum_segment_length:
+                continue
+            segment_phase = analytic_phase(run.values[positions])
+            segment_vectors, segment_eigenvalues = leading_phase_eigenvectors(segment_phase)
+            phases.append(segment_phase)
+            vectors.append(segment_vectors)
+            eigenvalues.append(segment_eigenvalues)
+            original_indices.append(run.original_indices[positions])
+            segment_ids.append(np.full(len(positions), segment_id, dtype=np.int64))
+
+        if not phases:
+            raise ValueError(
+                "no retained segment meets the requested minimum_segment_length"
+            )
+        try:
+            import scipy
+        except ModuleNotFoundError as error:  # pragma: no cover - analytic_phase fails first
+            raise ModuleNotFoundError(
+                "LEiDA phase extraction requires the 'phase' extra: "
+                "pip install 'dfc-kit[phase]'"
+            ) from error
+        return LEiDAResult(
+            phase=_readonly(np.concatenate(phases, axis=0)),
+            leading_vectors=_readonly(np.concatenate(vectors, axis=0)),
+            leading_eigenvalues=_readonly(np.concatenate(eigenvalues)),
+            original_indices=_readonly(np.concatenate(original_indices)),
+            segment_ids=_readonly(np.concatenate(segment_ids)),
+            roi_names=run.roi_names,
+            subject=run.subject,
+            session=run.session,
+            acquisition_id=run.acquisition_id,
+            tr=run.tr,
+            minimum_segment_length=self.minimum_segment_length,
+            orientation="positive-vector-sum",
+            implementation=f"scipy {scipy.__version__} signal.hilbert",
+        )