dfc-kit 1.0.2__tar.gz → 1.0.3__tar.gz

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.0.3 - 2026-10-08
+
+- CAP now defaults to within-run ROI z-scoring and full-data Lloyd KMeans;
+  previously the defaults were within-segment z-scoring and MiniBatchKMeans.
+  Isolated retained frames contribute when their run has at least two frames.
+- Added `cap_state_maps` to average standardized ROI activity by assigned state.
+  To retain earlier CAP behavior, choose `standardization="segment"` and
+  `algorithm="minibatch"`; for stores, use
+  `--cap-standardization segment` and a materialized MiniBatch fit.
+- Clarified that result storage is explicit and computations are not automatically
+  cached across calls. Memory-mapped reads can be disabled with `mmap=False`;
+  this changes file loading, not computation reuse or operating-system caching.
+
 ## 1.0.2 - 2026-09-11
 
 - Added exact-feature selection for in-memory and disk-backed state models,

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/CITATION.cff

@@ -4,6 +4,6 @@ title: "dfc-kit: Censor-aware dynamic functional connectivity tools"
 type: software
 authors:
   - name: "dfc-kit contributors"
-version: 1.0.2
-date-released: 2026-09-11
+version: 1.0.3
+date-released: 2026-10-08
 license: BSD-3-Clause

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfc-kit
-Version: 1.0.2
+Version: 1.0.3
 Summary: Censor-aware tools for dynamic functional connectivity analysis
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/yidao9518/dfc-kit

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/docs/api.md

@@ -11,9 +11,10 @@ from dfckit.io import load_xcpd_run, discover_xcpd_runs
 ```
 
 `TimeSeriesRun` carries ROI time series, original frame indices, and acquisition
-metadata. XCP-D loaders preserve censor gaps. ETS and CAP perform their required
-within-segment standardization internally; the shared standardization helper is
-an implementation detail rather than a public preprocessing API.
+metadata. XCP-D loaders preserve censor gaps. ETS standardizes within each
+retained segment. CAP standardizes within each run by default, with segment-wise
+scaling available as an option. Both retain segment boundaries for temporal
+summaries.
 
 ## Connectivity
 

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/docs/cli.md

@@ -6,6 +6,11 @@ whole-edge window-pattern and low-rank covariance endpoints, information
 estimates, state fitting,
 decoding, scoring, alignment, repeated-fit stability, and paired inference.
 
+Commands do not automatically reuse previous computation results. Store and
+model inputs are loaded only when explicitly supplied; output paths name saved
+results, not cache directories. `build-store` and `fit-states` require new output
+paths and fail if those paths already exist.
+
 ## Inspect and build a FeatureStore
 
 ```bash
@@ -24,6 +29,24 @@ dfc-kit build-store /path/to/xcpd /path/to/features.store \
 All temporal methods preserve original frame indices and never cross a censor
 gap. `--method` accepts `window-fc`, `cap`, `ets`, `mtd`, or `leida`.
 
+For CAP, build a store of instantaneous ROI patterns and fit materialized Lloyd
+KMeans without a second pooled standardization:
+
+```bash
+dfc-kit build-store /path/to/xcpd /path/to/cap.store \
+  --atlas Schaefer200 --space MNI152NLin2009cAsym \
+  --method cap --cap-standardization run
+dfc-kit fit-states /path/to/cap.store /path/to/models/cap-k5.model \
+  --method kmeans --n-states 5 --seed 20260818 \
+  --n-init 20 --max-iter 300 \
+  --fitting-mode materialized --algorithm lloyd --no-standardize-features
+```
+
+`--cap-standardization` defaults to `run`: each ROI is standardized over all
+retained frames of a run, while censor-bounded sequence boundaries remain.
+Choose `segment` for the earlier per-segment scaling. The default `fit-states`
+streaming path is MiniBatchKMeans, not the in-memory CAP Lloyd default.
+
 ## Fit, decode, and score states
 
 ```bash

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/docs/state_alignment.md

@@ -47,7 +47,8 @@ future predictions from the returned model already use reference numbering.
 CAP fits use the same `KMeansStateModel` contract but expose a domain-specific
 alignment entry point. Use `align_cap_centroids` for CAP models. It defaults to Pearson matching because
 CAP centres describe relative spatial co-activation configurations after
-within-segment ROI standardization:
+ROI standardization. This matching step is separate from the Euclidean distance
+used to fit the clusters:
 
 ```python
 cap_alignment = align_cap_centroids(reference_cap.model, candidate_cap.model)

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/docs/states.md

@@ -186,39 +186,63 @@ materialized Lloyd KMeans; incompatible engines are rejected explicitly.
 ## CAP
 
 ```python
-from dfckit.states import fit_cap_states
+from dfckit.states import (
+    cap_sequences,
+    cap_state_maps,
+    fit_cap_states,
+    predict_kmeans_states,
+    summarize_state_assignments,
+)
 
+features = cap_sequences(training_dataset)
 fit = fit_cap_states(training_dataset, n_states=5, seed=20260818)
+maps = cap_state_maps(features, fit.assignments)
+metrics = summarize_state_assignments(fit.assignments)
+
+unseen_features = cap_sequences(unseen_dataset)
+unseen_assignments = predict_kmeans_states(fit.model, unseen_features)
 ```
 
-CAP input consists of instantaneous ROI patterns. Each uninterrupted retained
-segment is centered and scaled ROI by ROI before fitting. The CAP wrapper uses
-MiniBatchKMeans and does not apply a second pooled feature standardization.
-CAP centroids are co-activation patterns, not connectivity matrices.
+CAP uses every retained instantaneous ROI pattern. By default, each ROI is
+centered and scaled over all retained frames of its run (`ddof=0`), with no
+second scaling across participants. Runs need at least two retained frames;
+isolated retained frames still contribute after run-wise scaling. Censor gaps
+remain sequence boundaries for dwell and transition metrics. `fit_cap_states`
+returns a `KMeansFitResult` and defaults to full-data Euclidean Lloyd KMeans
+without PCA (`n_init=20`, `max_iter=300`). Set `algorithm="minibatch"` for
+MiniBatchKMeans. `standardization="segment"` retains the earlier per-segment
+scaling, which omits segments shorter than two frames.
+
+`maps` is a read-only `(n_states, n_rois)` array: for each state, it averages
+the standardized BOLD patterns of frames assigned that final label, with equal
+weight per frame. A state with no assigned frames has a NaN map. These activity
+maps are not FC matrices and do not change the fitted centers or prediction.
 Use `align_cap_centroids` to align repeated CAP fits. Its default is Pearson
 pattern matching; generic KMeans and HMM alignment continues to default to
 standardized Euclidean distance.
 
 For a disk-backed XCP-D cohort, build the equivalent CAP FeatureStore with
 `dfc-kit build-store --method cap` or `write_cap_store`. The store uses the
-source contract `cap:within-segment-roi-zscore-ddof0`, one ROI feature per row,
-and one sequence per uninterrupted retained segment. Its rows preserve the
-original frame indices, and segments shorter than two retained frames are
-omitted. To reproduce the in-memory CAP wrapper from that store, use materialized
-MiniBatchKMeans with `--no-standardize-features`:
+source contract `cap:within-run-roi-zscore-ddof0`, one ROI feature per column,
+and one sequence per uninterrupted retained segment. Its rows preserve original
+frame indices. To fit the same geometry as the in-memory default, use
+materialized Lloyd KMeans without pooled feature standardization:
 
 ```bash
 dfc-kit fit-states cap.store models/cap-k5.model \
   --method kmeans --n-states 5 --seed 20260818 \
   --n-init 20 --max-iter 300 \
-  --fitting-mode materialized --algorithm minibatch \
+  --fitting-mode materialized --algorithm lloyd \
   --no-standardize-features
 ```
 
 Materialized fitting loads the selected cohort and calls one complete
-`MiniBatchKMeans.fit`; it is therefore intended for moderate stores and can
-reproduce historical native geometry. The default CLI path is bounded-memory
-streaming `MiniBatchKMeans.partial_fit`, which is a different fitting contract.
+`KMeans.fit`; it is intended for moderate stores. The default CLI fitting path
+uses bounded-memory streaming `MiniBatchKMeans.partial_fit`, so select
+`--fitting-mode materialized --algorithm lloyd` explicitly for this CAP fit.
+
+For background, see the [original full-frame CAP study](https://pmc.ncbi.nlm.nih.gov/articles/PMC3913885/)
+and an [ROI-pattern CAP study](https://pmc.ncbi.nlm.nih.gov/articles/PMC4386757/).
 
 ## LEiDA states
 

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/docs/storage.md

@@ -14,6 +14,15 @@ FeatureStore accepts only the current manifest schema. Every sequence record
 therefore has an explicit acquisition field, which may be `None` when no
 acquisition label is available.
 
+## Storage versus computation caches
+
+dfc-kit does not automatically cache computed results across calls. Numerical
+analysis calls recompute their outputs; disk storage is explicit through store
+writers and artifact save/load functions. Creating a store at an existing path
+raises an error rather than silently reusing its contents. To compute features
+without writing them to disk, use the estimator's in-memory API, such as
+`SlidingWindowFC.transform(run)`, instead of a store writer.
+
 ## Stream sliding-window FC
 
 ```python
@@ -63,9 +72,8 @@ is required; that path avoids edge materialization.
 ## Stream CAP
 
 CAP stores contain instantaneous ROI patterns, not ROI-pair edges. The writer
-standardizes every ROI over the complete uninterrupted retained segment with
-population standard deviation (`ddof=0`) and then writes the resulting rows in
-bounded chunks:
+standardizes every ROI across all retained frames of each run with population
+standard deviation (`ddof=0`) and writes rows in bounded chunks:
 
 ```python
 from dfckit.storage import append_cap, write_cap_store
@@ -80,14 +88,16 @@ store = write_cap_store(
 append_cap(store, another_run, chunk_size=256)
 ```
 
-Each retained segment becomes its own FeatureStore sequence. Segments shorter
-than two retained frames are omitted, because a segment-level standardized CAP
-sequence cannot provide a usable temporal sample. Every stored row retains the
-original frame index in both `sample_start_indices` and `sample_end_indices`,
-and censor gaps therefore cannot be joined during later state metrics. The
-source contract is `cap:within-segment-roi-zscore-ddof0`, and the feature keys
-are the ROI names in their input order. Standardization is performed before
-chunking, so changing `chunk_size` does not change CAP values.
+Runs need at least two retained frames. Each retained censor-bounded segment
+becomes its own FeatureStore sequence, including isolated retained frames.
+Every stored row retains its original frame index in both
+`sample_start_indices` and `sample_end_indices`, so later state metrics do not
+join censor gaps. The source contract is `cap:within-run-roi-zscore-ddof0`,
+and the feature keys are the ROI names in input order. Set
+`standardization="segment"` in `write_cap_store` or `append_cap` to use the
+earlier per-segment scaling and omit segments shorter than two frames; its
+source contract is `cap:within-segment-roi-zscore-ddof0`. Standardization
+precedes chunking, so `chunk_size` does not change CAP values.
 
 ## Stream LEiDA
 
@@ -129,6 +139,11 @@ sequence_part = store.read_sequence(
 append_window_fc(store, another_run, estimator, chunk_size=128)
 ```
 
+`iter_chunks()` uses read-only memory mapping by default. Pass `mmap=False` to
+load each chunk into ordinary NumPy arrays instead. This controls how existing
+files are read, not whether previous computations are reused. Neither mode
+disables the operating system's filesystem cache.
+
 `read_dataset()` reconstructs ordinary `FeatureSequenceDataset` objects for
 existing in-memory state APIs. For genuinely large analyses, iterate chunks or
 read selected sequences instead of reconstructing the full dataset.
@@ -266,7 +281,7 @@ fit = fit_kmeans_store_materialized(
     seed=20260818,
     n_init=20,
     max_iter=300,
-    algorithm="minibatch",
+    algorithm="lloyd",
     standardize_features=False,
 )
 ```
@@ -275,8 +290,8 @@ Materialized fitting loads the selected cohort into memory; it is not an
 out-of-core operation. `algorithm="lloyd"` calls scikit-learn `KMeans.fit`,
 whereas `algorithm="minibatch"` calls `MiniBatchKMeans.fit`. Both retain the
 FeatureStore source contract, feature identities, and selected fit subjects in
-the returned model. CAP rows have already been
-standardized within segment, so CAP reproduction normally uses
+the returned model. CAP rows have already been standardized within run (or
+within segment when requested), so CAP fitting normally uses
 `standardize_features=False`; enabling it adds a second pooled feature
 standardization and changes the fitted geometry.
 
@@ -285,8 +300,8 @@ The two KMeans paths have distinct numerical and memory semantics:
 | Mode | Algorithm | Feature rows in RAM | Estimator operation | Typical use |
 | --- | --- | --- | --- | --- |
 | `streaming` | `minibatch` only | bounded chunks | repeated `partial_fit` passes | large stores |
-| `materialized` | `lloyd` | selected cohort | one `KMeans.fit` call | historical Lloyd fits |
-| `materialized` | `minibatch` | selected cohort | one `MiniBatchKMeans.fit` call | historical CAP/MiniBatch fits |
+| `materialized` | `lloyd` | selected cohort | one `KMeans.fit` call | default in-memory CAP fit |
+| `materialized` | `minibatch` | selected cohort | one `MiniBatchKMeans.fit` call | optional MiniBatch fit |
 
 The streaming path is not a hidden alias for `MiniBatchKMeans.fit`: its
 initialization sample, chunk traversal, and repeated `partial_fit` updates are

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dfc-kit"
-version = "1.0.2"
+version = "1.0.3"
 description = "Censor-aware tools for dynamic functional connectivity analysis"
 readme = "README.md"
 requires-python = ">=3.10"

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfc_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfc-kit
-Version: 1.0.2
+Version: 1.0.3
 Summary: Censor-aware tools for dynamic functional connectivity analysis
 License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/yidao9518/dfc-kit

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfc_kit.egg-info/SOURCES.txt

@@ -132,6 +132,7 @@ tests/regression/test_nbs_independent_reference.py
 tests/regression/test_nbs_reference.py
 tests/unit/__init__.py
 tests/unit/test_artifact_helpers.py
+tests/unit/test_cap.py
 tests/unit/test_cli.py
 tests/unit/test_correlation.py
 tests/unit/test_cross_validation.py

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/__init__.py

@@ -8,4 +8,4 @@ __all__ = [
     "TimeWindow",
     "validate_subject_disjoint",
 ]
-__version__ = "1.0.2"
+__version__ = "1.0.3"

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/_preprocessing.py

@@ -9,6 +9,39 @@ from ._arrays import readonly_copy as _readonly
 from .data import TimeSeriesRun
 
 
+def _roi_zscore(values: NDArray[np.float64]) -> NDArray[np.float64]:
+    scale = values.std(axis=0, ddof=0)
+    scale = np.where(scale < 1e-8, 1.0, scale)
+    return (values - values.mean(axis=0)) / scale
+
+
+def _standardized_samples(
+    run: TimeSeriesRun,
+    *,
+    standardization: str = "run",
+    method_name: str = "CAP",
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Standardize retained ROI samples while preserving censor boundaries.
+
+    Run scaling uses all retained frames together, including isolated frames.
+    Segment scaling omits segments shorter than two frames.
+    """
+    if standardization == "segment":
+        return _segment_standardized_samples(run, method_name=method_name)
+    if standardization != "run":
+        raise ValueError("standardization must be 'run' or 'segment'")
+    if run.n_frames < 2:
+        raise ValueError(f"{method_name} requires at least two retained frames per run")
+    values = _roi_zscore(run.values)
+    if not np.isfinite(values).all():
+        raise ValueError(f"standardized {method_name} samples contain non-finite values")
+    segment_ids = np.concatenate([
+        np.full(len(positions), segment_id, dtype=np.int64)
+        for segment_id, positions in enumerate(run.segments())
+    ])
+    return _readonly(values), _readonly(run.original_indices), _readonly(segment_ids)
+
+
 def _segment_standardized_samples(
     run: TimeSeriesRun,
     *,
@@ -28,9 +61,7 @@ def _segment_standardized_samples(
         if len(positions) < 2:
             continue
         values = run.values[positions]
-        scale = values.std(axis=0, ddof=0)
-        scale = np.where(scale < 1e-8, 1.0, scale)
-        samples.append((values - values.mean(axis=0)) / scale)
+        samples.append(_roi_zscore(values))
         original_indices.append(run.original_indices[positions])
         segment_ids.append(np.full(len(positions), segment_id, dtype=np.int64))
 

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/commands/parser.py

@@ -71,6 +71,10 @@ def build_parser() -> argparse.ArgumentParser:
     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)
+    build.add_argument(
+        "--cap-standardization", choices=("run", "segment"), default="run",
+        help="CAP ROI z-score scope; run uses all retained frames per acquisition",
+    )
 
     information = subparsers.add_parser(
         "fixed-information",

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/commands/source.py

@@ -164,6 +164,7 @@ def build_store(namespace: argparse.Namespace) -> dict[str, object]:
         store = write_cap_store(
             namespace.output,
             dataset.runs,
+            standardization=namespace.cap_standardization,
             chunk_size=namespace.chunk_size,
             dtype=namespace.dtype,
         )

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/states/__init__.py

@@ -11,7 +11,7 @@ from .alignment import (
     relabel_gaussian_hmm_model,
     relabel_kmeans_model,
 )
-from .cap import cap_sequences, fit_cap_states
+from .cap import cap_sequences, cap_state_maps, fit_cap_states
 from .cross_validation import SubjectValidationFold, make_subject_validation_folds
 from .data import (
     FeatureSequence,
@@ -77,6 +77,7 @@ __all__ = [
     "apply_gaussian_hmm_alignment",
     "apply_state_alignment",
     "cap_sequences",
+    "cap_state_maps",
     "compare_state_model_scores",
     "fit_cap_states",
     "fit_gaussian_hmm_states",

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/states/alignment.py

@@ -193,9 +193,8 @@ def align_cap_centroids(
 ) -> StateAlignment:
     """Align CAP state centres, using pattern-shape matching by default.
 
-    CAP centres are relative ROI activation configurations because each input
-    segment is ROI-wise z-scored. Pearson matching therefore compares the
-    spatial configuration without treating a proportional amplitude change as
+    CAP centres describe ROI-wise standardized activity. Pearson matching
+    compares the spatial configuration without treating a proportional amplitude change as
     a different CAP state. Pass ``metric="euclidean"`` when amplitude should
     also contribute to the CAP pairing.
     """

dfc_kit-1.0.3/src/dfckit/states/cap.py

@@ -0,0 +1,124 @@
+"""Co-activation pattern feature construction and KMeans fitting."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .._arrays import readonly_copy
+from .._preprocessing import _standardized_samples
+from ..data import TimeSeriesDataset
+from .data import (
+    FeatureSequence,
+    FeatureSequenceDataset,
+    StateAssignments,
+    _segment_feature_sequences,
+)
+from .kmeans import KMeansFitResult, fit_kmeans_states
+
+
+def cap_sequences(
+    dataset: TimeSeriesDataset,
+    *,
+    standardization: str = "run",
+) -> FeatureSequenceDataset:
+    """Create instantaneous ROI patterns from all retained frames.
+
+    Each run is ROI-wise z-scored over its retained frames by default (ddof=0).
+    ``standardization='segment'`` instead scales each contiguous segment and
+    omits singleton segments. Both modes keep censor gaps as sequence boundaries.
+    """
+    dataset.require_subject_ids("CAP state modeling")
+    feature_keys = tuple((roi,) for roi in dataset.roi_names)
+    sequences: list[FeatureSequence] = []
+    for run in dataset.runs:
+        assert run.subject is not None
+        standardized, original_indices, segment_ids = _standardized_samples(
+            run, standardization=standardization, method_name="CAP"
+        )
+        sequences.extend(
+            _segment_feature_sequences(
+                run, standardized, original_indices, original_indices, segment_ids,
+                feature_keys=feature_keys,
+                source_contract=f"cap:within-{standardization}-roi-zscore-ddof0",
+                interval=run.tr,
+            )
+        )
+    return FeatureSequenceDataset(sequences)
+
+
+def fit_cap_states(
+    dataset: TimeSeriesDataset,
+    *,
+    n_states: int,
+    seed: int,
+    n_init: int = 20,
+    max_iter: int = 300,
+    standardization: str = "run",
+    algorithm: str = "lloyd",
+    batch_size: int = 4096,
+    reassignment_ratio: float = 0.01,
+) -> KMeansFitResult:
+    """Fit Euclidean KMeans to standardized instantaneous ROI patterns.
+
+    The default uses full-batch Lloyd KMeans, with no PCA or second feature
+    standardization. ``algorithm='minibatch'`` enables approximate fitting.
+    Use :func:`cap_state_maps` for exact frame-average activity maps under the
+    final assignments, rather than assuming estimated centers equal those maps.
+    """
+    return fit_kmeans_states(
+        cap_sequences(dataset, standardization=standardization),
+        n_states=n_states,
+        seed=seed,
+        n_init=n_init,
+        max_iter=max_iter,
+        algorithm=algorithm,
+        standardize_features=False,
+        batch_size=batch_size,
+        reassignment_ratio=reassignment_ratio,
+    )
+
+
+def cap_state_maps(
+    features: FeatureSequenceDataset,
+    assignments: StateAssignments,
+) -> NDArray[np.float64]:
+    """Average standardized ROI activity over the frames assigned to each CAP.
+
+    Returns a read-only states-by-ROIs array in ``features.feature_keys`` order.
+    Frames have equal weight; states with no assigned frames have NaN rows.
+    Sequences may be reordered, but acquisition identities and frame indices
+    must match. These descriptive maps do not change the fitted model centers.
+    """
+    if not features.source_contract.startswith("cap:") or any(
+        len(key) != 1 for key in features.feature_keys
+    ):
+        raise ValueError("CAP maps require CAP ROI features from cap_sequences or a CAP store")
+    if features.source_contract != assignments.source_contract:
+        raise ValueError("CAP maps require matching standardization source contracts")
+    left, right = features.sample_interval_seconds, assignments.sample_interval_seconds
+    if (left is None) != (right is None) or (
+        left is not None and right is not None and not np.isclose(left, right, rtol=0, atol=1e-9)
+    ):
+        raise ValueError("CAP maps require matching sample intervals")
+
+    def identity(sequence):
+        return sequence.subject, sequence.session, sequence.acquisition_id, sequence.segment_id
+
+    labels_by_sequence = {identity(sequence): sequence for sequence in assignments.sequences}
+    if {identity(sequence) for sequence in features.sequences} != set(labels_by_sequence):
+        raise ValueError("CAP maps require matching sequence identities")
+    sums = np.zeros((assignments.n_states, len(features.feature_keys)), dtype=float)
+    counts = np.zeros(assignments.n_states, dtype=np.int64)
+    for sequence in features.sequences:
+        assigned = labels_by_sequence[identity(sequence)]
+        if not (
+            np.array_equal(sequence.sample_start_indices, assigned.sample_start_indices)
+            and np.array_equal(sequence.sample_end_indices, assigned.sample_end_indices)
+        ):
+            raise ValueError("CAP maps require matching frame indices")
+        np.add.at(sums, assigned.labels, sequence.values)
+        counts += np.bincount(assigned.labels, minlength=assignments.n_states)
+    maps = np.full(sums.shape, np.nan)
+    np.divide(sums, counts[:, None], out=maps, where=counts[:, None] > 0)
+    return readonly_copy(maps)

{dfc_kit-1.0.2 → dfc_kit-1.0.3}/src/dfckit/storage/builders.py

@@ -8,7 +8,7 @@ from pathlib import Path
 import numpy as np
 from numpy.typing import NDArray
 
-from .._preprocessing import _segment_standardized_samples
+from .._preprocessing import _standardized_samples
 from ..connectivity._edge_products import edge_products
 from ..connectivity.correlation import edge_index, weighted_correlation
 from ..connectivity.instantaneous import _InstantaneousEstimator, _InstantaneousRows
@@ -211,20 +211,23 @@ def append_cap(
     store: FeatureStore,
     run: TimeSeriesRun,
     *,
+    standardization: str = "run",
     chunk_size: int = 128,
 ) -> None:
-    """Append segment-standardized instantaneous ROI patterns in bounded chunks."""
+    """Append run- or segment-standardized ROI patterns in bounded chunks."""
     if run.subject is None:
         raise ValueError("stored CAP requires a subject identifier")
     size = _validated_chunk_size(chunk_size)
     keys = _roi_feature_keys(run.roi_names)
-    contract = "cap:within-segment-roi-zscore-ddof0"
+    contract = f"cap:within-{standardization}-roi-zscore-ddof0"
     store.require_contract(
         feature_keys=keys,
         source_contract=contract,
         sample_interval_seconds=run.tr,
     )
-    standardized, original, segment_ids = _segment_standardized_samples(run, method_name="CAP")
+    standardized, original, segment_ids = _standardized_samples(
+        run, standardization=standardization, method_name="CAP"
+    )
     _append_segment_rows(
         store, run, standardized, original, original, segment_ids, chunk_size=size,
     )
@@ -234,21 +237,24 @@ def write_cap_store(
     root: str | Path,
     runs: Sequence[TimeSeriesRun],
     *,
+    standardization: str = "run",
     chunk_size: int = 128,
     dtype: str | np.dtype = "float64",
 ) -> FeatureStore:
-    """Create a store of segment-standardized instantaneous ROI patterns."""
+    """Store CAP patterns, using run-wise ROI z-scores by default."""
+    if standardization not in {"run", "segment"}:
+        raise ValueError("standardization must be 'run' or 'segment'")
     dataset = TimeSeriesDataset(runs)
     dataset.require_subject_ids("stored CAP")
     store = FeatureStore.create(
         root,
         feature_keys=_roi_feature_keys(dataset.roi_names),
-        source_contract="cap:within-segment-roi-zscore-ddof0",
+        source_contract=f"cap:within-{standardization}-roi-zscore-ddof0",
         sample_interval_seconds=dataset.tr,
         dtype=dtype,
     )
     for run in dataset.runs:
-        append_cap(store, run, chunk_size=chunk_size)
+        append_cap(store, run, standardization=standardization, chunk_size=chunk_size)
     return store