heterodecomp 0.1.0__tar.gz

heterodecomp-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include examples *.py *.md

heterodecomp-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: heterodecomp
+Version: 0.1.0
+Summary: Shared and individual pattern decomposition for heterogeneous data
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=1.5
+Requires-Dist: pillow>=9
+Requires-Dist: scipy>=1.9
+Requires-Dist: tensorly>=0.8
+Requires-Dist: torch>=2.0
+Provides-Extra: eeg
+Requires-Dist: mne>=1.6; extra == "eeg"
+Provides-Extra: test
+Requires-Dist: build>=1; extra == "test"
+Requires-Dist: twine>=5; extra == "test"
+
+# HeteroDecomp
+
+HeteroDecomp separates repeated data items into shared, individual-specific, and
+residual patterns. It accepts time-series tables (BOLD, EEG, and similar
+signals), general matrices (including symmetric FC matrices), and common image
+formats.
+
+## Install for development
+
+```bash
+python -m pip install -e .
+```
+
+Install the optional EEG reader for MNE FIF files:
+
+```bash
+python -m pip install -e ".[eeg]"
+```
+
+## Basic API
+
+```python
+from heterodecomp import decompose
+
+result = decompose(
+    r"D:\data\bold",
+    kind="timeseries",
+    algorithm="perpca",
+    shared_rank=5,
+    individual_rank=2,
+    params={"epochs": 200, "lr": 0.01},
+)
+
+print(result.summary_metrics)
+print(result.output_dir)
+```
+
+Before fitting, HeteroDecomp prints detected shapes, headers, index columns, missing
+values, constant columns, symmetry, and a recommended truncation length when
+time series differ in duration. Use explicit `header=` and `index=` arguments
+to override conservative automatic detection.
+
+By default, outputs are saved beside the input directory in separate `shared`,
+`individual`, `reconstruction`, and `residual` folders. Per-item metrics,
+summary metrics, the data audit, and model metadata are saved with them.
+
+## Functional-connectivity matrices
+
+```python
+result = decompose(
+    r"D:\data\fc",
+    kind="matrix",
+    algorithm="perpca",
+    shared_rank=10,
+    individual_rank=3,
+    output_format="xlsx",
+)
+```
+
+If every input is square and symmetric within tolerance, every saved shared and
+individual FC component is explicitly symmetrized and keeps its detected row
+and column labels.
+
+## Images
+
+```python
+result = decompose(
+    r"D:\data\frames",
+    kind="image",
+    algorithm="perpca",
+    shared_rank=5,
+    individual_rank=20,
+    image_format="png",
+)
+```
+
+PNG previews are accompanied by `exact_components.npz`, which preserves signed
+individual and residual arrays without visualization clipping.
+
+## Simulated ground truth
+
+```python
+from heterodecomp import evaluate_ground_truth
+
+metrics = evaluate_ground_truth(
+    result,
+    r"D:\data\shared_signal",
+    r"D:\data\individual_signal",
+)
+```
+
+Ground-truth recovery metrics are kept separate from real-data metrics so that
+recovery claims cannot accidentally be made for empirical datasets.
+
+## P300 validation
+
+```python
+from heterodecomp import prepare_p300, validate_p300
+
+prepared = prepare_p300(r"D:\data\P300")
+validation = validate_p300(prepared, shared_rank=5, individual_rank=2)
+print(validation.pearson_r, validation.permutation_p)
+```
+
+P300 validation matches the recovered shared spatial basis to the group target
+topography, applies a maximum-component channel-label permutation test, and
+reports target/non-target projection effects and peak latency.
+
+## Algorithms
+
+`perpca`, `hmf`, `jive`, `robust_jive`, `rajive`, `slide`, `pertucker`,
+`percdl`, and `robust_pca` share one interface. Algorithm-specific settings are
+passed through `params`; see each adapter in `heterodecomp/_engine/models` for the
+accepted options.
+
+All algorithms print interpretable quality metrics approximately every 1% of
+the configured iterations (`epochs=300` prints every 3 iterations), including
+explained variance, reconstruction correlation, residual energy, and—where
+available—shared/individual energy allocation. Internal optimizer losses are
+not printed. Runs shorter than 100 iterations print every iteration. Pass
+`params={"progress": False}` to disable progress. RaJIVE has no epoch loop, so
+it reports the equivalent block and decomposition stages instead.
+
+Complete runnable examples for every algorithm are in
+[`examples/README.md`](examples/README.md).
+
+## Test
+
+```bash
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```

heterodecomp-0.1.0/README.md

@@ -0,0 +1,133 @@
+# HeteroDecomp
+
+HeteroDecomp separates repeated data items into shared, individual-specific, and
+residual patterns. It accepts time-series tables (BOLD, EEG, and similar
+signals), general matrices (including symmetric FC matrices), and common image
+formats.
+
+## Install for development
+
+```bash
+python -m pip install -e .
+```
+
+Install the optional EEG reader for MNE FIF files:
+
+```bash
+python -m pip install -e ".[eeg]"
+```
+
+## Basic API
+
+```python
+from heterodecomp import decompose
+
+result = decompose(
+    r"D:\data\bold",
+    kind="timeseries",
+    algorithm="perpca",
+    shared_rank=5,
+    individual_rank=2,
+    params={"epochs": 200, "lr": 0.01},
+)
+
+print(result.summary_metrics)
+print(result.output_dir)
+```
+
+Before fitting, HeteroDecomp prints detected shapes, headers, index columns, missing
+values, constant columns, symmetry, and a recommended truncation length when
+time series differ in duration. Use explicit `header=` and `index=` arguments
+to override conservative automatic detection.
+
+By default, outputs are saved beside the input directory in separate `shared`,
+`individual`, `reconstruction`, and `residual` folders. Per-item metrics,
+summary metrics, the data audit, and model metadata are saved with them.
+
+## Functional-connectivity matrices
+
+```python
+result = decompose(
+    r"D:\data\fc",
+    kind="matrix",
+    algorithm="perpca",
+    shared_rank=10,
+    individual_rank=3,
+    output_format="xlsx",
+)
+```
+
+If every input is square and symmetric within tolerance, every saved shared and
+individual FC component is explicitly symmetrized and keeps its detected row
+and column labels.
+
+## Images
+
+```python
+result = decompose(
+    r"D:\data\frames",
+    kind="image",
+    algorithm="perpca",
+    shared_rank=5,
+    individual_rank=20,
+    image_format="png",
+)
+```
+
+PNG previews are accompanied by `exact_components.npz`, which preserves signed
+individual and residual arrays without visualization clipping.
+
+## Simulated ground truth
+
+```python
+from heterodecomp import evaluate_ground_truth
+
+metrics = evaluate_ground_truth(
+    result,
+    r"D:\data\shared_signal",
+    r"D:\data\individual_signal",
+)
+```
+
+Ground-truth recovery metrics are kept separate from real-data metrics so that
+recovery claims cannot accidentally be made for empirical datasets.
+
+## P300 validation
+
+```python
+from heterodecomp import prepare_p300, validate_p300
+
+prepared = prepare_p300(r"D:\data\P300")
+validation = validate_p300(prepared, shared_rank=5, individual_rank=2)
+print(validation.pearson_r, validation.permutation_p)
+```
+
+P300 validation matches the recovered shared spatial basis to the group target
+topography, applies a maximum-component channel-label permutation test, and
+reports target/non-target projection effects and peak latency.
+
+## Algorithms
+
+`perpca`, `hmf`, `jive`, `robust_jive`, `rajive`, `slide`, `pertucker`,
+`percdl`, and `robust_pca` share one interface. Algorithm-specific settings are
+passed through `params`; see each adapter in `heterodecomp/_engine/models` for the
+accepted options.
+
+All algorithms print interpretable quality metrics approximately every 1% of
+the configured iterations (`epochs=300` prints every 3 iterations), including
+explained variance, reconstruction correlation, residual energy, and—where
+available—shared/individual energy allocation. Internal optimizer losses are
+not printed. Runs shorter than 100 iterations print every iteration. Pass
+`params={"progress": False}` to disable progress. RaJIVE has no epoch loop, so
+it reports the equivalent block and decomposition stages instead.
+
+Complete runnable examples for every algorithm are in
+[`examples/README.md`](examples/README.md).
+
+## Test
+
+```bash
+python -m unittest discover -s tests -v
+python -m build
+python -m twine check dist/*
+```

heterodecomp-0.1.0/examples/01_perpca.py

@@ -0,0 +1,40 @@
+"""Detailed PerPCA example for BOLD time-series matrices.
+
+PerPCA is the recommended default when the goal is an explicit shared feature
+subspace plus an orthogonal subject-specific subspace.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "perpca"
+
+PARAMS = {
+    "epochs": 200,  # Number of distributed covariance-gradient iterations.
+    "lr": 0.01,  # Initial manifold-gradient step size.
+    "progress": True,  # Print interpretable quality metrics every ~1%.
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="perpca",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,  # Use None for every subject.
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,  # Set both truth paths to None for real data.
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/02_hmf.py

@@ -0,0 +1,45 @@
+"""Detailed HMF example for shared/individual BOLD decomposition.
+
+HMF uses separate global and local matrix factors and is useful when accurate
+reconstruction is more important than strict projection-only components.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "hmf"
+
+PARAMS = {
+    "epochs": 100,
+    "lr": 0.001,
+    "beta": 0.1,  # Coupling strength for the shared factors.
+    "wd": 0.0,  # Optimizer weight decay.
+    "optim": "SGD",  # The vendored implementation also accepts Adam.
+    "epsilon": 0.0,  # Set above zero to enable convergence stopping.
+    "device": "cpu",  # Change to "cuda" when a compatible GPU is available.
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="hmf",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/03_jive.py

@@ -0,0 +1,36 @@
+"""Detailed JIVE example for joint and individual variation."""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "jive"
+
+PARAMS = {
+    "epochs": 100,  # Alternating joint/individual update iterations.
+    "device": "cpu",
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="jive",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/04_robust_jive.py

@@ -0,0 +1,38 @@
+"""Detailed RobustJIVE example with an explicit sparse-error component."""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "robust_jive"
+
+PARAMS = {
+    "epochs": 100,
+    "mu": 10.0,  # Augmented-Lagrangian penalty.
+    "lbd": 0.01,  # Sparse-error regularization strength.
+    "device": "cpu",
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="robust_jive",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/05_rajive.py

@@ -0,0 +1,44 @@
+"""Detailed angle-based robust JIVE (RaJIVE) example.
+
+RaJIVE estimates joint structure using resampled Wedin and random-direction
+bounds. Its sampling controls trade runtime for rank-selection stability.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "rajive"
+
+PARAMS = {
+    "n_wedin_samples": 100,
+    "n_rand_dir_samples": 100,
+    "joint_rank": 3,  # Set to None only when automatic selection is desired.
+    "robust_niter": 100,
+    "robust_tol": 1e-5,
+    "use_hmf_variant": False,
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="rajive",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/06_slide.py

@@ -0,0 +1,43 @@
+"""Detailed SLIDE example with a fixed shared/individual structure.
+
+The default avoids expensive bi-cross-validation and constructs a structure
+from the requested ranks. Enable ``use_bcv`` for data-driven structure search.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "slide"
+
+PARAMS = {
+    "use_bcv": False,
+    "center": True,
+    "k_max": 1000,
+    "eps": 1e-6,
+    "progress": True,
+    # BCV-only controls: n_lambda, lambda_min, n_fold, p_fold, ratio_max.
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="slide",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/07_pertucker.py

@@ -0,0 +1,43 @@
+"""Detailed Personalized Tucker decomposition example.
+
+Each 2-D input is represented as a small tensor internally. This method is most
+useful when multilinear row and column structure is scientifically meaningful.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "pertucker"
+
+PARAMS = {
+    "max_itr": 100,
+    "tol": 1e-8,
+    "rho": 0.0,  # Optional local-factor regularization.
+    "init_method": "random",  # Supported by the vendored PerTucker solver.
+    "orthogonal": True,
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="pertucker",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/08_percdl.py

@@ -0,0 +1,43 @@
+"""Detailed personalized convolutional dictionary learning example.
+
+PerCDL is specialized for one-dimensional time series. Each feature/ROI is
+treated as a signal; it should not be the first choice for FC matrices/images.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "percdl"
+
+PARAMS = {
+    "n_steps": 100,
+    "n_atoms": 3,
+    "atom_length": 24,  # Must be shorter than the aligned time series.
+    "step_size": 1e-3,
+    "sparsity": 0.05,
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="percdl",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )

heterodecomp-0.1.0/examples/09_robust_pca.py

@@ -0,0 +1,42 @@
+"""Detailed robust PCA baseline example.
+
+The adapter fits low-rank plus sparse structure per item, defines the group mean
+low-rank matrix as shared, and treats deviations from it as individual-specific.
+"""
+
+from pathlib import Path
+
+from _common import run_example
+
+
+DATA_ROOT = Path("YOUR_DATA_ROOT")
+DATA_DIR = DATA_ROOT / "BOLD" / "full_signal"
+TRUE_SHARED_DIR = DATA_ROOT / "BOLD" / "shared_signal"
+TRUE_INDIVIDUAL_DIR = DATA_ROOT / "BOLD" / "individual_signal"
+OUTPUT_DIR = Path(__file__).resolve().parents[1] / "example_outputs" / "robust_pca"
+
+PARAMS = {
+    "outer_epochs": 100,
+    "lbd_s_outer": 0.02,  # Sparse-component shrinkage.
+    "rho": 0.95,  # Continuation factor used by the robust solver.
+    "device": "cpu",
+    "progress": True,
+}
+
+
+if __name__ == "__main__":
+    run_example(
+        algorithm="robust_pca",
+        params=PARAMS,
+        data_dir=DATA_DIR,
+        data_kind="timeseries",
+        pattern="*.csv",
+        max_items=10,
+        shared_rank=3,
+        individual_rank=3,
+        target_length=150,
+        scaling="zscore",
+        output_dir=OUTPUT_DIR,
+        true_shared_dir=TRUE_SHARED_DIR,
+        true_individual_dir=TRUE_INDIVIDUAL_DIR,
+    )