indi-net-extract 0.1.0.dev0__tar.gz

indi_net_extract-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 更新记录
+
+## 0.1.0.dev0
+
+- 初始开发版本：模板引导的双回归β和独立Python GIG-ICA。
+- 支持按被试批处理、两层并行参数、连续结果保存与重新载入。
+- 提供空间平滑、有限有符号Top-N、精确模板Dice及网络重叠比例。
+- 分发名为indi-net-extract，导入名为indinetextract。
+- 源码包补齐文档、示例和完整测试附件；构建与复查步骤见[分发说明](docs/distribution.md)。
+- 许可证元数据采用标准SPDX表达式和project.license-files，最低构建依赖更新为setuptools 77.0.3。
+- 尚未发布到PyPI；验证范围见docs/validation.md。

indi_net_extract-0.1.0.dev0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, indinetextract 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.
+
+The GIG-ICA source additionally retains its original notice; see
+THIRD_PARTY_NOTICES.md and src/indinetextract/_algorithms/gig_ica.py.

indi_net_extract-0.1.0.dev0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md CHANGELOG.md
+include docs/methods.md docs/validation.md docs/distribution.md
+recursive-include examples *.py
+recursive-include tests *.py

indi_net_extract-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: indi-net-extract
+Version: 0.1.0.dev0
+Summary: Template-guided individual network extraction and spatial overlap evaluation
+License-Expression: BSD-3-Clause
+Project-URL: Source, https://github.com/sonia1maslova/indi-net-extract
+Project-URL: Documentation, https://github.com/sonia1maslova/indi-net-extract/blob/main/README.md
+Project-URL: Issues, https://github.com/sonia1maslova/indi-net-extract/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: nibabel>=5.2
+Requires-Dist: threadpoolctl>=3.1
+Dynamic: license-file
+
+# IndiNetExtract
+
+Python分发名（安装名）：`indi-net-extract`。Python导入名和源码包目录：`indinetextract`。
+
+模板引导的个体网络提取工具包，开发初版 `0.1.0.dev0`。目前提供Python源码，尚未发布到PyPI。
+
+输入被试ID列表、逐项对应的静息态影像路径，以及全体共用的模板和mask。输出每名被试的连续网络图、时间序列及运行记录。支持经典双回归β和独立NumPy/SciPy GIG-ICA。
+
+**每名被试只输入一份已经准备好的4D NIfTI。** 数据清洗、扫描标准化、拼接和空间配准在包外完成。批处理列表表示不同被试，不表示要拼接的扫描。算法内部所需的中心化、白化和双回归时间序列归一化仍保留。
+
+## 从源码安装
+
+当前为开发初版，尚未发布到PyPI。可从本仓库安装：
+
+```bash
+git clone https://github.com/sonia1maslova/indi-net-extract.git
+cd indi-net-extract
+python -m pip install .
+```
+
+## 快速使用
+
+在已具备NumPy、SciPy、NiBabel、threadpoolctl的环境中，将本包 `src` 加入 `PYTHONPATH`，或安装本地构建产物。已测试的软件版本和验证边界见 `docs/validation.md`；以下示例不下载或修改数据。
+
+安装已下载的wheel时，文件名中的分发名按打包规则写成 `indi_net_extract`：
+
+```bash
+python -m pip install /path/to/indi_net_extract-0.1.0.dev0-py3-none-any.whl
+```
+
+安装后仍使用 `from indinetextract import ...`。分发名中的连字符不用于Python导入语句。
+
+```python
+from indinetextract import extract_batch
+
+def main():
+    batch = extract_batch(
+        subject_ids=["sub-001", "sub-002"],
+        fmri_paths=[
+            "/data/sub-001/rest_preprocessed.nii.gz",
+            "/data/sub-002/rest_preprocessed.nii.gz",
+        ],
+        templates="/data/templates.nii.gz",
+        mask="/data/analysis_mask.nii.gz",
+        output_root="/results/gig_ica",
+        method="gig_ica",
+        n_jobs=2,
+        n_threads=2,
+    )
+    print(batch.summary)
+
+if __name__ == "__main__":
+    main()
+```
+
+并行采用独立进程，脚本需要上面的 `__main__` 保护。只处理一名时，也传入长度为1的两个列表。输入文件名不必含被试ID；包按列表位置配对，不推测文件属于谁。
+
+| 参数 | 含义 |
+| --- | --- |
+| `subject_ids` | 非空且唯一的字符串ID列表 |
+| `fmri_paths` | 等长路径列表，每条路径是一名被试的一份4D影像 |
+| `templates` | 同一份4D空间模板，第四维为K个成分 |
+| `mask` | 同一份3D二值分析mask |
+| `method` | `"dual_regression"` 或 `"gig_ica"` |
+| `n_jobs=1` | 最多同时处理的被试数，即进程数 |
+| `n_threads=2` | 每名被试数值计算的线程预算 |
+| `label="extraction"` | 被试目录下的本次输出标签；可用不同标签区分方法、模板或测量日 |
+| `on_error="continue"` | 记录失败后继续；`"raise"` 表示停止提交新被试，等待正在运行的被试结束后报错 |
+| `work_dir=None` | 可选临时存储目录；每名被试使用独立临时子目录 |
+
+例如 `n_jobs=3, n_threads=2` 表示最多3名被试同时拟合，每名的数值运算预算为2线程。它不保证总内存足够；GIG-ICA仍需白化和SVD工作内存。默认串行执行，不自动增加进程。
+
+## 输出
+
+```text
+output_root/
+  _batches/<batch_id>/
+    inputs.tsv                   # 保存原ID—影像配对
+    summary.tsv                  # 顺序与输入一致，包含状态及失败原因
+    metadata.json                # 共用设置、环境及源码指纹
+  sub-001/extraction/
+    continuous_components.nii.gz  # X×Y×Z×K，连续成分
+    timecourses.tsv              # T×K，行是时间点，无标题行
+    components.tsv               # 0起始图像索引与成分ID
+    mask.nii.gz
+    metadata.json
+  sub-002/extraction/
+    ...
+```
+
+连续图的第四维是**成分**，不是时间；第i张图对应第i个模板。默认成分ID为C1…CK。双回归输出空间β，GIG-ICA输出成分权重，两者不当作统计Z或概率。
+
+一名完成后立即保存。`BatchResult`只返回轻量记录和文件路径，不把全体影像留在内存。失败被试不产生一个伪成功的结果目录。默认不覆盖已有结果；显式调用结果对象的 `save(overwrite=True)` 时，旧目录改名为备份并保留。
+
+## 独立后处理与模板Dice
+
+已经提取好的连续图可以重新载入，改变平滑或Top-N时不用重新拟合：
+
+```python
+from indinetextract import NetworkResult, postprocess_maps, template_dice, overlap_fraction
+
+fit = NetworkResult.load("/results/gig_ica/sub-001/extraction")
+binary = postprocess_maps(
+    fit,
+    fwhm_mm=6,
+    count_reference="/data/fixed_binary_reference.nii.gz",
+)
+binary.save("/results/gig_ica", label="fwhm_6mm")
+
+dice = template_dice(binary, reference="/data/fixed_binary_reference.nii.gz")
+print(dice.per_component, dice.mean_dice)
+dice.save("/results/gig_ica", label="fwhm_6mm/template_dice")
+
+pleiotropy = overlap_fraction(binary)  # 3D NIfTI对象，值为所选成分比例
+```
+
+- `count_reference`必须是二值图，在mask内计数得到每成分N。也可以改用显式的 `top_n=[...]`，两者必须二选一。
+- 用于提取的模板允许连续值；用于计数和Dice的参考图必须明确为0/1。切换提取模板不自动改变N。
+- 平滑使用 `G(M*f)/G(M)`，仅沿空间维，保留原mask。每个宽度都从原始连续图开始。NIfTI空间单位unknown时按mm解释并记录；正宽度平滑拒绝剪切网格。
+- Top-N按有限的有符号数值降序选严格N个，允许零值和负值；并列按原始Fortran体素索引。候选不足时报错，不自动缩小N。
+- Dice矩阵行是个体成分，列是参考成分；对应分数是对角线。不自动换序、翻符号或选择最佳配对。
+- 单侧为空时Dice为0，双侧为空为NaN；存在无效对应成分时完整K成分均值为NaN。JSON中缺失数值保存为null，TSV中为nan。
+- `overlap_fraction`为K张二值图的逐体素平均；它不自动构成统计显著性检验。
+
+## 输入约束与验证边界
+
+所有影像必须事先对齐，空间形状一致，affine数值在记录的容差内一致。mask显式提供，保持不变。mask外不参与计算；mask内NaN/Inf或时间常量BOLD序列会报错，包不自动插补或删除体素。
+
+独立Python GIG核心保留原算法源码许可与控制流程。此前合成数据及三名真实被试有MATLAB对照，真实数据不是所有数值严格相等。此包封装的验证范围和具体检查见 [docs/validation.md](docs/validation.md)；不能只依据模板Dice较高就判定个体网络科学有效。
+
+当前实际验证使用Python3.13项目环境；其他Python版本和Windows原生并行尚需分别测试。声明最低Python版本不等于所有组合均已测试。
+
+自动单元测试不依赖MATLAB或FSL；本轮另外完成了两种模板的小型FSL对照。更新算法一致性结论时，应保留输入、源码、参数和数值误差。
+
+## 来源与许可
+
+GIG数值核心位于 `_algorithms/gig_ica.py`，来自已有NumPy/SciPy移植；原始来源为GIFT `icatb_gigicar.m`，作者Yuhui Du、Yong Fan。版权与许可保留在文件头及 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。其他初版代码采用BSD-3-Clause许可。

indi_net_extract-0.1.0.dev0/README.md

@@ -0,0 +1,137 @@
+# IndiNetExtract
+
+Python分发名（安装名）：`indi-net-extract`。Python导入名和源码包目录：`indinetextract`。
+
+模板引导的个体网络提取工具包，开发初版 `0.1.0.dev0`。目前提供Python源码，尚未发布到PyPI。
+
+输入被试ID列表、逐项对应的静息态影像路径，以及全体共用的模板和mask。输出每名被试的连续网络图、时间序列及运行记录。支持经典双回归β和独立NumPy/SciPy GIG-ICA。
+
+**每名被试只输入一份已经准备好的4D NIfTI。** 数据清洗、扫描标准化、拼接和空间配准在包外完成。批处理列表表示不同被试，不表示要拼接的扫描。算法内部所需的中心化、白化和双回归时间序列归一化仍保留。
+
+## 从源码安装
+
+当前为开发初版，尚未发布到PyPI。可从本仓库安装：
+
+```bash
+git clone https://github.com/sonia1maslova/indi-net-extract.git
+cd indi-net-extract
+python -m pip install .
+```
+
+## 快速使用
+
+在已具备NumPy、SciPy、NiBabel、threadpoolctl的环境中，将本包 `src` 加入 `PYTHONPATH`，或安装本地构建产物。已测试的软件版本和验证边界见 `docs/validation.md`；以下示例不下载或修改数据。
+
+安装已下载的wheel时，文件名中的分发名按打包规则写成 `indi_net_extract`：
+
+```bash
+python -m pip install /path/to/indi_net_extract-0.1.0.dev0-py3-none-any.whl
+```
+
+安装后仍使用 `from indinetextract import ...`。分发名中的连字符不用于Python导入语句。
+
+```python
+from indinetextract import extract_batch
+
+def main():
+    batch = extract_batch(
+        subject_ids=["sub-001", "sub-002"],
+        fmri_paths=[
+            "/data/sub-001/rest_preprocessed.nii.gz",
+            "/data/sub-002/rest_preprocessed.nii.gz",
+        ],
+        templates="/data/templates.nii.gz",
+        mask="/data/analysis_mask.nii.gz",
+        output_root="/results/gig_ica",
+        method="gig_ica",
+        n_jobs=2,
+        n_threads=2,
+    )
+    print(batch.summary)
+
+if __name__ == "__main__":
+    main()
+```
+
+并行采用独立进程，脚本需要上面的 `__main__` 保护。只处理一名时，也传入长度为1的两个列表。输入文件名不必含被试ID；包按列表位置配对，不推测文件属于谁。
+
+| 参数 | 含义 |
+| --- | --- |
+| `subject_ids` | 非空且唯一的字符串ID列表 |
+| `fmri_paths` | 等长路径列表，每条路径是一名被试的一份4D影像 |
+| `templates` | 同一份4D空间模板，第四维为K个成分 |
+| `mask` | 同一份3D二值分析mask |
+| `method` | `"dual_regression"` 或 `"gig_ica"` |
+| `n_jobs=1` | 最多同时处理的被试数，即进程数 |
+| `n_threads=2` | 每名被试数值计算的线程预算 |
+| `label="extraction"` | 被试目录下的本次输出标签；可用不同标签区分方法、模板或测量日 |
+| `on_error="continue"` | 记录失败后继续；`"raise"` 表示停止提交新被试，等待正在运行的被试结束后报错 |
+| `work_dir=None` | 可选临时存储目录；每名被试使用独立临时子目录 |
+
+例如 `n_jobs=3, n_threads=2` 表示最多3名被试同时拟合，每名的数值运算预算为2线程。它不保证总内存足够；GIG-ICA仍需白化和SVD工作内存。默认串行执行，不自动增加进程。
+
+## 输出
+
+```text
+output_root/
+  _batches/<batch_id>/
+    inputs.tsv                   # 保存原ID—影像配对
+    summary.tsv                  # 顺序与输入一致，包含状态及失败原因
+    metadata.json                # 共用设置、环境及源码指纹
+  sub-001/extraction/
+    continuous_components.nii.gz  # X×Y×Z×K，连续成分
+    timecourses.tsv              # T×K，行是时间点，无标题行
+    components.tsv               # 0起始图像索引与成分ID
+    mask.nii.gz
+    metadata.json
+  sub-002/extraction/
+    ...
+```
+
+连续图的第四维是**成分**，不是时间；第i张图对应第i个模板。默认成分ID为C1…CK。双回归输出空间β，GIG-ICA输出成分权重，两者不当作统计Z或概率。
+
+一名完成后立即保存。`BatchResult`只返回轻量记录和文件路径，不把全体影像留在内存。失败被试不产生一个伪成功的结果目录。默认不覆盖已有结果；显式调用结果对象的 `save(overwrite=True)` 时，旧目录改名为备份并保留。
+
+## 独立后处理与模板Dice
+
+已经提取好的连续图可以重新载入，改变平滑或Top-N时不用重新拟合：
+
+```python
+from indinetextract import NetworkResult, postprocess_maps, template_dice, overlap_fraction
+
+fit = NetworkResult.load("/results/gig_ica/sub-001/extraction")
+binary = postprocess_maps(
+    fit,
+    fwhm_mm=6,
+    count_reference="/data/fixed_binary_reference.nii.gz",
+)
+binary.save("/results/gig_ica", label="fwhm_6mm")
+
+dice = template_dice(binary, reference="/data/fixed_binary_reference.nii.gz")
+print(dice.per_component, dice.mean_dice)
+dice.save("/results/gig_ica", label="fwhm_6mm/template_dice")
+
+pleiotropy = overlap_fraction(binary)  # 3D NIfTI对象，值为所选成分比例
+```
+
+- `count_reference`必须是二值图，在mask内计数得到每成分N。也可以改用显式的 `top_n=[...]`，两者必须二选一。
+- 用于提取的模板允许连续值；用于计数和Dice的参考图必须明确为0/1。切换提取模板不自动改变N。
+- 平滑使用 `G(M*f)/G(M)`，仅沿空间维，保留原mask。每个宽度都从原始连续图开始。NIfTI空间单位unknown时按mm解释并记录；正宽度平滑拒绝剪切网格。
+- Top-N按有限的有符号数值降序选严格N个，允许零值和负值；并列按原始Fortran体素索引。候选不足时报错，不自动缩小N。
+- Dice矩阵行是个体成分，列是参考成分；对应分数是对角线。不自动换序、翻符号或选择最佳配对。
+- 单侧为空时Dice为0，双侧为空为NaN；存在无效对应成分时完整K成分均值为NaN。JSON中缺失数值保存为null，TSV中为nan。
+- `overlap_fraction`为K张二值图的逐体素平均；它不自动构成统计显著性检验。
+
+## 输入约束与验证边界
+
+所有影像必须事先对齐，空间形状一致，affine数值在记录的容差内一致。mask显式提供，保持不变。mask外不参与计算；mask内NaN/Inf或时间常量BOLD序列会报错，包不自动插补或删除体素。
+
+独立Python GIG核心保留原算法源码许可与控制流程。此前合成数据及三名真实被试有MATLAB对照，真实数据不是所有数值严格相等。此包封装的验证范围和具体检查见 [docs/validation.md](docs/validation.md)；不能只依据模板Dice较高就判定个体网络科学有效。
+
+当前实际验证使用Python3.13项目环境；其他Python版本和Windows原生并行尚需分别测试。声明最低Python版本不等于所有组合均已测试。
+
+自动单元测试不依赖MATLAB或FSL；本轮另外完成了两种模板的小型FSL对照。更新算法一致性结论时，应保留输入、源码、参数和数值误差。
+
+## 来源与许可
+
+GIG数值核心位于 `_algorithms/gig_ica.py`，来自已有NumPy/SciPy移植；原始来源为GIFT `icatb_gigicar.m`，作者Yuhui Du、Yong Fan。版权与许可保留在文件头及 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。其他初版代码采用BSD-3-Clause许可。

indi_net_extract-0.1.0.dev0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,30 @@
+# Third-party source notices
+
+The GIG-ICA Python core retains the following original notice. Original source: GIFT icatb_gigicar.m; source SHA256: 6a0bbf665524d0122686ce6416d06350cb21d71f90460c282aa539f76803773c.
+
+Copyright (c) 2012 Yuhui DU and Yong FAN
+All rights reserved.
+
+Redistribution and use in source or any other forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice,
+  this list of conditions and the following disclaimer.
+* Redistributions in any other 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.
+* Neither the names of the copyright holders nor the names of future
+  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 OWNER 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.

indi_net_extract-0.1.0.dev0/docs/distribution.md

@@ -0,0 +1,55 @@
+# 构建与检查分发文件
+
+源码发行包（sdist，扩展名为 `.tar.gz`）保留源码和开发附件。安装包（wheel，扩展名为 `.whl`）用于安装运行库。两者用途不同，因此包含的文件也不同。
+
+## 源码包附件清单
+
+`MANIFEST.in` 指定需要额外收入源码包的文件：
+
+| 文件或目录 | 内容 |
+| --- | --- |
+| `README.md`、`CHANGELOG.md` | 使用入口和更新记录 |
+| `docs/methods.md` | 方法与参数说明 |
+| `docs/validation.md` | 已完成的验证及其边界 |
+| `docs/distribution.md` | 本构建说明 |
+| `examples/*.py` | 两个使用示例，需要用户提供输入影像和输出路径 |
+| `tests/*.py` | 四个测试模块、`helpers.py`、`__init__.py` 和 `validate_distribution.py` |
+
+`pyproject.toml` 声明运行依赖、构建依赖和许可证；构建工具同时收入 `src/indinetextract/` 下的运行源码。`LICENSE` 和 `THIRD_PARTY_NOTICES.md` 由 `project.license-files` 指定，同时进入源码包和 wheel。
+
+wheel 包含运行库、分发元数据和许可证文件。文档、示例和测试保留在源码包中，不随 wheel 安装。
+
+## 构建和格式检查
+
+在维护者的开发环境中安装构建工具，然后从源码根目录执行：
+
+```bash
+python -m pip install build twine
+python -m build
+python -m twine check --strict dist/*
+```
+
+构建依赖要求 `setuptools>=77.0.3`，以支持标准许可证标识（SPDX 表达式）和 `project.license-files`。当前许可证表达式为 `BSD-3-Clause`。配置格式更新不改变许可证正文和第三方声明。
+
+默认的 `python -m build` 先生成源码包，再从源码包构建 wheel。已有构建依赖的受控环境可使用 `python -m build --no-isolation`，直接使用当前环境中的工具。
+
+`twine check` 检查分发元数据和 README 格式，不验证算法，也不会上传文件。
+
+## 从源码包复查
+
+将生成的 `.tar.gz` 解压到一个新目录，进入包含 `pyproject.toml` 的目录，在已安装运行依赖的环境中执行：
+
+```bash
+python -m pip install .
+python -m unittest discover -s tests -t . -v
+```
+
+测试使用合成数据，不需要研究影像、MATLAB 或 FSL。命令在解压目录中执行，可以检查源码包是否带齐测试模块及其辅助文件。
+
+若需要检查 wheel 中的两进程 GIG-ICA 和结果保存/载入，先安装对应 wheel，再从同一解压目录执行以下命令；输出目录必须尚不存在：
+
+```bash
+python -m tests.validate_distribution --output-root ./synthetic-distribution-check
+```
+
+此命令默认只用合成数据。可选参数 `--fsl-dir` 用于额外的 FSL 对照，具体范围见 [验证说明](validation.md)。构建、格式检查、单元测试和上传是不同步骤；上述命令均不发布到 PyPI。

indi_net_extract-0.1.0.dev0/docs/methods.md

@@ -0,0 +1,31 @@
+# 方法与数据约定
+
+## 输入与方法分开
+
+每名被试提供一份已准备好的4D静息态NIfTI。清洗、逐扫描标准化、拼接和配准由调用者完成。包只在共同mask内提取数据，并按各算法本身的要求中心化、白化或归一化。没有 `run_normalization` 或扫描拼接参数。
+
+内部矩阵为BOLD `T×V`、模板 `V×K`、个体图 `V×K`、时间序列 `T×K`。mask内体素按NIfTI Fortran索引排列，并按同一顺序映射回图像。成分顺序从模板保留到输出，不自动匹配或翻转符号。
+
+## 经典双回归
+
+第一步以K张模板为共同解释变量，估计各成分随时间变化的系数；第二步以这些时间序列为共同解释变量，估计每个体素的成分β。
+
+实现沿用项目已对照的经典路线：模板空间去均值及总体标准差缩放；输入整体时间去均值；第一步时间序列去均值并按样本标准差 `ddof=1` 归一化；第二步包含截距。该设置对应FSL `des_norm=1`。输出是连续β，不是统计Z；没有空间先验惩罚或时间点加权。
+
+## GIG-ICA
+
+采用现有独立NumPy/SciPy移植，保留作者算法的白化、阈值与回退、模板标准化、非高斯性和模板对应目标，以及迭代停止规则。默认使用已对照的SVD伪逆路线。没有另外加入跨成分正交约束。
+
+输入加载使用临时memmap控制加载副本；白化和SVD仍需要内存，不能把该实现理解为完全在磁盘上运算。逐被试完成后保存结果，批次只返回状态和路径。
+
+## 平滑与选取
+
+平滑在连续图提取后、二值化前执行：`G(M*f)/G(M)`，保留原mask，高斯核截断4倍标准差。每个宽度从同一份原始连续图独立计算，只沿三个空间轴平滑。
+
+固定Top-N按有限带符号值降序选取；零值、负值可以入选。并列时按原始Fortran体素索引排序。每成分必须选足N，N来自显式列表或固定二值参考在mask内的计数。
+
+## 评价
+
+精确Dice为 `2×交集体素数/(个体体素数+参考体素数)`。完整矩阵的行是个体成分，列是参考成分；对应分数取对角线。单侧为空为0，双侧为空为NaN，不能静默忽略无效成分后报告完整K成分均值。
+
+`overlap_fraction` 是K张二值图的逐体素平均。固定mask、K和各成分N时，全mask平均值固定，因此不是有个体差异的总体指标。

indi_net_extract-0.1.0.dev0/docs/validation.md

@@ -0,0 +1,35 @@
+# 验证范围
+
+版本：0.1.0.dev0。验证日期：2026-11-10。本页概述已完成的检查和仍未验证的范围；首次公开仓库不会自动增加已验证的平台或数据范围。
+
+## 初版检查
+
+- 54项单元及接口测试通过：批处理10项、提取数值12项、后处理和Dice 21项、保存/载入11项。
+- 小型合成输入中，双回归串行和两进程结果一致；wheel中的两进程GIG-ICA、平滑、Top-N及结果保存/回读通过。
+- 两组小型FSL双回归对照通过。连续与二值模板的β最大绝对差分别为1.0529613776733004e-6和1.190774973361397e-6。
+- 分发名改为indi-net-extract后，独立目标目录安装、元数据、导入和小型并行检查通过；该次修改没有重跑上述全部54项检查或FSL。
+
+## 独立GIG-ICA核心
+
+已有11项核心检查、6组合成数据与未修改作者MATLAB核心的独立对照，以及原研究队列中预先选定的三名真实被试对照。真实被试连续成分的最低空间相关为0.997386、0.999585、0.999906，最大单成分相对误差为7.23%、2.88%、1.37%。结果接近，但没有全部达到严格数值等价标准。
+
+MATLAB复算、白化及求解器诊断支持近零特征值的数值敏感性是差异来源之一，尚未证明它是唯一原因。不能只凭高相关或高Dice认定逐值一致，也不能把核心的历史验证当作封装后真实大样本的完整验证。
+
+## 实际测试环境
+
+Python 3.13.14；NumPy 2.2.6；SciPy 1.15.3；NiBabel 5.4.2；threadpoolctl 3.6.0。FSL独立对照使用6.0.4。MATLAB和FSL用于外部对照，不是工具运行依赖。
+
+声明Python >=3.11不等于所有这些版本都已测试。其他Python/数值库组合、Windows原生多进程、真实大样本内存峰值和长时运行仍待验证。
+
+## 在自己的环境复查
+
+先安装运行依赖，再从仓库根目录执行：
+
+```bash
+python -m pip install .
+python -m unittest discover -s tests -t . -v
+```
+
+本仓库的单元测试使用合成数据，不需要下载研究影像，不调用MATLAB或FSL。可选的分发检查脚本是tests/validate_distribution.py；它要求使用新输出目录。
+
+源码包也包含上述测试模块及其辅助文件。构建、格式检查和从解压目录复查的步骤见[分发说明](distribution.md)。`tests.validate_distribution`不传`--fsl-dir`时只执行合成数据检查，传入该参数时再增加FSL对照。

indi_net_extract-0.1.0.dev0/examples/batch_extraction.py

@@ -0,0 +1,26 @@
+"""Run a batch from already prepared images; no raw-data preprocessing."""
+from __future__ import annotations
+
+import argparse
+import json
+
+from indinetextract import extract_batch
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--subject-ids", nargs="+", required=True)
+    parser.add_argument("--fmri-paths", nargs="+", required=True)
+    parser.add_argument("--templates", required=True)
+    parser.add_argument("--mask", required=True)
+    parser.add_argument("--output-root", required=True)
+    parser.add_argument("--method", choices=["dual_regression", "gig_ica"], required=True)
+    parser.add_argument("--n-jobs", type=int, default=1)
+    parser.add_argument("--n-threads", type=int, default=2)
+    args = parser.parse_args()
+    result = extract_batch(**vars(args))
+    print(json.dumps(result.summary, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

indi_net_extract-0.1.0.dev0/examples/compare_postprocessing.py

@@ -0,0 +1,27 @@
+"""Re-use one saved fit for independent smoothing widths and exact Dice."""
+from __future__ import annotations
+
+import argparse
+
+from indinetextract import NetworkResult, postprocess_maps, template_dice
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--extraction", required=True)
+    parser.add_argument("--binary-reference", required=True)
+    parser.add_argument("--output-root", required=True)
+    parser.add_argument("--fwhm-mm", type=float, nargs="+", default=[0, 2, 4, 6])
+    args = parser.parse_args()
+    fit = NetworkResult.load(args.extraction)
+    for width in args.fwhm_mm:
+        label = "fwhm_" + format(width, "g") + "mm"
+        binary = postprocess_maps(fit, fwhm_mm=width, count_reference=args.binary_reference)
+        binary.save(args.output_root, label=label)
+        result = template_dice(binary, reference=args.binary_reference)
+        result.save(args.output_root, label=label + "/template_dice")
+        print(width, result.mean_dice)
+
+
+if __name__ == "__main__":
+    main()

indi_net_extract-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "indi-net-extract"
+version = "0.1.0.dev0"
+description = "Template-guided individual network extraction and spatial overlap evaluation"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "BSD-3-Clause"
+license-files = ["LICENSE", "THIRD_PARTY_NOTICES.md"]
+dependencies = ["numpy>=1.26", "scipy>=1.11", "nibabel>=5.2", "threadpoolctl>=3.1"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true
+
+
+[project.urls]
+Source = "https://github.com/sonia1maslova/indi-net-extract"
+Documentation = "https://github.com/sonia1maslova/indi-net-extract/blob/main/README.md"
+Issues = "https://github.com/sonia1maslova/indi-net-extract/issues"

indi_net_extract-0.1.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+