dfc-kit 1.0.0__py3-none-any.whl

dfc_kit-1.0.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: dfc-kit
+Version: 1.0.0
+Summary: Censor-aware tools for dynamic functional connectivity analysis
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/yidao9518/dfc-kit
+Project-URL: Repository, https://github.com/yidao9518/dfc-kit
+Project-URL: Issues, https://github.com/yidao9518/dfc-kit/issues
+Keywords: functional connectivity,dynamic functional connectivity,fMRI,neuroimaging,XCP-D
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Provides-Extra: states
+Requires-Dist: scikit-learn>=1.2; extra == "states"
+Provides-Extra: phase
+Requires-Dist: scipy>=1.10; extra == "phase"
+Provides-Extra: inference
+Requires-Dist: scipy>=1.10; extra == "inference"
+Provides-Extra: hmm
+Requires-Dist: hmmlearn>=0.3; extra == "hmm"
+Requires-Dist: scikit-learn>=1.2; extra == "hmm"
+Provides-Extra: information
+Requires-Dist: scipy>=1.10; extra == "information"
+Provides-Extra: all
+Requires-Dist: hmmlearn>=0.3; extra == "all"
+Requires-Dist: scikit-learn>=1.2; extra == "all"
+Requires-Dist: scipy>=1.10; extra == "all"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs<2,>=1.6; extra == "docs"
+Dynamic: license-file
+
+# dfc-kit
+
+`dfc-kit` is an open-source Python toolkit for dynamic functional connectivity
+analysis of XCP-D parcellated derivatives. It provides composable estimators,
+state models, network summaries, statistical inference, and command-line
+workflows for reproducible neuroimaging analysis.
+
+```text
+BIDS -> fMRIPrep -> XCP-D -> dfc-kit
+```
+
+## Why dfc-kit
+
+`dfc-kit` provides a unified workflow for estimating time-varying functional
+connectivity, identifying recurring brain states, and testing paired or
+between-group differences. Sliding-window FC, instantaneous edges generated
+from ETS or MTD samples, LEiDA, CAP, KMeans, and Gaussian HMM analyses share
+the same data structures and output conventions, making it easier to compare
+methods without rebuilding data loading, state summaries, and statistical
+inference for every analysis.
+
+The toolkit supports both direct in-memory analysis and chunked feature stores
+for larger datasets, with matching Python and command-line interfaces.
+
+## Features
+
+- **Input and topology:** XCP-D discovery and validation, multi-atlas ROI
+  loading, acquisition identity, and censor-bounded sequences. Censored time
+  points retain their original frame indices, and temporal operations are
+  evaluated separately within contiguous retained segments.
+- **Connectivity:** weighted sliding-window FC, instantaneous ETS/MTD edges,
+  LEiDA, low-rank covariance geometry, and fixed-length MI/CMI.
+- **Connectivity and state analysis:** partition-based graph metrics, CAP, KMeans,
+  Gaussian HMMs, state alignment, occupancy/dwell/transition summaries, and
+  selection of the number of states using held-out participants.
+- **Inference:** paired sign-flips, bootstrap intervals, HC3 models,
+  declared-family FDR, generic paired endpoint inference, paired NBS, and
+  within-subject motion matching.
+- **Large-dataset workflows:** chunked, memory-mapped FeatureStores and
+  batch-wise fitting for MiniBatch KMeans and Incremental PCA.
+- **Portable results:** models and held-out predictions stored as JSON and
+  NumPy arrays with explicit feature, subject, and parameter metadata.
+
+The [method inventory](docs/method_inventory.md) maps each method family to its
+public API and guide. Public data, connectivity, state, reference, and
+inference objects are covered by the package test suite and documented
+contracts.
+
+## Scope
+
+The supported input boundary is XCP-D output. `dfc-kit` does not reimplement
+fMRIPrep-to-XCP-D denoising, filtering, censoring, interpolation, or
+parcellation. Callers provide ROI definitions, cohort labels, clinical
+variables, and manuscript-specific analyses around the library's numerical
+interfaces. The array API is also available for equivalently preprocessed ROI
+time series that are not stored as XCP-D derivatives.
+
+## Installation
+
+```bash
+python -m pip install dfc-kit
+```
+
+Install only the optional method families required by an analysis:
+
+```bash
+python -m pip install 'dfc-kit[phase,states,hmm,information,inference]'
+```
+
+Python 3.10 or newer is required. See [Getting started](docs/getting_started.md)
+for development installation and dependency details.
+
+## Quick start
+
+```python
+from dfckit.connectivity import SlidingWindowFC
+from dfckit.io import load_xcpd_run
+
+loaded = load_xcpd_run(
+    "/path/to/xcp_d",
+    subject="sub-001",
+    session="01",
+    task="rest",
+    atlases=("Schaefer200",),
+    space="MNI152NLin2009cAsym",
+    minimum_coverage=0.5,
+    tr=0.8,
+)
+
+result = SlidingWindowFC(length=60, step=10, taper="hamming").transform(loaded.run)
+print(result.features.shape)
+print(result.start_frames, result.end_frames, result.segment_ids)
+```
+
+The result contains Fisher-z upper-triangle edges and the original-frame bounds
+of every valid window. For a complete path from XCP-D discovery through state
+fitting, see the [XCP-D-to-state tutorial](docs/tutorial_xcpd_to_states.md).
+
+## Command line
+
+The `dfc-kit` command exposes XCP-D inspection, FeatureStore construction,
+state fitting, held-out prediction, scoring, alignment, and state-count
+validation. Start with:
+
+```bash
+dfc-kit --help
+dfc-kit inspect-xcpd --help
+dfc-kit build-store --help
+dfc-kit fixed-information --help
+dfc-kit describe-states --help
+dfc-kit infer-state-metrics --help
+dfc-kit summarize-store --help
+dfc-kit summarize-information --help
+dfc-kit infer-paired-endpoints --help
+```
+
+See [Command-line workflows](docs/cli.md) for complete examples and arguments,
+including fixed-length MI/CMI artifacts and frozen-window replay.
+
+## Documentation
+
+- [Documentation home](docs/index.md)
+- [XCP-D input contract](docs/xcpd_input.md)
+- [Connectivity methods](docs/correlation.md)
+- [State models and validation](docs/states.md)
+- [API map](docs/api.md)
+- [Release process](docs/release.md)
+
+## Development
+
+```bash
+python -m pip install -e '.[all,dev,docs]'
+python -m unittest discover
+ruff check src tests
+mkdocs build --strict
+```
+
+`dfc-kit` is distributed under the BSD-3-Clause license. See `LICENSE` and
+`CITATION.cff` for licensing and citation information.

dfc_kit-1.0.0.dist-info/RECORD

@@ -0,0 +1,71 @@
+dfc_kit-1.0.0.dist-info/licenses/LICENSE,sha256=kxmKO_Pwzh4hpRqvLrgakw0GknW6MZT-GpyESzUsOJg,1528
+dfckit/__init__.py,sha256=KCGdV9ixKTvXjebYTUVobRTFCNQX0ceaZ9_Wc9LmaQk,283
+dfckit/_arrays.py,sha256=8Cg2NH2ETnZlgIE7O8U-9jZJi8vU2_QgRMS5eEX2Z3Y,355
+dfckit/_preprocessing.py,sha256=11WZ0GPg3lwKbWg0rPKsFPAPj3_IvVs0JmM-227FtoM,1702
+dfckit/_validation.py,sha256=2_1bcCoLE6gPTiISdAQjD-lpTb84uz7jblc-364v9go,3637
+dfckit/cli.py,sha256=MbEkgE8bcKch-DlLR7bAtU9ahhjVt6rPqdICAQRZxy0,3426
+dfckit/data.py,sha256=DF-_bFXuOhjHe1_038I7tDLegenLchgXyaaA4ihLwxA,9403
+dfckit/reference.py,sha256=RN_8VlEfxmqhUGnMyAfAXV_8XJ7aCUlqf4PELKwa_80,14121
+dfckit/segments.py,sha256=3pNszqoKN-bznIMDEza1Of6-Phxji4NhWiWPDTjuvLw,1716
+dfckit/artifacts/__init__.py,sha256=Rq0X9IeqpCznXrXyyWJGtgWVD-uAaklWJoKwQq7XVag,900
+dfckit/artifacts/_fields.py,sha256=LlY-wFsyZFR4zAH6uujkedo1rGZgw02H03TSFkaJdVI,2224
+dfckit/artifacts/_json.py,sha256=UnbH-8lTkGcXSkKMNrJNUeXOJY8uoi0q0GFXTrd5r-0,2986
+dfckit/artifacts/_numpy.py,sha256=YwkQFnAuMgvwsRY8p5eiEJVpIPsB_5EwE0ngCNA955o,2127
+dfckit/artifacts/models.py,sha256=yVLUCjxu-_4NCCTE5dToBfRs8BNRoaAe5_o9s39FnWc,26410
+dfckit/artifacts/state_alignment.py,sha256=Me-WIDw5iCkSfbtHw46zs08E3Uk9fVqHqJAD-1638sE,4420
+dfckit/artifacts/state_results.py,sha256=f6X16wXzy7mMS_Ou3hWPzXIDZ3T13qZiaRuWbgntBKY,14626
+dfckit/artifacts/state_scoring.py,sha256=QvHMlOecgB60ozxbUR5f1hLj5DVtnv_Xr-cqhBHzO6k,18960
+dfckit/artifacts/state_stability.py,sha256=ugRF2MN6D4IW_Ii4DpcHEcJD9XQDwOQMrLbRhY3TeOM,7547
+dfckit/commands/__init__.py,sha256=mQOkYH18Zfzd8QYg_2uBFrNRR3vlnGlBVFAHZfxigZc,59
+dfckit/commands/parser.py,sha256=Dycs33QvUcFcjSpJmPJ42nKuEZMLjX38jAN2BhdG9C0,14181
+dfckit/commands/reporting.py,sha256=fGU2V3X1AlTittGwMsU6Xw_r5EHNRlQRwRM8CRquRf4,5623
+dfckit/commands/source.py,sha256=S5GdjU34Xr7uMdLhlmHxv_rqAEcXVHDl5pu7hKsOPhw,8966
+dfckit/commands/stability.py,sha256=DYM-BNCp9XXBTCNP5B7QkfxVT_sG4v_VV279Wp2DPJ8,12019
+dfckit/commands/states.py,sha256=WAzEKYcjpP18Y7npO_FCM95rALRgYcq8YpB5wSCp5dM,10751
+dfckit/connectivity/__init__.py,sha256=EjylhFWC-fhf1GqTbcle00y8gTUfVfs6ymqEoXWXHwI,1658
+dfckit/connectivity/_edge_products.py,sha256=0U7DbJpPl8XnWEyPa6waCpKW1zks79uts8xAr-k0NgQ,5338
+dfckit/connectivity/correlation.py,sha256=zqYopgGauG7PJXxOaUrNVAbHzhIidTpc5dkCGiRGj2I,2579
+dfckit/connectivity/instantaneous.py,sha256=w5nTpYATYbDkPdGwGhda6SOtJCO95F-COUdYsfcHqcs,10725
+dfckit/connectivity/leida.py,sha256=Ycf11G0hSPQLQyygAfgcETCawL2YBfokXmbljNLVkgc,7710
+dfckit/connectivity/lowrank.py,sha256=Enhc4nnbkuBN84JE6fG5mSsgkAStVIMCpytz4X94pQ0,16668
+dfckit/connectivity/partition.py,sha256=dFjUxHXQlSiVhQIq7jFzXsir8n-oRiYJDXwgXocJJLM,11612
+dfckit/connectivity/windows.py,sha256=U-dBREBxgzTA-l9AT1I7_UOHjIlZnAPubErLfWnNYJk,2856
+dfckit/inference/__init__.py,sha256=CCoa3ooCYLdsGgMAlM2pS_EEX5qnpySA7XtTmffZeGM,1298
+dfckit/inference/endpoints.py,sha256=3LtFjfU3j5vOrcSSj_cQpOQQ6TG4GbYkiMd68__9O9c,7107
+dfckit/inference/hc3.py,sha256=F4VrNQXGx9qe53wnK25hvgZWt88EzBLxaZz7abkMZRk,7409
+dfckit/inference/matching.py,sha256=MZ55KNCW4dePI_eSzWHWL3espe3hi0iitZpHiMXeRMM,12336
+dfckit/inference/multiple_testing.py,sha256=Ij2jTYJ3kSjFYkUOcluLdCMzlQ1CETqjMLTjYYldCWE,1773
+dfckit/inference/nbs.py,sha256=sMRyXw6iv_kqxEMq8eeDOXnst3rv3E8XKZ7e2oQl2zc,22006
+dfckit/inference/paired.py,sha256=jIWb31gOjGCI4sS-hhPIDcoHm9bx0mt4zUSaoA11mOM,5562
+dfckit/inference/state_metrics.py,sha256=spcBU3SCBfB3KDwZ2fSvFq6vROLJcK1R3xIHxXtUnTA,10442
+dfckit/information/__init__.py,sha256=6W8BHMnjowNI2DYrx2UFU5MHuv6cOtwxQGU4dVUweqM,1071
+dfckit/information/_artifact.py,sha256=zPVwzjfU13sjePdagD8_pqH_xSZUXNZitz1uh8b02G0,19984
+dfckit/information/estimators.py,sha256=F-mz9-A1zKBjyLO5FszJ0xLvrBCUNggIT6uer264HjY,19677
+dfckit/information/fixed.py,sha256=F_mL5rb8KcYau9ImlEpYZRvQ8C-N4f0sgkEXcOFlsXc,25612
+dfckit/information/summary.py,sha256=pr0Hg-erAXVqlb-p8M-Aj3Fstjp5s_4WWRYKPGB9G-o,2911
+dfckit/io/__init__.py,sha256=PQEtD6_nPXyTAFY4NWEyntU2T_koSddGvpfU3SGAU7I,422
+dfckit/io/xcpd.py,sha256=Mu7VA7szewDYK0B6ZC80MLYDOTGiHP1ZRsHemx4CaoU,17499
+dfckit/states/__init__.py,sha256=1o_OvbJHnJ7XjIUUfo6JBBxu6xDxS4Mbvc90WclB-9k,2664
+dfckit/states/alignment.py,sha256=JBoUMWdj0k2SyFw-Pvgovivm4Xf1L8P9m82ogjywIQg,16617
+dfckit/states/cap.py,sha256=Xa2Le_en_zhX-YQQbeD4TbO0UQ_S2UlkfGCFqnet9Ok,2251
+dfckit/states/cross_validation.py,sha256=EHTyHflanmrc0GHT4WcyB2ANEs7C_gz3tfXRNeg2FcI,4516
+dfckit/states/data.py,sha256=GNJ-9dX4_x2ZehlUaDoYMFXsS5oiFXRRL8LR6hxgZbs,17331
+dfckit/states/hmm.py,sha256=GefBHehuHVMf-eUUWZFU459ps-YFqjCTdWw2WIlyDTE,15392
+dfckit/states/interpretation.py,sha256=7I3_qX4epopk7kTArKyajvzXOGQgL7sWBt2KpqhMpHo,9983
+dfckit/states/kmeans.py,sha256=5x35H8KpnL-NQTORjU6n3l0JL3NfWumf49LlkMSRav8,14218
+dfckit/states/metrics.py,sha256=t45phWMTFK0rXfN28SRS-oj3f8SINVHKYnUn2W_2SMU,3726
+dfckit/states/scoring.py,sha256=uG1FRrskrSpsRv8OP37d1h5DUV4oY6Pub3ssU9jox4o,4201
+dfckit/states/selection.py,sha256=AQA4DmKta4Jjea2oSKq_SuBmQJlgzv-Cx75shIqdv5Y,21829
+dfckit/states/stability.py,sha256=MaSMTa8zFkW7KNNn1rFXKiUk95LcjKv7NNOJS_Bn84A,7709
+dfckit/states/streaming.py,sha256=LP6Dvrr9Bry8MHKxuD6T8D3NgcwFwgR2LX6uLJVBfm4,34964
+dfckit/states/streaming_hmm.py,sha256=ZwzPc1AGL6OWLsBM17tt29xBvghPtjYDYRwbd_9bW4Y,16947
+dfckit/storage/__init__.py,sha256=QbQmYKXRF14bD-lJDSnlu6U8h68-kYq7B0s6u8i-_pU,642
+dfckit/storage/_statistics.py,sha256=MOZsg-JlbYEypzzxMEwmHtpDw6wQSXlFSLLbCPgX9cQ,2693
+dfckit/storage/builders.py,sha256=Kj9mNBTExWzphzsjtSoq_goEDf71ihWJHFyobWBcJK0,11864
+dfckit/storage/store.py,sha256=A8sLsG21G6hIdz98LZ3CTAPPNKz6KWnSBEdP-_T-Reg,25405
+dfckit/storage/summary.py,sha256=PMFqLZzMfoIQe9HYPXPfol7b8NLKAEdUigr49eb-N_s,4898
+dfc_kit-1.0.0.dist-info/METADATA,sha256=QwEZmbTqDwRox8kXOJmSJ9Z__I4Jr_fgvUvM8Txd9SU,6841
+dfc_kit-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+dfc_kit-1.0.0.dist-info/entry_points.txt,sha256=SWlP-V-AosW-cKE7Ji2ItNeHXnzpf2WLtVjDHlQtXWw,44
+dfc_kit-1.0.0.dist-info/top_level.txt,sha256=aZFx4KeqTtnkO3XFb6XLsYLRJvgNi2VqONu0A5psdk0,7
+dfc_kit-1.0.0.dist-info/RECORD,,

dfc_kit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dfc_kit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dfc-kit = dfckit.cli:main

dfc_kit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, dfc-kit contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dfc_kit-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dfckit

dfckit/__init__.py

@@ -0,0 +1,11 @@
+"""Censor-aware dynamic functional connectivity tools."""
+
+from .data import TimeSeriesDataset, TimeSeriesRun, TimeWindow, validate_subject_disjoint
+
+__all__ = [
+    "TimeSeriesDataset",
+    "TimeSeriesRun",
+    "TimeWindow",
+    "validate_subject_disjoint",
+]
+__version__ = "1.0.0"

dfckit/_arrays.py

@@ -0,0 +1,13 @@
+"""Internal NumPy array ownership helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def readonly_copy(values: ArrayLike) -> NDArray:
+    """Return an independent NumPy array with mutation disabled."""
+    output = np.asarray(values).copy()
+    output.setflags(write=False)
+    return output

dfckit/_preprocessing.py

@@ -0,0 +1,46 @@
+"""Shared preprocessing for censor-bounded time series."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import NDArray
+
+from ._arrays import readonly_copy as _readonly
+from .data import TimeSeriesRun
+
+
+def _segment_standardized_samples(
+    run: TimeSeriesRun,
+    *,
+    method_name: str = "ETS",
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Z-score each ROI within each retained contiguous segment.
+
+    Segments shorter than two frames are omitted. Constant ROI columns become
+    zero after centering, and returned rows retain their original frame and
+    segment identities.
+    """
+    samples: 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) < 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)
+        original_indices.append(run.original_indices[positions])
+        segment_ids.append(np.full(len(positions), segment_id, dtype=np.int64))
+
+    if not samples:
+        raise ValueError(f"{method_name} requires at least one retained segment with two frames")
+    standardized = np.concatenate(samples, axis=0)
+    if not np.isfinite(standardized).all():
+        raise ValueError(f"standardized {method_name} samples contain non-finite values")
+    return (
+        _readonly(standardized),
+        _readonly(np.concatenate(original_indices)),
+        _readonly(np.concatenate(segment_ids)),
+    )

dfckit/_validation.py

@@ -0,0 +1,87 @@
+"""Internal validation shared across method families."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def validated_integer(value: object, *, label: str, minimum: int = 0) -> int:
+    """Return a Python integer after type and lower-bound validation."""
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)):
+        raise TypeError(f"{label} must be an integer")
+    if value < minimum:
+        raise ValueError(f"{label} must be at least {minimum}")
+    return int(value)
+
+
+def validated_seed(value: object, *, label: str) -> int:
+    """Return a non-negative Python integer suitable as a random seed."""
+    return validated_integer(value, label=label, minimum=0)
+
+
+def validated_positive_integer(value: object, label: str) -> int:
+    """Validate an integer using the legacy positive-value error contract."""
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)):
+        raise TypeError(f"{label} must be an integer")
+    if value < 1:
+        raise ValueError(f"{label} must be positive")
+    return int(value)
+
+
+def validated_nonnegative_integer(value: object, label: str) -> int:
+    """Validate an integer using the legacy non-negative error contract."""
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)):
+        raise TypeError(f"{label} must be an integer")
+    if value < 0:
+        raise ValueError(f"{label} must be non-negative")
+    return int(value)
+
+
+def validated_roi_indices(
+    nodes: Iterable[int],
+    *,
+    n_rois: int,
+    label: str,
+    minimum: int = 1,
+) -> NDArray[np.int64]:
+    """Validate unique integer ROI indices against a known ROI axis."""
+    raw = tuple(nodes)
+    if len(raw) < minimum:
+        quantity = "one ROI index" if minimum == 1 else f"{minimum} ROI indices"
+        raise ValueError(f"{label} must contain at least {quantity}")
+    if any(
+        isinstance(node, (bool, np.bool_)) or not isinstance(node, (int, np.integer))
+        for node in raw
+    ):
+        raise TypeError(f"{label} must contain integer ROI indices")
+    output = np.asarray(raw, dtype=np.int64)
+    if len(set(output.tolist())) != len(output):
+        raise ValueError(f"{label} contains duplicate ROI indices")
+    if np.any(output < 0) or np.any(output >= n_rois):
+        raise ValueError(f"{label} contains an ROI index outside [0, {n_rois})")
+    return output
+
+
+def validated_subject_labels(subjects: Iterable[str], *, n_observations: int) -> tuple[str, ...]:
+    """Validate one non-empty subject label per observation, allowing repeats."""
+    output = tuple(str(subject) for subject in subjects)
+    if len(output) != n_observations:
+        raise ValueError("subjects must contain one identifier per observation")
+    if any(not subject.strip() for subject in output):
+        raise ValueError("subject identifiers must be non-empty")
+    return output
+
+
+def validated_subject_ids(subject_ids: Sequence[str], n_observations: int) -> tuple[str, ...]:
+    """Validate one unique, non-empty participant ID per observation."""
+    identifiers = tuple(str(subject) for subject in subject_ids)
+    if len(identifiers) != n_observations:
+        raise ValueError("subject_ids must match the number of observations")
+    if any(not subject.strip() for subject in identifiers):
+        raise ValueError("subject_ids cannot contain empty identifiers")
+    if len(set(identifiers)) != len(identifiers):
+        raise ValueError("subject_ids must contain one unique entry per participant")
+    return identifiers

dfckit/artifacts/__init__.py

@@ -0,0 +1,36 @@
+"""Portable model, prediction, score, and alignment artifacts."""
+
+from .models import (
+    FittedModel,
+    load_fitted_model,
+    save_fitted_model,
+)
+from .state_alignment import load_state_alignment, save_state_alignment
+from .state_results import (
+    StatePredictions,
+    load_state_predictions,
+    save_state_predictions,
+    write_state_metrics,
+)
+from .state_scoring import (
+    StateModelScoreReport,
+    load_state_model_scores,
+    write_state_model_scores,
+)
+from .state_stability import write_state_stability
+
+__all__ = [
+    "FittedModel",
+    "StateModelScoreReport",
+    "StatePredictions",
+    "load_fitted_model",
+    "load_state_alignment",
+    "load_state_model_scores",
+    "load_state_predictions",
+    "save_fitted_model",
+    "save_state_alignment",
+    "save_state_predictions",
+    "write_state_metrics",
+    "write_state_model_scores",
+    "write_state_stability",
+]

dfckit/artifacts/_fields.py

@@ -0,0 +1,67 @@
+"""Scalar and collection validation for persisted artifact schemas."""
+
+from __future__ import annotations
+
+from itertools import pairwise
+
+import numpy as np
+
+
+def artifact_integer(value: object, name: str, *, minimum: int = 0) -> int:
+    """Validate an integer artifact field using schema-style errors."""
+    if (
+        isinstance(value, (bool, np.bool_))
+        or not isinstance(value, (int, np.integer))
+        or value < minimum
+    ):
+        raise ValueError(f"{name} must be an integer of at least {minimum}")
+    return int(value)
+
+
+def artifact_finite_float(
+    value: object,
+    name: str,
+    *,
+    positive: bool = False,
+) -> float:
+    """Validate a finite numeric artifact field."""
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be numeric")
+    output = float(value)
+    if not np.isfinite(output) or (positive and output <= 0.0):
+        qualifier = "finite and positive" if positive else "finite"
+        raise ValueError(f"{name} must be {qualifier}")
+    return output
+
+
+def artifact_integer_grid(
+    value: object,
+    name: str,
+    *,
+    minimum: int,
+    minimum_count: int,
+) -> tuple[int, ...]:
+    """Validate a strictly increasing integer grid in an artifact."""
+    if not isinstance(value, list) or len(value) < minimum_count:
+        raise ValueError(f"{name} must contain at least {minimum_count} values")
+    output = tuple(artifact_integer(item, name, minimum=minimum) for item in value)
+    if len(set(output)) != len(output) or any(
+        right <= left for left, right in pairwise(output)
+    ):
+        raise ValueError(f"{name} must be strictly increasing and unique")
+    return output
+
+
+def sample_intervals_match(left: object, right: float | None) -> bool:
+    """Compare nullable positive sample intervals with fixed absolute tolerance."""
+    if left is None or right is None:
+        return left is None and right is None
+    try:
+        observed = artifact_finite_float(
+            left,
+            "sample_interval_seconds",
+            positive=True,
+        )
+    except (TypeError, ValueError):
+        return False
+    return bool(np.isclose(observed, right, rtol=0.0, atol=1e-9))

dfckit/artifacts/_json.py

@@ -0,0 +1,92 @@
+"""Strict JSON persistence shared by artifact modules."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+
+def strict_object_hook(context: str) -> Callable[[list[tuple[str, object]]], dict[str, object]]:
+    """Return an object-pairs hook that rejects duplicate JSON fields."""
+
+    def hook(pairs: list[tuple[str, object]]) -> dict[str, object]:
+        output: dict[str, object] = {}
+        for key, value in pairs:
+            if key in output:
+                raise ValueError(f"duplicate JSON field in {context}: {key}")
+            output[key] = value
+        return output
+
+    return hook
+
+
+def nonstandard_constant_hook(context: str) -> Callable[[str], object]:
+    """Return a parse hook that rejects NaN and infinite JSON constants."""
+
+    def hook(value: str) -> object:
+        raise ValueError(f"non-standard JSON constant in {context}: {value}")
+
+    return hook
+
+
+def load_json_object(path: str | Path, *, context: str) -> dict[str, Any]:
+    """Read one finite JSON object while rejecting duplicate fields."""
+    source = Path(path)
+    if not source.is_file():
+        raise FileNotFoundError(f"{context} does not exist: {source}")
+    try:
+        value = json.loads(
+            source.read_text(encoding="utf-8"),
+            object_pairs_hook=strict_object_hook(context),
+            parse_constant=nonstandard_constant_hook(context),
+        )
+    except (OSError, json.JSONDecodeError) as error:
+        raise ValueError(f"cannot read {context} {source}: {error}") from error
+    if not isinstance(value, dict):
+        raise TypeError(f"{context} must be a JSON object")
+    return value
+
+
+def write_json_atomic(
+    path: str | Path,
+    payload: object,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Atomically write finite JSON, creating or replacing one regular file."""
+    target = Path(path)
+    if not overwrite and (target.exists() or target.is_symlink()):
+        raise FileExistsError(f"JSON output already exists: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{target.name}.tmp-",
+        dir=target.parent,
+        text=True,
+    )
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+            json.dump(payload, stream, indent=2, sort_keys=True, allow_nan=False)
+            stream.write("\n")
+        if overwrite:
+            os.replace(temporary, target)
+        else:
+            if target.exists() or target.is_symlink():
+                raise FileExistsError(f"JSON output already exists: {target}")
+            os.rename(temporary, target)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise
+    return target
+
+
+__all__ = [
+    "load_json_object",
+    "nonstandard_constant_hook",
+    "strict_object_hook",
+    "write_json_atomic",
+]