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

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

@@ -1,6 +1,18 @@
 # Changelog
 
-## 1.0.1 (unreleased)
+## 1.0.2 - 2026-09-11
+
+- Added exact-feature selection for in-memory and disk-backed state models,
+  including clustering on a fixed NBS component's edges.
+- Added conditional Granger predictability with censor-bounded lagged samples
+  and VAR diagnostics. SciPy is loaded only when those diagnostics are used,
+  preserving the NumPy-only base installation.
+- FeatureStore summaries can now aggregate a named feature set within each
+  sample before computing acquisition-level mean, variance, standard deviation,
+  and extrema. The CLI exposes `--feature-keys` and `--feature-mean NAME` for
+  fixed-network summaries, including sparse NBS components.
+
+## 1.0.1
 
 - Fixed-length MI/CMI now shares one process pool across acquisition, window
   length, and draw combinations. Bounded task submission avoids materializing

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/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.1
-date-released: 2026-09-05
+version: 1.0.2
+date-released: 2026-09-11
 license: BSD-3-Clause

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/MANIFEST.in

@@ -1,11 +1,8 @@
 include CHANGELOG.md
 include CITATION.cff
 include CONTRIBUTING.md
-include ENGINEERING_PLAN.md
 include LICENSE
 include README.md
-include ROADMAP.md
-include SECURITY.md
 include mkdocs.yml
 recursive-include benchmarks *.md *.py
 recursive-include docs *.md

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfc-kit
-Version: 1.0.1
+Version: 1.0.2
 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.1 → dfc_kit-1.0.2}/docs/api.md

@@ -60,10 +60,17 @@ store = FeatureStore.create(
     sample_interval_seconds=result.sample_interval_seconds,
 )
 store.append_dataset(dataset)
+
+# Select exact edges without duplicating the disk-backed store.
+selected = store.select_features(
+    feature_keys=(("V1_L", "PUT-DP_L"), ("V1_R", "PUT-DP_R"))
+)
 ```
 
 FeatureStore chunks are memory-mappable and retain sequence/acquisition
-boundaries. They are an execution format, not a provenance database.
+boundaries. A selected feature view preserves those boundaries and is accepted
+by the store-based state fitters. FeatureStore objects are an execution format,
+not a provenance database.
 
 ## State models
 

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

@@ -32,6 +32,13 @@ dfc-kit fit-states /path/to/features.store /path/to/models/k4.model \
   --max-iter 100 --streaming-tol 1e-4 \
   --streaming-patience 3 --streaming-min-passes 2
 
+# Exact ordered edge subset with equal participant-session influence.
+dfc-kit fit-states /path/to/features.store /path/to/models/k2.model \
+  --method kmeans --n-states 2 --seed 20260907 \
+  --feature-keys /path/to/edges.json \
+  --fitting-mode materialized --algorithm lloyd \
+  --sample-weight-mode subject_session_balanced
+
 dfc-kit predict-states /path/to/features.store /path/to/models/k4.model \
   /path/to/results/k4.labels --subject sub-010
 
@@ -177,6 +184,24 @@ and `maximum`. Variance and standard deviation use all retained samples with
 `ddof=0`. Censor-delimited segments remain distinct during feature generation,
 then their valid samples are combined by sample count within the acquisition.
 
+To summarize a fixed NBS component, supply its exact ROI-pair keys as a JSON
+array (for example, `[["V1_L", "PUT-DP_L"], ["V1_R", "PUT-DP_R"]]`):
+
+```bash
+dfc-kit summarize-store features/window-fc.store results/nbs24-summary.json \
+  --feature-keys nbs24-edges.json --feature-mean NBS24 \
+  --statistic mean --statistic standard_deviation
+```
+
+`--feature-keys` selects columns. `--feature-mean NAME` averages those columns
+equally within each sample, then summarizes the resulting network time series
+under `NAME.mean`, `NAME.standard_deviation`, and any other requested statistics.
+With no key file, the mean uses all store features; with no `--feature-mean`,
+selected features are summarized separately. Signed values and source units
+are preserved. Network standard deviation is computed **after** averaging
+edges, not by averaging their individual standard deviations. The resulting
+endpoint file can be used with `infer-paired-endpoints`.
+
 Use `summarize-states`, `summarize-information`, `describe-states`,
 `infer-state-metrics`, `infer-paired-endpoints`, and `infer-paired-nbs` for
 reporting and inference. Every command writes finite JSON and refuses

dfc_kit-1.0.2/docs/granger.md

@@ -0,0 +1,35 @@
+# Conditional Granger predictability
+
+Install the inference dependency before running this analysis:
+
+```bash
+python -m pip install 'dfc-kit[inference]'
+```
+
+`conditional_granger()` fits pooled linear VAR models while constructing every
+lagged row inside one contiguous retained-frame segment. Its Geweke statistic is
+the log ratio of restricted to unrestricted target-residual variance (or
+generalized variance for a multivariate target). The restricted model removes
+source lags and retains target and conditioning lags.
+
+```python
+from dfckit.connectivity import conditional_granger
+
+result = conditional_granger(
+    run,
+    source=[0],
+    target=[1],
+    conditioning=[2, 3],
+    lag_order=2,
+)
+print(result.geweke, result.spectral_radius, result.whiteness.min_ljung_box_p)
+```
+
+The result reports residual degrees of freedom, VAR spectral radius, and a
+Ljung--Box residual-autocorrelation diagnostic. Segment standardization is
+enabled by default. These estimates describe lagged linear predictability in the
+processed time series and do not by themselves establish neural causality.
+
+References: Geweke (1982), *Journal of the American Statistical Association*,
+doi:10.1080/01621459.1982.10477803; Barnett and Seth (2014), *Journal of
+Neuroscience Methods*, doi:10.1016/j.jneumeth.2013.10.018.

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/docs/nbs.md

@@ -98,6 +98,36 @@ tests reconstruct the OLS statistics with NumPy and the graph components with
 SciPy, and compare observed components and complete null arrays for both sign
 modes and for unadjusted and confound-adjusted analyses.
 
+## Summarize a component's connection strength
+
+NBS reports component size or a sum of edge t statistics; neither is its mean
+FC. To measure a fixed component in every acquisition, take its exact
+`component_edges` from an `infer-paired-nbs` result and select those keys in
+the FC store:
+
+```python
+from dfckit.storage import FeatureStore, summarize_store_statistics
+
+store = FeatureStore.open("features/window-fc.store")
+selected = store.select_features(feature_keys=component_edges)
+network_endpoints = summarize_store_statistics(
+    selected,
+    statistics=("mean", "standard_deviation"),
+    feature_mean="NBS_component",
+)
+```
+
+This averages the selected signed edge values in each window, then computes
+their network mean and temporal variability within each acquisition. Use the
+same fixed edge set in every condition. The stored edge names, not node
+membership alone, define the component: adding all connections between its
+nodes would include edges that NBS did not select. A mean of window FC is also
+distinct from whole-acquisition static FC.
+
+The generic endpoint output supports paired inference. Testing the contrast
+that selected a component on the same participants is a descriptive follow-up,
+not an independent confirmation of the NBS discovery.
+
 ## References
 
 - Zalesky A, Fornito A, Bullmore ET. Network-based statistic: identifying

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

@@ -40,6 +40,16 @@ directly in the original edge-feature space:
 window FC edges -> training-set feature scaling -> KMeans
 ```
 
+The default `sample_weight_mode="uniform"` gives every window equal weight and
+preserves the original fitting behavior. For cohorts with unequal usable scan
+lengths, `sample_weight_mode="subject_session_balanced"` first gives every
+participant equal total weight, then divides that weight equally among the
+participant's sessions and their retained windows. The weighted mean and
+variance are used for feature scaling, and the same weights enter the Lloyd
+KMeans objective. The model records the weight sums and Kish effective row
+count; this diagnostic is not a count of statistically independent samples.
+Balanced weighting currently requires materialized Lloyd KMeans without PCA.
+
 For a lower-dimensional sensitivity path, set `n_pca_components`. PCA is fitted
 only on the training participants, and the frozen scaler and PCA basis are
 applied before KMeans:
@@ -123,6 +133,56 @@ The prediction artifact retains the original sequence identity and sample
 indices. The summary command applies the same gap-safe
 `summarize_state_assignments` implementation used by the Python API.
 
+## Clustering a specified feature or edge set
+
+State fitting uses every input feature by default. Restrict an in-memory
+feature dataset by exact feature identity before fitting:
+
+```python
+selected = training_sequences.select_features(
+    feature_keys=(
+        ("V1_L", "PUT-DP_L"),
+        ("V1_R", "PUT-DP_R"),
+    )
+)
+fit = fit_kmeans_states(selected, n_states=2, seed=20260907)
+```
+
+For a disk-backed store, `select_features` returns a read-only column view. It
+does not rewrite the store and works with materialized or streaming state
+fitting:
+
+```python
+store = FeatureStore.open("/path/to/window_fc.store")
+selected_store = store.select_features(feature_mask=nbs_edge_mask)
+fit = fit_minibatch_kmeans_store(
+    selected_store,
+    n_states=2,
+    seed=20260907,
+)
+```
+
+`feature_keys` are exact identities and determine output order. A Boolean
+`feature_mask` must have one entry per source feature and preserves source
+order. Fitted models record only the selected keys, so prediction must use the
+same selected view.
+
+The command line accepts the same exact ordered selection as a JSON array of
+feature-key arrays:
+
+```bash
+dfc-kit fit-states window-fc.store models/nbs-k2.model \
+  --method kmeans --n-states 2 --feature-keys nbs-edges.json \
+  --fitting-mode materialized --algorithm lloyd \
+  --sample-weight-mode subject_session_balanced
+dfc-kit predict-states window-fc.store models/nbs-k2.model labels \
+  --feature-keys nbs-edges.json --allow-fit-subjects
+```
+
+Participant-session-balanced weighting gives every acquisition sequence equal
+total influence regardless of its number of windows. It is supported only by
+materialized Lloyd KMeans; incompatible engines are rejected explicitly.
+
 ## CAP
 
 ```python

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

@@ -176,6 +176,37 @@ or `feature_12.variance`. For edge FeatureStores, one selected statistic at a
 time can be reshaped into a participants-by-edges matrix for NBS. Mixing two
 statistics in one NBS graph would duplicate every edge and is invalid.
 
+### Mean strength and variability of a fixed network
+
+Select exact edge keys, then name the feature mean to summarize the network
+instead of each edge separately:
+
+```python
+selected = store.select_features(feature_keys=component_edges)
+payload = summarize_store_statistics(
+    selected,
+    statistics=("mean", "standard_deviation"),
+    feature_mean="NBS24",
+)
+```
+
+For each sample, the selected edges are averaged with equal weights. The
+resulting network time series is then summarized separately for each
+participant, session, and acquisition. `NBS24.mean` is its temporal mean;
+`NBS24.standard_deviation` is its population standard deviation, **not** the
+average of the individual edges' standard deviations. Each retained sample
+has equal weight, including when segments or storage chunks differ in length.
+
+Values keep the store's scale and sign: a Fisher-z window-FC store produces
+means of signed Fisher-z values, without taking absolute values or applying
+another transform. These are mean-window FC summaries, not whole-acquisition
+static FC. A store with one static FC row per acquisition instead gives its
+across-edge mean and a zero temporal standard deviation.
+
+The output lists `source_feature_keys` and marks `feature_type="feature_set"`.
+It can enter `infer-paired-endpoints`, but is no longer an edge matrix for
+`infer-paired-nbs`. Omitting `feature_mean` retains per-feature summaries.
+
 ## Stream MiniBatchKMeans
 
 Feature stores can be fitted directly without calling `read_dataset()`:

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/mkdocs.yml

@@ -16,6 +16,7 @@ nav:
       - Architecture: architecture.md
   - Connectivity methods:
       - Correlation and sliding-window FC: correlation.md
+      - Conditional Granger predictability: granger.md
       - Instantaneous edges (ETS and MTD): instantaneous_edges.md
       - LEiDA: leida.md
       - Low-rank covariance: lowrank.md

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfc-kit
-Version: 1.0.1
+Version: 1.0.2
 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.1 → dfc_kit-1.0.2}/src/dfc_kit.egg-info/SOURCES.txt

@@ -1,12 +1,9 @@
 CHANGELOG.md
 CITATION.cff
 CONTRIBUTING.md
-ENGINEERING_PLAN.md
 LICENSE
 MANIFEST.in
 README.md
-ROADMAP.md
-SECURITY.md
 mkdocs.yml
 pyproject.toml
 benchmarks/README.md
@@ -18,6 +15,7 @@ docs/cli.md
 docs/correlation.md
 docs/datasets.md
 docs/getting_started.md
+docs/granger.md
 docs/group_inference.md
 docs/hmm.md
 docs/index.md
@@ -49,6 +47,7 @@ src/dfc_kit.egg-info/requires.txt
 src/dfc_kit.egg-info/top_level.txt
 src/dfckit/__init__.py
 src/dfckit/_arrays.py
+src/dfckit/_feature_selection.py
 src/dfckit/_preprocessing.py
 src/dfckit/_validation.py
 src/dfckit/cli.py
@@ -73,6 +72,7 @@ src/dfckit/commands/states.py
 src/dfckit/connectivity/__init__.py
 src/dfckit/connectivity/_edge_products.py
 src/dfckit/connectivity/correlation.py
+src/dfckit/connectivity/granger.py
 src/dfckit/connectivity/instantaneous.py
 src/dfckit/connectivity/leida.py
 src/dfckit/connectivity/lowrank.py
@@ -138,6 +138,9 @@ tests/unit/test_cross_validation.py
 tests/unit/test_data.py
 tests/unit/test_endpoint_inference.py
 tests/unit/test_ets.py
+tests/unit/test_feature_selection.py
+tests/unit/test_granger.py
+tests/unit/test_granger_optional_dependency.py
 tests/unit/test_hmm.py
 tests/unit/test_independent_endpoint_inference.py
 tests/unit/test_inference.py

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

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

dfc_kit-1.0.2/src/dfckit/_feature_selection.py

@@ -0,0 +1,43 @@
+"""Shared validation for selecting named feature columns."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+FeatureKey = tuple[str, ...]
+
+
+def resolve_feature_selection(
+    available_keys: Sequence[FeatureKey],
+    *,
+    feature_keys: Iterable[Sequence[str]] | None,
+    feature_mask: ArrayLike | None,
+) -> tuple[NDArray[np.int64], tuple[FeatureKey, ...]]:
+    """Resolve one exact-key or Boolean-mask selection against known features."""
+    if (feature_keys is None) == (feature_mask is None):
+        raise ValueError("provide exactly one of feature_keys or feature_mask")
+
+    available = tuple(tuple(str(part) for part in key) for key in available_keys)
+    if feature_keys is not None:
+        requested = tuple(tuple(str(part) for part in key) for key in feature_keys)
+        if not requested or any(not key for key in requested):
+            raise ValueError("feature_keys must select at least one non-empty key")
+        if len(set(requested)) != len(requested):
+            raise ValueError("feature_keys must be unique")
+        positions = {key: index for index, key in enumerate(available)}
+        missing = tuple(key for key in requested if key not in positions)
+        if missing:
+            raise KeyError(f"selected feature keys are absent: {missing}")
+        indices = np.asarray([positions[key] for key in requested], dtype=np.int64)
+        return indices, requested
+
+    mask = np.asarray(feature_mask)
+    if mask.dtype.kind != "b" or mask.shape != (len(available),):
+        raise ValueError(f"feature_mask must be a Boolean vector with shape ({len(available)},)")
+    indices = np.flatnonzero(mask).astype(np.int64, copy=False)
+    if not len(indices):
+        raise ValueError("feature_mask must select at least one feature")
+    return indices, tuple(available[int(index)] for index in indices)

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/src/dfckit/artifacts/models.py

@@ -47,6 +47,10 @@ _KMEANS_METADATA = {
     "n_states",
     "reassignment_ratio",
     "sample_interval_seconds",
+    "sample_weight_effective_row_count",
+    "sample_weight_mode",
+    "sample_weight_sum",
+    "sample_weight_sum_squares",
     "seed",
     "source_contract",
     "standardize_features",
@@ -249,6 +253,10 @@ def _array_payload(model: FittedModel) -> tuple[str, dict[str, object], dict[str
             ),
             "iterations": int(model.iterations),
             "inertia": float(model.inertia),
+            "sample_weight_mode": str(model.sample_weight_mode),
+            "sample_weight_sum": model.sample_weight_sum,
+            "sample_weight_sum_squares": model.sample_weight_sum_squares,
+            "sample_weight_effective_row_count": model.sample_weight_effective_row_count,
         }
         arrays = {name: np.asarray(getattr(model, name)) for name in _KMEANS_ARRAYS}
         return "kmeans-state", metadata, arrays
@@ -425,6 +433,12 @@ def _load_kmeans(
         fit_subjects=_string_tuple(metadata, "fit_subjects"),
         fit_sample_count=fit_sample_count,
         implementation=_string(metadata, "implementation"),
+        sample_weight_mode=_string(metadata, "sample_weight_mode"),
+        sample_weight_sum=_finite_float(metadata, "sample_weight_sum"),
+        sample_weight_sum_squares=_finite_float(metadata, "sample_weight_sum_squares"),
+        sample_weight_effective_row_count=_finite_float(
+            metadata, "sample_weight_effective_row_count"
+        ),
     )
 
 

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

@@ -174,6 +174,11 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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(
+        "--feature-keys",
+        type=Path,
+        help="JSON array of exact ordered feature keys to fit",
+    )
     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)
@@ -228,6 +233,12 @@ def build_parser() -> argparse.ArgumentParser:
     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)
+    fit.add_argument(
+        "--sample-weight-mode",
+        choices=("uniform", "subject_session_balanced"),
+        default="uniform",
+        help="row weighting for materialized Lloyd KMeans",
+    )
 
     predict = subparsers.add_parser(
         "predict-states",
@@ -236,6 +247,11 @@ def build_parser() -> argparse.ArgumentParser:
     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(
+        "--feature-keys",
+        type=Path,
+        help="JSON array of exact ordered feature keys expected by the model",
+    )
     predict.add_argument(
         "--subject",
         action="append",
@@ -256,10 +272,20 @@ def build_parser() -> argparse.ArgumentParser:
 
     summarize_features = subparsers.add_parser(
         "summarize-store",
-        help="write acquisition-level statistics for every named FeatureStore feature",
+        help="write acquisition-level statistics for features or their equal-weight mean",
     )
     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(
+        "--feature-keys",
+        type=Path,
+        help="JSON array of exact feature keys to select, such as an NBS component's edges",
+    )
+    summarize_features.add_argument(
+        "--feature-mean",
+        metavar="NAME",
+        help="average selected features within each sample before summarizing under NAME",
+    )
     summarize_features.add_argument(
         "--statistic",
         action="append",
@@ -282,6 +308,11 @@ def build_parser() -> argparse.ArgumentParser:
     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(
+        "--feature-keys",
+        type=Path,
+        help="JSON array of exact ordered feature keys used to fit the model",
+    )
     describe.add_argument("--top-features", type=int, default=10)
     describe.add_argument(
         "--network-map",
@@ -440,6 +471,11 @@ def build_parser() -> argparse.ArgumentParser:
     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(
+        "--feature-keys",
+        type=Path,
+        help="JSON array of exact ordered feature keys expected by the model",
+    )
     score.add_argument(
         "--subject",
         action="append",

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/src/dfckit/commands/reporting.py

@@ -29,7 +29,9 @@ from ..states.interpretation import (
     write_state_description,
 )
 from ..states.selection import _write_state_count_comparison
-from ..storage.summary import _summarize_store_file, _write_store_summary
+from ..storage import FeatureStore, summarize_store_statistics
+from ..storage.summary import _write_store_summary
+from .states import _load_feature_keys, _selected_feature_store
 
 
 def describe_states(namespace: argparse.Namespace) -> dict[str, object]:
@@ -39,6 +41,7 @@ def describe_states(namespace: argparse.Namespace) -> dict[str, object]:
         namespace.model,
         top_features=namespace.top_features,
         network_map_path=namespace.network_map,
+        feature_keys=_load_feature_keys(namespace.feature_keys),
     )
     output = write_state_description(payload, namespace.output)
     return {
@@ -84,7 +87,8 @@ def infer_state_metrics(namespace: argparse.Namespace) -> dict[str, object]:
 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)
+    store = _selected_feature_store(FeatureStore.open(namespace.store), namespace.feature_keys)
+    payload = summarize_store_statistics(store, statistics, feature_mean=namespace.feature_mean)
     output = _write_store_summary(payload, namespace.output)
     return {
         "output": str(output),

{dfc_kit-1.0.1 → dfc_kit-1.0.2}/src/dfckit/commands/states.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 
 from ..artifacts import (
     StatePredictions,
@@ -31,9 +32,29 @@ from ..states.streaming_hmm import (
 from ..storage import FeatureStore
 
 
+def _load_feature_keys(path):
+    if path is None:
+        return None
+    if not path.is_file() or path.is_symlink():
+        raise ValueError(f"feature-keys file must be an existing non-symlink file: {path}")
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(raw, list) or not raw:
+        raise ValueError("feature-keys JSON must be a non-empty array")
+    if any(not isinstance(key, list) or not key for key in raw):
+        raise ValueError("every feature key must be a non-empty JSON array")
+    return tuple(tuple(str(part) for part in key) for key in raw)
+
+
+def _selected_feature_store(store: FeatureStore, path):
+    keys = _load_feature_keys(path)
+    return store if keys is None else store.select_features(feature_keys=keys)
+
+
 def fit_states(namespace: argparse.Namespace) -> dict[str, object]:
     """Fit one state model from a disk-backed feature store."""
-    store = FeatureStore.open(namespace.store)
+    store = _selected_feature_store(
+        FeatureStore.open(namespace.store), namespace.feature_keys
+    )
     if namespace.output.exists() or namespace.output.is_symlink():
         raise FileExistsError(f"model artifact path already exists: {namespace.output}")
     subjects = None if namespace.subject is None else tuple(namespace.subject)
@@ -43,6 +64,14 @@ def fit_states(namespace: argparse.Namespace) -> dict[str, object]:
             raise ValueError(f"requested fit subjects are absent from the store: {missing}")
 
     if namespace.method == "kmeans":
+        if namespace.sample_weight_mode != "uniform" and (
+            namespace.fitting_mode != "materialized"
+            or namespace.algorithm != "lloyd"
+            or namespace.n_pca_components is not None
+        ):
+            raise ValueError(
+                "subject_session_balanced weights require materialized Lloyd KMeans without PCA"
+            )
         if namespace.fitting_mode == "streaming":
             if namespace.algorithm != "minibatch":
                 raise ValueError("streaming KMeans requires --algorithm minibatch")
@@ -78,6 +107,7 @@ def fit_states(namespace: argparse.Namespace) -> dict[str, object]:
                 reassignment_ratio=namespace.reassignment_ratio,
                 n_pca_components=namespace.n_pca_components,
                 subjects=subjects,
+                sample_weight_mode=namespace.sample_weight_mode,
             )
         model = fit.model
         fit_sequence_count = len(fit.assignments.sequences)
@@ -97,6 +127,7 @@ def fit_states(namespace: argparse.Namespace) -> dict[str, object]:
             "initialization_passes": list(fit.initialization_passes),
             "log_likelihood": None,
             "inertia": model.inertia,
+            "sample_weight_mode": model.sample_weight_mode,
             "init_sample_size": model.init_sample_size,
             "n_pca_components": model.n_pca_components,
             "pca_batch_size": model.pca_batch_size,
@@ -151,7 +182,9 @@ def selected_store_subjects(
 
 def predict_states(namespace: argparse.Namespace) -> dict[str, object]:
     """Decode a feature store with a fitted state model."""
-    store = FeatureStore.open(namespace.store)
+    store = _selected_feature_store(
+        FeatureStore.open(namespace.store), namespace.feature_keys
+    )
     model = load_fitted_model(namespace.model)
     subjects = selected_store_subjects(store, namespace.subject)
     if isinstance(model, KMeansStateModel):
@@ -214,7 +247,9 @@ def score_states(namespace: argparse.Namespace) -> dict[str, object]:
     """Score a fitted state model on selected acquisitions."""
     if namespace.output.exists() or namespace.output.is_symlink():
         raise FileExistsError(f"state-model score output path already exists: {namespace.output}")
-    store = FeatureStore.open(namespace.store)
+    store = _selected_feature_store(
+        FeatureStore.open(namespace.store), namespace.feature_keys
+    )
     model = load_fitted_model(namespace.model)
     subjects = selected_store_subjects(store, namespace.subject)
     if isinstance(model, KMeansStateModel):