Enhance documentation and implement quality checks for parameter uniqueness and sparsity analysis

- Updated global development instructions to include output structure and reproducibility goals.
- Modified example configuration for DSI Studio to correct command path.
- Added functions for computing sparsity and sparsity scores in analysis_monolith.py.
- Expanded test suite to include regression tests for sparsity scoring and CLI behavior.
- Centralized quality checks into a unified script with subcommands for quick checks and uniqueness analysis.
- Updated install script to support optional experimental requirements installation.
- Refactored quick_quality_check.py and verify_parameter_uniqueness.py to delegate functionality to quality_checks.py.

Author: karl-koschutnig

.github/instructions/global.md.instructions.md

@@ -1,5 +1,15 @@
 # Global Development Instructions
 
+# Purpose
+- takes preprocessed fib files 
+- generates connectivity matrices using DSI Studio
+- uses a wide spectrum of parameters
+- outputs matrices in a structured directory format
+- ensures reproducibility and consistency across runs
+- weight each parameter combination to get a qa score
+- use cross-validation to find optimal parameter sets
+- give user BEST parameter sets for their data (THAT'S THE GOAL!)
+
 ## Package Management
 - **All packages MUST be installed via `install.sh`** - never install packages manually
 - **All installations MUST occur within the virtual environment** - no global installations

dsi_studio_tools/example_config.json

@@ -1,7 +1,7 @@
 {
   "comment": "Example configuration for connectivity matrix extraction",
 
-  "dsi_studio_cmd": "/data/local/software/dsi-studio/dsi_studio",
+  "dsi_studio_cmd": "/Applications/dsi_studio.app/Contents/MacOS/dsi_studio",
 
   "atlases": [
     "ATAG_basal_ganglia",

experimental/monolith_refactor/analysis_monolith.py

@@ -17,6 +17,7 @@
 import sys
 import json
 from pathlib import Path
+import numpy as np
 
 HAS_DEPS = True
 try:
@@ -28,6 +29,39 @@
     HAS_DEPS = False
 
 
+def compute_sparsity_from_matrix(matrix: np.ndarray) -> float:
+    """Compute network sparsity as proportion of zero off-diagonal elements.
+
+    Returns a float in [0,1].
+    """
+    if matrix.ndim != 2 or matrix.shape[0] != matrix.shape[1]:
+        raise ValueError("matrix must be square")
+    n = matrix.shape[0]
+    mask = ~np.eye(n, dtype=bool)
+    off = matrix[mask]
+    zeros = np.sum(off == 0)
+    return float(zeros) / float(off.size)
+
+
+def compute_sparsity_score_generic(sparsity_values: np.ndarray, min_sparsity: float = 0.05, max_sparsity: float = 0.4) -> np.ndarray:
+    """Compute sparsity quality scores as in MetricOptimizer.compute_sparsity_score.
+
+    Uses the same heuristic: values near center of [min,max] get score ~1, outside range penalized.
+    """
+    sparsity_values = np.array(sparsity_values, dtype=float)
+    min_s, max_s = float(min_sparsity), float(max_sparsity)
+    optimal = (min_s + max_s) / 2.0
+    width = max_s - min_s
+    distance = np.abs(sparsity_values - optimal)
+    # Avoid division by zero
+    denom = (width / 2.0) if width != 0 else 1.0
+    normalized = distance / denom
+    scores = np.maximum(0.0, 1.0 - normalized)
+    out_of_range = (sparsity_values < min_s) | (sparsity_values > max_s)
+    scores[out_of_range] = scores[out_of_range] * 0.1
+    return scores
+
+
 def do_score(args: argparse.Namespace) -> int:
     print("\n[monolith] SCORE\u001b[0m")
     print(f"Input: {args.input}")

experimental/monolith_refactor/tests/test_smoke.py

@@ -17,3 +17,159 @@ def test_monolith_dry_run_compare():
     res = subprocess.run(cmd, capture_output=True, text=True)
     print(res.stdout)
     assert res.returncode == 0
+
+
+def test_sparsity_score_regression():
+    # Load sample adjacency
+    import numpy as _np
+    from pathlib import Path as _P
+    csv = _P(__file__).resolve().parents[1] / 'data' / 'sample_adj.csv'
+    mat = _np.loadtxt(str(csv), delimiter=',')
+    # Compute sparsity using POC helper via subprocess import
+    script = _P(__file__).resolve().parents[1] / 'analysis_monolith.py'
+    # Direct import from the script to call helper
+    import importlib.util as _spec
+    spec = _spec.spec_from_file_location('analysis_monolith', str(script))
+    mod = _spec.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    sparsity = mod.compute_sparsity_from_matrix(mat)
+    assert abs(sparsity - 0.3333333333333333) < 1e-6
+    # If MetricOptimizer available, compare scores
+    try:
+        from scripts.metric_optimizer import MetricOptimizer
+        mo = MetricOptimizer()
+        # MetricOptimizer expects arrays; compute score using its method
+        svals = _np.array([sparsity])
+        mo_scores = mo.compute_sparsity_score(svals)
+        poc_scores = mod.compute_sparsity_score_generic(svals)
+        assert abs(float(mo_scores[0]) - float(poc_scores[0])) < 1e-6
+    except Exception:
+        # If MetricOptimizer isn't available in imports, at least verify poc scoring produces expected shape
+        svals = _np.array([sparsity])
+        poc_scores = mod.compute_sparsity_score_generic(svals)
+        assert poc_scores.shape == (1,)
+
+
+def test_cli_prints_help_on_no_args():
+    script = Path(__file__).resolve().parents[1] / 'analysis_monolith.py'
+    # Running with no args should print help and exit 0
+    res = subprocess.run([sys.executable, str(script)], capture_output=True, text=True)
+    print(res.stdout)
+    assert res.returncode == 0
+    assert ('usage' in res.stdout.lower()) or ('experimental monolith' in res.stdout.lower()) or ('analysis_monolith' in res.stdout)
+
+
+import pytest
+
+
+@pytest.mark.parametrize('vals', [
+    [0.01, 0.1, 0.2, 0.3],
+    [0.05, 0.15, 0.35, 0.5],
+    [0.0, 0.4, 0.6]
+])
+def test_vectorized_sparsity_scores(vals):
+    """Compare vectorized sparsity scoring between POC helper and MetricOptimizer when available."""
+    import numpy as _np
+    from importlib import util as _spec
+    script = Path(__file__).resolve().parents[1] / 'analysis_monolith.py'
+    spec = _spec.spec_from_file_location('analysis_monolith', str(script))
+    mod = _spec.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    arr = _np.array(vals, dtype=float)
+    poc = mod.compute_sparsity_score_generic(arr)
+    try:
+        from scripts.metric_optimizer import MetricOptimizer
+        mo = MetricOptimizer()
+        mo_scores = mo.compute_sparsity_score(arr)
+        # Allow small numerical tolerance
+        assert _np.allclose(_np.asarray(poc, dtype=float), _np.asarray(mo_scores, dtype=float), atol=1e-6)
+    except Exception:
+        # If MetricOptimizer not importable, ensure POC returns sensible numbers in [0,1]
+        assert _np.all((poc >= 0.0) & (poc <= 1.0))
+
+
+def test_matrix_sparsity_and_score_various():
+    """Generate small matrices with controlled sparsity and check scoring behaviour."""
+    import numpy as _np
+    from importlib import util as _spec
+    script = Path(__file__).resolve().parents[1] / 'analysis_monolith.py'
+    spec = _spec.spec_from_file_location('analysis_monolith', str(script))
+    mod = _spec.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    # Create matrices 3x3 with varying off-diagonal zeros
+    mats = []
+    # fully connected (no zeros off-diag)
+    mats.append(_np.array([[0,1,1],[1,0,1],[1,1,0]]))
+    # one zero off-diag
+    mats.append(_np.array([[0,1,0],[1,0,1],[0,1,0]]))
+    # many zeros (sparse)
+    mats.append(_np.array([[0,0,0],[0,0,1],[0,1,0]]))
+
+    sparsities = [round(mod.compute_sparsity_from_matrix(m), 6) for m in mats]
+    # Basic sanity: sparsity values should be between 0 and 1 and increase with more zeros
+    assert all(0.0 <= s <= 1.0 for s in sparsities)
+    assert sparsities[0] < sparsities[1] < sparsities[2]
+
+    # Check scoring produces array same length
+    arr = _np.array(sparsities)
+    scores = mod.compute_sparsity_score_generic(arr)
+    assert scores.shape == arr.shape
+
+
+    def test_regression_grid_sparsity_scores():
+        """Compare scoring vectors over a grid of sparsity values and synthetic matrices."""
+        import numpy as _np
+        from importlib import util as _spec
+        script = Path(__file__).resolve().parents[1] / 'analysis_monolith.py'
+        spec = _spec.spec_from_file_location('analysis_monolith', str(script))
+        mod = _spec.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+        # Generate grid of sparsity values
+        grid = _np.linspace(0.0, 1.0, 21)
+        poc_scores = mod.compute_sparsity_score_generic(grid)
+        try:
+            from scripts.metric_optimizer import MetricOptimizer
+            mo = MetricOptimizer()
+            mo_scores = mo.compute_sparsity_score(grid)
+            # Compare full vectors
+            assert _np.allclose(_np.asarray(poc_scores, dtype=float), _np.asarray(mo_scores, dtype=float), atol=1e-6)
+        except Exception:
+            # If MetricOptimizer not importable, check shape and range
+            assert poc_scores.shape == grid.shape
+            assert _np.all((poc_scores >= 0.0) & (poc_scores <= 1.0))
+
+    def test_regression_synthetic_matrices():
+        """Create a set of synthetic matrices, compute sparsity and compare scoring vectors."""
+        import numpy as _np
+        from importlib import util as _spec
+        script = Path(__file__).resolve().parents[1] / 'analysis_monolith.py'
+        spec = _spec.spec_from_file_location('analysis_monolith', str(script))
+        mod = _spec.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+
+        # Create synthetic matrices of size 4x4 with varying sparsity
+        mats = []
+        # Fully connected
+        mats.append(_np.ones((4,4)) - _np.eye(4))
+        # Half zeros off-diag
+        m = _np.ones((4,4)) - _np.eye(4)
+        m[0,1] = m[1,2] = m[2,3] = m[3,0] = 0
+        mats.append(m)
+        # Mostly zeros
+        m = _np.zeros((4,4))
+        m[0,3] = m[1,2] = m[2,1] = m[3,0] = 1
+        mats.append(m)
+
+        sparsities = [_np.round(mod.compute_sparsity_from_matrix(mat), 6) for mat in mats]
+        arr = _np.array(sparsities)
+        poc_scores = mod.compute_sparsity_score_generic(arr)
+        try:
+            from scripts.metric_optimizer import MetricOptimizer
+            mo = MetricOptimizer()
+            mo_scores = mo.compute_sparsity_score(arr)
+            assert _np.allclose(_np.asarray(poc_scores, dtype=float), _np.asarray(mo_scores, dtype=float), atol=1e-6)
+        except Exception:
+            assert poc_scores.shape == arr.shape
+            assert _np.all((poc_scores >= 0.0) & (poc_scores <= 1.0))

install.sh

@@ -119,3 +119,22 @@ echo -e "${YELLOW}📋 To deactivate the environment:${NC}"
 echo "  deactivate"
 echo ""
 echo -e "${GREEN}🚀 Environment ready for braingraph pipeline!${NC}"
+
+# Optional experimental extras
+# Install experimental dev requirements when INSTALL_EXPERIMENTAL=1 is set.
+# This keeps all installs centralized in install.sh as requested by global instructions.
+if [ "${INSTALL_EXPERIMENTAL:-0}" = "1" ]; then
+    echo -e "\n${BLUE}🧪 Installing experimental extras...${NC}"
+    if [ -f "experimental/monolith_refactor/requirements.txt" ]; then
+        echo -e "${BLUE}🔧 Installing experimental requirements from experimental/monolith_refactor/requirements.txt${NC}"
+        # Ensure pip exists in the venv (some venvs may not have pip bootstrapped)
+        python -m ensurepip --upgrade || true
+        python -m pip install --upgrade pip setuptools wheel || true
+        # Best-effort: use python -m pip inside venv
+        python -m pip install -r experimental/monolith_refactor/requirements.txt || {
+            echo -e "${YELLOW}⚠️  Failed to install experimental requirements. Continuing without them.${NC}"
+        }
+    else
+        echo -e "${YELLOW}⚠️  No experimental requirements file found; skipping.${NC}"
+    fi
+fi