fscpy 2.0.0__tar.gz → 2.0.2__tar.gz

{fscpy-2.0.0 → fscpy-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fscpy
-Version: 2.0.0
+Version: 2.0.2
 Summary: Function-structure coupling on parcellation and FOD-derived voxel graphs
 Author: Viljami Sairanen
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -699,8 +699,8 @@ Dynamic: license-file
 
 The Python package is imported as `fsc` and provides two workflows:
 
-- **Parcellation FSC:** a structural connectivity (SC) matrix and a functional connectivity (FC) matrix produce a symmetric matrix of structural-edge support. Relevant publication for this version is the Network Neuroscience paper 10.1162/NETN.a.589.
-- **Voxelwise FSC:** a spherical-harmonic fibre orientation distribution (FOD) defines a weighted white-matter voxel graph. One supernode per functional parcel connects to neighbouring white-matter voxels through FOD-supported interfaces. The output is a voxelwise map of white-matter edge support. This version is explained in the Aperture Neuro paper 10.52294/001c.172225.
+- **Parcellation FSC:** a structural connectivity (SC) matrix and a functional connectivity (FC) matrix produce a symmetric matrix of structural-edge support. Related publication: the Network Neuroscience paper [doi:10.1162/NETN.a.589](https://doi.org/10.1162/NETN.a.589). The paper's joint formulation is available as `method="joint"` for FC without cycles, and a pairwise variant for dense FC is the default; see [Relation to the publications](#relation-to-the-publications).
+- **Voxelwise FSC:** a spherical-harmonic fibre orientation distribution (FOD) defines a weighted white-matter voxel graph. One supernode per functional parcel connects to neighbouring white-matter voxels through FOD-supported interfaces. The output is a voxelwise map of white-matter edge support. This version is explained in the Aperture Neuro paper [doi:10.52294/001c.172225](https://doi.org/10.52294/001c.172225).
 
 These workflows use different structural graphs, so their numerical outputs are **not interchangeable**.
 
@@ -719,7 +719,6 @@ On Windows PowerShell, use double quotes around extras, for example `python -m p
 
 The ENIGMA example also requires the external [ENIGMA Toolbox](https://github.com/MICA-MNI/ENIGMA), which is not a dependency of FSC. Please, refer to their installation instructions if needed.
 
-
 ## Examples
 
 The scripts run from the repository root after installation:
@@ -730,7 +729,7 @@ The scripts run from the repository root after installation:
 | `python examples/enigma.py` | ENIGMA Toolbox's included HCP SC and FC matrices | Side-by-side SC, FC and FSC heatmaps |
 | `python examples/voxel.py` | Generated synthetic SH FOD and two parcel voxels | A small 3D white-matter support map |
 
-The synthetic voxel example requires `.[voxel]` but **no downloaded MRI data**. It constructs an x-oriented FOD bundle, attaches two functional ROI supernodes and evaluates the resulting support. The ENIGMA example follows the bundled cortical connectivity matrices returned by `load_sc()` and `load_fc()`.
+The synthetic voxel example requires `.[voxel]` but **no downloaded MRI data**. It constructs an x-oriented FOD bundle in the MRtrix3 SH convention, attaches two functional ROI supernodes and evaluates the resulting support. The ENIGMA example follows the bundled cortical connectivity matrices returned by `load_sc()` and `load_fc()`.
 
 ### Parcellation workflow
 
@@ -753,7 +752,50 @@ support = fsc.solve_from_parcellations(sc, fc)
 print(support)
 ```
 
-`solve_from_parcellations()` returns the **symmetric support matrix**, not an `FSCResult` object. In this example, the only structural path connecting parcels 1 and 4 is 1–0–2–4. Its three unit-conductance edges each carry support `1/3`; the side branch 2–3 carries zero current.
+`solve_from_parcellations()` returns the **symmetric support matrix**, not an `FSCResult` object. In this example, the only structural path connecting parcels 1 and 4 is 1–0–2–4. Its three unit-conductance edges each carry support `1/3` and the side branch 2–3 carries zero current.
+
+FC must be square and symmetric. Only finite, positive values above the diagonal are used. Negative, zero and non-finite values are ignored. The papers used Fisher *z*-transformed FC. The fscpy uses whatever values it is given. The output scales linearly with the FC magnitudes.
+
+`solve_from_parcellations()` has two methods:
+
+- `method="pairwise"` (default) solves each FC pair separately and sums the absolute edge currents. It works for any FC matrix.
+- `method="joint"` solves all FC constraints in one modified-nodal-analysis system as in the Network Neuroscience paper (Eq. 11). Returns absolute edge currents. Requires the FC pairs to contain no cycles, e.g. a set of disjoint pairs like the FiberCup example. Otherwise, error is raised. Three regions with positive FC between all of them already form a cycle. So, a dense FC matrix has likely no exact joint solution.
+
+```python
+fc = np.zeros((5, 5))
+fc[1, 4] = fc[4, 1] = 1
+fc[3, 4] = fc[4, 3] = 1      # two pairs sharing node 4: no cycle
+
+joint = fsc.solve_from_parcellations(sc, fc, method="joint")
+pairwise = fsc.solve_from_parcellations(sc, fc)   # different for several pairs
+```
+
+The two methods agree for a single FC pair and generally differ for several, because the joint solve combines the constraints in one potential field while the pairwise method sums the magnitudes of separate solutions.
+
+#### Mapping support to streamlines
+
+The support matrix can be mapped back onto a tractogram so that each streamline gets a weight for visualisation, filtering, or analyses. The SC matrix does not have to come from fscpy. Any tool that writes a per-streamline parcel assignment, such as MRtrix3 `tck2connectome -out_assignments`, works.
+
+```python
+from fsc.parcellation import streamline_support
+
+assignments = np.loadtxt("assignments.txt", dtype=int)  # two parcel labels per streamline
+weights = np.loadtxt("sift2_weights.txt")               # optional, see below
+
+values = streamline_support(support, assignments, weights)
+np.savetxt("fsc_streamline_weights.txt", values)        # one value per streamline, input order
+```
+
+The support of each parcel pair is split among the streamlines connecting that pair in proportion to their weights. So the values of each pair's streamlines sum to `support[a, b]`. This holds for both methods and for SC from any source or normalisation. Only the relative weights within a pair matter.
+
+Requirements:
+
+- **Assignments:** exactly two labels per streamline, numbered from 1 in SC matrix order, with 0 for an unassigned endpoint. This is the default `tck2connectome -out_assignments` format. Options that write more labels per streamline (e.g. `-assignment_all_voxels`), or that add a row for node 0 to the matrix (`-keep_unassigned`) break this correspondence!
+- **Weights:** use the per-streamline weights the SC was built from. Omit them for streamline counts, pass the SIFT2 weights file if the SC used `-tck_weights_in`, or `1 / length` for length-scaled SC. Non-finite or non-positive weights mark a streamline as invalid.
+- **Output:** one non-negative value per input streamline, in input order. Unassigned, invalid and self-connecting streamlines get 0. If the SC has an edge with no streamline in `assignments`, that edge's support is not mapped.
+
+For signed streamline currents from a potential vector computed with `fsc.solve_fsc()`, use `streamline_currents()`. If SC is built inside fscpy from streamline resistances, use `sc_from_streamlines()`.
+
 
 ### Voxel workflow
 
@@ -783,15 +825,40 @@ support = sum_pairwise_support(
 nib.save(nib.Nifti1Image(support, fod_image.affine), 'fsc_support.nii.gz')
 ```
 
-`labels_in_fod_space()` uses nearest-neighbour resampling and assumes the images are **already spatially registered**. It does not register images or reorient SH coefficients. By default, the FOD coefficient convention is DIPY's `tournier07` basis with `legacy=True`; the supplied image must use the matching convention. An optional `wm_mask` can further restrict graph voxels; the FOD-norm threshold is still applied. ROI voxels must have positive labels, lie outside the selected WM voxel graph, and have FOD-supported WM contacts.
+#### Input conventions
 
-The voxel workflow applies each finite, nonzero FC pair **independently in the mathematical model**. For efficiency, the implementation solves reusable grounded-Laplacian basis fields relative to one ROI per connected component, then reconstructs pair solutions. It accumulates **absolute** structural currents. Voxel support sums currents on **WM–WM edges only**, excluding ROI-supernode interface edges. Pairs without a structural path contribute zero. Specify `pairs=[(0, 1)]` to select one pair by zero-based FC matrix indices.
+- **SH basis.** The FOD image must contain SH coefficients in the MRtrix3 convention, as written by `dwi2fod`. This is DIPY's `tournier07` basis with `legacy=False`, which is the default. FODs in the older MRtrix 0.2 convention need `legacy=True`.
+  Since version 2.0.2 the default is `legacy=False`; earlier versions defaulted to `legacy=True`. Pass `legacy=True` explicitly to reproduce results from those versions.
+- **Same settings in both calls.** Pass identical `sphere`, `basis`, `legacy`, `kappa`, `kernel_power` and `orientation_floor` values to `graph_from_fod()` and `add_roi_nodes()`. They are not cross-checked.
+- **Frame.** Neighbour directions are computed in world coordinates from the image affine, so the SH coefficients must be defined in that same frame, as MRtrix3 does. The image must have a correct affine.
+- **Registration.** `labels_in_fod_space()` uses nearest-neighbour resampling and assumes the images are **already spatially registered**. It does not register images or reorient SH coefficients.
+- **Masks.** An optional `wm_mask` restricts graph voxels and an optional `exclusion_mask` removes voxels. The FOD-norm threshold is always applied in addition to `wm_mask`.
+- **ROIs.** ROI voxels must have positive labels, lie outside the selected WM voxel graph, and every ROI must have at least one FOD-supported WM contact, otherwise `add_roi_nodes()` raises an error. An optional `tissue_mask` excludes non-tissue ROI voxels.
+
+#### How the graph is built
+
+- **Nodes.** Voxels whose SH coefficient vector has a Euclidean norm above `fod_norm_threshold` (default 0.25), inside `wm_mask` if given. This threshold depends on the FOD intensity scale, so check it against your FOD normalisation.
+- **Edges.** Each voxel is connected to its 26 neighbours (13 unique directions). The conductance of an interface is `sqrt(s_i · s_j) / ℓ`, where `ℓ` is the physical distance between voxel centres and `s` is the directional support of each endpoint. Interfaces below `min_conductance` (default 1e-12) are dropped.
+- **Directional support.** The FOD amplitude along the interface direction is evaluated with an angular averaging kernel, with weights proportional to `exp(κ·|cos θ|^p)` over the sampling sphere (default `repulsion724`, `kappa=8`, `kernel_power=2`). It is clipped at zero after averaging, reduced by `orientation_floor` times the mean positive FOD amplitude of the voxel, and clipped at zero again. This kernel averaging is an implementation detail: the papers evaluate the FOD directly along the interface direction.
+- **ROI supernodes.** Each ROI is a graph node. Labelled voxels outside the WM graph are ROI tissue. Each one touches the WM graph through its six face neighbours. The conductance of a contact is `interface_scale` times the *WM voxel's* directional support along the face normal, divided by the voxel size. Diagonal contacts are not used, and support is taken from the WM side only. All ROI supernodes are present in the graph when any pair is solved.
+- **Support map.** Voxel support is the sum of absolute currents on the WM–WM edges incident to a voxel, accumulated over all FC pairs. ROI–WM interface edges are excluded.
+
+#### Solving
+
+The voxel workflow applies each finite, positive FC pair **independently in the mathematical model**. For efficiency, the implementation solves reusable grounded-Laplacian basis fields relative to one ROI per connected component, then reconstructs pair solutions. It accumulates **absolute** structural currents. Pairs without a structural path contribute zero. Specify `pairs=[(0, 1)]` to select one pair by zero-based FC matrix indices.
+
+`solver` can be `'auto'`, `'cg'` or `'direct'`; the default `rtol` is `1e-4`. Each solution is checked for current conservation, and the check is relative to the injected current, so it does not depend on the scale of the conductances. One potential field is stored per active ROI, and run time grows with the number of FC pairs.
 
 ## Numerical interpretation
 
-In both workflows, nonzero FC magnitudes define imposed potential differences and negative FC values are treated using `abs(FC)`. SC values and FOD interface weights act as conductances, **not lengths or resistances**. FSC reports how the weighted structural graph supports the imposed correlations; it is not a direct measurement of axonal traffic or a uniquely determined anatomical tract.
+In both workflows, only positive FC values define imposed potential differences. Negative values are ignored. SC values and FOD interface weights act as conductances, **not lengths or resistances**. FSC reports how the weighted structural graph supports the imposed correlations. It is not a direct measurement of axonal traffic or a uniquely determined anatomical tract.
+
+The low-level `fsc.solve_fsc()` interface solves **simultaneous** functional constraints through modified nodal analysis and returns an `FSCResult` (potentials, currents and residual diagnostics). The constraints must be mutually compatible. The imposed potential differences must sum to zero around every cycle of constrained pairs. Constraints without cycles, e.g. the FiberCup experiment, always satisfy this. Whereas a dense FC matrix likely does not because it imposes far more potential differences than the graph has free potentials. `solve_from_parcellations(..., method="joint")` wraps this interface and checks for cycles before solving. For dense FC, use `solve_from_parcellations()` with the default `method="pairwise"`, or `solve_fsc_voxel()`, which evaluate FC pairs separately and sum their absolute structural-edge currents.
+
+## Relation to the publications
 
-The low-level `fsc.solve_fsc()` interface solves **simultaneous** functional constraints through modified nodal analysis and returns an `FSCResult` (potentials, currents and residual diagnostics). This is distinct from `solve_from_parcellations()` and `solve_fsc_voxel()`, which evaluate FC pairs separately and sum their absolute structural-edge currents.
+- **Network Neuroscience (parcellation workflow).** The paper formulates FSC as one joint modified-nodal-analysis system (Eq. 11), with all constraints solved together. `solve_from_parcellations(..., method="joint")` implements it for FC pairs without cycles like in the FiberCup specificity test. When FC pairs form cycles, as many dense FC matrices, the constraints cannot all hold at once andthe joint system has no exact solution. For such inputs use the default `method="pairwise"`, which solves each pair separately and sums absolute currents. The two methods agree for a single constraint.
+- **Aperture Neuro (voxel workflow).** The Methods describe imposing each selected FC value separately and accumulating the resulting current magnitudes, which is what `sum_pairwise_support()` does. The directional-support kernel, the six-face ROI contacts and the 0.25 norm threshold are implementation choices not given in the paper.
 
 ## Tests
 
@@ -801,7 +868,7 @@ Run the small deterministic tests without downloading neuroimaging datasets:
 python -m pytest -q
 ```
 
-The tests cover the five-node analytical solution, general MNA, negative FC, empty FC, ROI-basis accumulation, disconnected ROIs, and WM-only voxel support. An optional synthetic-FOD end-to-end test runs when NiBabel and DIPY are installed.
+The tests cover the five-node analytical solution, general MNA, the joint parcellation method and its rejection of FC with cycles, mapping support to streamlines, negative FC, empty FC, ROI-basis accumulation, disconnected ROIs, WM-only voxel support, and the scale-invariance of the solver's convergence check. Optional tests run when NiBabel and DIPY are installed: a synthetic-FOD end-to-end example, and a check that the default SH basis reproduces amplitudes computed by MRtrix3 (`sh2amp`) from a reference FiberCup FOD stored in `tests/data/`.
 
 ## Research
 

fscpy-2.0.2/README.md

@@ -0,0 +1,190 @@
+# fscpy
+
+**Function–structure coupling (FSC)** maps functional correlations onto the structural connections that can support them. FSC represents structural connectivity as weighted graph conductances, imposes functional connectivity as potential differences, and measures the resulting currents on structural edges.
+
+The Python package is imported as `fsc` and provides two workflows:
+
+- **Parcellation FSC:** a structural connectivity (SC) matrix and a functional connectivity (FC) matrix produce a symmetric matrix of structural-edge support. Related publication: the Network Neuroscience paper [doi:10.1162/NETN.a.589](https://doi.org/10.1162/NETN.a.589). The paper's joint formulation is available as `method="joint"` for FC without cycles, and a pairwise variant for dense FC is the default; see [Relation to the publications](#relation-to-the-publications).
+- **Voxelwise FSC:** a spherical-harmonic fibre orientation distribution (FOD) defines a weighted white-matter voxel graph. One supernode per functional parcel connects to neighbouring white-matter voxels through FOD-supported interfaces. The output is a voxelwise map of white-matter edge support. This version is explained in the Aperture Neuro paper [doi:10.52294/001c.172225](https://doi.org/10.52294/001c.172225).
+
+These workflows use different structural graphs, so their numerical outputs are **not interchangeable**.
+
+## Installation
+
+From the repository directory, preferably in a virtual environment:
+
+```bash
+python -m pip install -e .                  # Parcellation FSC (NumPy, SciPy)
+python -m pip install -e '.[voxel]'          # Also NiBabel and DIPY
+python -m pip install -e '.[test]'           # Run tests with pytest
+python -m pip install -e '.[examples]'       # Matplotlib for the ENIGMA plot
+```
+
+On Windows PowerShell, use double quotes around extras, for example `python -m pip install -e ".[voxel,test,examples]"`.
+
+The ENIGMA example also requires the external [ENIGMA Toolbox](https://github.com/MICA-MNI/ENIGMA), which is not a dependency of FSC. Please, refer to their installation instructions if needed.
+
+## Examples
+
+The scripts run from the repository root after installation:
+
+| Script | Data | Output |
+| --- | --- | --- |
+| `python examples/parcellation.py` | Explicit 5×5 SC and FC matrices | A 5×5 symmetric FSC matrix with a known three-edge path |
+| `python examples/enigma.py` | ENIGMA Toolbox's included HCP SC and FC matrices | Side-by-side SC, FC and FSC heatmaps |
+| `python examples/voxel.py` | Generated synthetic SH FOD and two parcel voxels | A small 3D white-matter support map |
+
+The synthetic voxel example requires `.[voxel]` but **no downloaded MRI data**. It constructs an x-oriented FOD bundle in the MRtrix3 SH convention, attaches two functional ROI supernodes and evaluates the resulting support. The ENIGMA example follows the bundled cortical connectivity matrices returned by `load_sc()` and `load_fc()`.
+
+### Parcellation workflow
+
+```python
+import numpy as np
+import fsc
+
+sc = np.array([
+    [0, 1, 1, 0, 0],
+    [1, 0, 0, 0, 0],
+    [1, 0, 0, 1, 1],
+    [0, 0, 1, 0, 0],
+    [0, 0, 1, 0, 0],
+], dtype=float)
+
+fc = np.zeros((5, 5))
+fc[1, 4] = fc[4, 1] = 1
+
+support = fsc.solve_from_parcellations(sc, fc)
+print(support)
+```
+
+`solve_from_parcellations()` returns the **symmetric support matrix**, not an `FSCResult` object. In this example, the only structural path connecting parcels 1 and 4 is 1–0–2–4. Its three unit-conductance edges each carry support `1/3` and the side branch 2–3 carries zero current.
+
+FC must be square and symmetric. Only finite, positive values above the diagonal are used. Negative, zero and non-finite values are ignored. The papers used Fisher *z*-transformed FC. The fscpy uses whatever values it is given. The output scales linearly with the FC magnitudes.
+
+`solve_from_parcellations()` has two methods:
+
+- `method="pairwise"` (default) solves each FC pair separately and sums the absolute edge currents. It works for any FC matrix.
+- `method="joint"` solves all FC constraints in one modified-nodal-analysis system as in the Network Neuroscience paper (Eq. 11). Returns absolute edge currents. Requires the FC pairs to contain no cycles, e.g. a set of disjoint pairs like the FiberCup example. Otherwise, error is raised. Three regions with positive FC between all of them already form a cycle. So, a dense FC matrix has likely no exact joint solution.
+
+```python
+fc = np.zeros((5, 5))
+fc[1, 4] = fc[4, 1] = 1
+fc[3, 4] = fc[4, 3] = 1      # two pairs sharing node 4: no cycle
+
+joint = fsc.solve_from_parcellations(sc, fc, method="joint")
+pairwise = fsc.solve_from_parcellations(sc, fc)   # different for several pairs
+```
+
+The two methods agree for a single FC pair and generally differ for several, because the joint solve combines the constraints in one potential field while the pairwise method sums the magnitudes of separate solutions.
+
+#### Mapping support to streamlines
+
+The support matrix can be mapped back onto a tractogram so that each streamline gets a weight for visualisation, filtering, or analyses. The SC matrix does not have to come from fscpy. Any tool that writes a per-streamline parcel assignment, such as MRtrix3 `tck2connectome -out_assignments`, works.
+
+```python
+from fsc.parcellation import streamline_support
+
+assignments = np.loadtxt("assignments.txt", dtype=int)  # two parcel labels per streamline
+weights = np.loadtxt("sift2_weights.txt")               # optional, see below
+
+values = streamline_support(support, assignments, weights)
+np.savetxt("fsc_streamline_weights.txt", values)        # one value per streamline, input order
+```
+
+The support of each parcel pair is split among the streamlines connecting that pair in proportion to their weights. So the values of each pair's streamlines sum to `support[a, b]`. This holds for both methods and for SC from any source or normalisation. Only the relative weights within a pair matter.
+
+Requirements:
+
+- **Assignments:** exactly two labels per streamline, numbered from 1 in SC matrix order, with 0 for an unassigned endpoint. This is the default `tck2connectome -out_assignments` format. Options that write more labels per streamline (e.g. `-assignment_all_voxels`), or that add a row for node 0 to the matrix (`-keep_unassigned`) break this correspondence!
+- **Weights:** use the per-streamline weights the SC was built from. Omit them for streamline counts, pass the SIFT2 weights file if the SC used `-tck_weights_in`, or `1 / length` for length-scaled SC. Non-finite or non-positive weights mark a streamline as invalid.
+- **Output:** one non-negative value per input streamline, in input order. Unassigned, invalid and self-connecting streamlines get 0. If the SC has an edge with no streamline in `assignments`, that edge's support is not mapped.
+
+For signed streamline currents from a potential vector computed with `fsc.solve_fsc()`, use `streamline_currents()`. If SC is built inside fscpy from streamline resistances, use `sc_from_streamlines()`.
+
+
+### Voxel workflow
+
+The runnable demonstration is [`examples/voxel.py`](examples/voxel.py). For actual FOD images and registered parcel labels, the workflow is:
+
+```python
+import nibabel as nib
+import numpy as np
+import fsc
+from fsc.voxel import graph_from_fod, labels_in_fod_space, add_roi_nodes, sum_pairwise_support
+
+fod_image = nib.load('fod_sh.nii.gz')
+parcel_image = nib.load('parcellation_registered.nii.gz')
+labels = labels_in_fod_space(parcel_image, fod_image)
+
+fc = np.load('fc.npy')
+roi_labels = np.load('roi_labels.npy')  # must match the FC matrix order
+
+wm_graph, voxel_mapping = graph_from_fod(fod_image, fod_norm_threshold=0.25)
+graph, parcellation = add_roi_nodes(
+    wm_graph, voxel_mapping, fod_image, labels, roi_labels=roi_labels
+)
+
+support = sum_pairwise_support(
+    graph, voxel_mapping, parcellation, fc, solver='cg', rtol=1e-6
+)
+nib.save(nib.Nifti1Image(support, fod_image.affine), 'fsc_support.nii.gz')
+```
+
+#### Input conventions
+
+- **SH basis.** The FOD image must contain SH coefficients in the MRtrix3 convention, as written by `dwi2fod`. This is DIPY's `tournier07` basis with `legacy=False`, which is the default. FODs in the older MRtrix 0.2 convention need `legacy=True`.
+  Since version 2.0.2 the default is `legacy=False`; earlier versions defaulted to `legacy=True`. Pass `legacy=True` explicitly to reproduce results from those versions.
+- **Same settings in both calls.** Pass identical `sphere`, `basis`, `legacy`, `kappa`, `kernel_power` and `orientation_floor` values to `graph_from_fod()` and `add_roi_nodes()`. They are not cross-checked.
+- **Frame.** Neighbour directions are computed in world coordinates from the image affine, so the SH coefficients must be defined in that same frame, as MRtrix3 does. The image must have a correct affine.
+- **Registration.** `labels_in_fod_space()` uses nearest-neighbour resampling and assumes the images are **already spatially registered**. It does not register images or reorient SH coefficients.
+- **Masks.** An optional `wm_mask` restricts graph voxels and an optional `exclusion_mask` removes voxels. The FOD-norm threshold is always applied in addition to `wm_mask`.
+- **ROIs.** ROI voxels must have positive labels, lie outside the selected WM voxel graph, and every ROI must have at least one FOD-supported WM contact, otherwise `add_roi_nodes()` raises an error. An optional `tissue_mask` excludes non-tissue ROI voxels.
+
+#### How the graph is built
+
+- **Nodes.** Voxels whose SH coefficient vector has a Euclidean norm above `fod_norm_threshold` (default 0.25), inside `wm_mask` if given. This threshold depends on the FOD intensity scale, so check it against your FOD normalisation.
+- **Edges.** Each voxel is connected to its 26 neighbours (13 unique directions). The conductance of an interface is `sqrt(s_i · s_j) / ℓ`, where `ℓ` is the physical distance between voxel centres and `s` is the directional support of each endpoint. Interfaces below `min_conductance` (default 1e-12) are dropped.
+- **Directional support.** The FOD amplitude along the interface direction is evaluated with an angular averaging kernel, with weights proportional to `exp(κ·|cos θ|^p)` over the sampling sphere (default `repulsion724`, `kappa=8`, `kernel_power=2`). It is clipped at zero after averaging, reduced by `orientation_floor` times the mean positive FOD amplitude of the voxel, and clipped at zero again. This kernel averaging is an implementation detail: the papers evaluate the FOD directly along the interface direction.
+- **ROI supernodes.** Each ROI is a graph node. Labelled voxels outside the WM graph are ROI tissue. Each one touches the WM graph through its six face neighbours. The conductance of a contact is `interface_scale` times the *WM voxel's* directional support along the face normal, divided by the voxel size. Diagonal contacts are not used, and support is taken from the WM side only. All ROI supernodes are present in the graph when any pair is solved.
+- **Support map.** Voxel support is the sum of absolute currents on the WM–WM edges incident to a voxel, accumulated over all FC pairs. ROI–WM interface edges are excluded.
+
+#### Solving
+
+The voxel workflow applies each finite, positive FC pair **independently in the mathematical model**. For efficiency, the implementation solves reusable grounded-Laplacian basis fields relative to one ROI per connected component, then reconstructs pair solutions. It accumulates **absolute** structural currents. Pairs without a structural path contribute zero. Specify `pairs=[(0, 1)]` to select one pair by zero-based FC matrix indices.
+
+`solver` can be `'auto'`, `'cg'` or `'direct'`; the default `rtol` is `1e-4`. Each solution is checked for current conservation, and the check is relative to the injected current, so it does not depend on the scale of the conductances. One potential field is stored per active ROI, and run time grows with the number of FC pairs.
+
+## Numerical interpretation
+
+In both workflows, only positive FC values define imposed potential differences. Negative values are ignored. SC values and FOD interface weights act as conductances, **not lengths or resistances**. FSC reports how the weighted structural graph supports the imposed correlations. It is not a direct measurement of axonal traffic or a uniquely determined anatomical tract.
+
+The low-level `fsc.solve_fsc()` interface solves **simultaneous** functional constraints through modified nodal analysis and returns an `FSCResult` (potentials, currents and residual diagnostics). The constraints must be mutually compatible. The imposed potential differences must sum to zero around every cycle of constrained pairs. Constraints without cycles, e.g. the FiberCup experiment, always satisfy this. Whereas a dense FC matrix likely does not because it imposes far more potential differences than the graph has free potentials. `solve_from_parcellations(..., method="joint")` wraps this interface and checks for cycles before solving. For dense FC, use `solve_from_parcellations()` with the default `method="pairwise"`, or `solve_fsc_voxel()`, which evaluate FC pairs separately and sum their absolute structural-edge currents.
+
+## Relation to the publications
+
+- **Network Neuroscience (parcellation workflow).** The paper formulates FSC as one joint modified-nodal-analysis system (Eq. 11), with all constraints solved together. `solve_from_parcellations(..., method="joint")` implements it for FC pairs without cycles like in the FiberCup specificity test. When FC pairs form cycles, as many dense FC matrices, the constraints cannot all hold at once andthe joint system has no exact solution. For such inputs use the default `method="pairwise"`, which solves each pair separately and sums absolute currents. The two methods agree for a single constraint.
+- **Aperture Neuro (voxel workflow).** The Methods describe imposing each selected FC value separately and accumulating the resulting current magnitudes, which is what `sum_pairwise_support()` does. The directional-support kernel, the six-face ROI contacts and the 0.25 norm threshold are implementation choices not given in the paper.
+
+## Tests
+
+Run the small deterministic tests without downloading neuroimaging datasets:
+
+```bash
+python -m pytest -q
+```
+
+The tests cover the five-node analytical solution, general MNA, the joint parcellation method and its rejection of FC with cycles, mapping support to streamlines, negative FC, empty FC, ROI-basis accumulation, disconnected ROIs, WM-only voxel support, and the scale-invariance of the solver's convergence check. Optional tests run when NiBabel and DIPY are installed: a synthetic-FOD end-to-end example, and a check that the default SH basis reproduces amplitudes computed by MRtrix3 (`sh2amp`) from a reference FiberCup FOD stored in `tests/data/`.
+
+## Research
+
+The two FSC workflows are described in the following papers:
+
+- **Parcellation workflow:** Sairanen, V. *From nodes to pathways: an edge-centric model of brain function–structure coupling via constrained Laplacians*. **Network Neuroscience** (2026). [doi:10.1162/NETN.a.589](https://doi.org/10.1162/NETN.a.589).
+
+- **Voxel workflow:** Sairanen, V. *Voxel-wise function-structure coupling with diffusion-weighted and functional MRI*. **Aperture Neuro** (2026). [doi:10.52294/001c.172225](https://doi.org/10.52294/001c.172225).
+
+Please, cite the publication corresponding to the workflow used.
+
+## License
+
+GNU General Public License v3.0; see [LICENSE](LICENSE).

{fscpy-2.0.0 → fscpy-2.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fscpy"
-version = "2.0.0"
+version = "2.0.2"
 description = "Function-structure coupling on parcellation and FOD-derived voxel graphs"
 readme = "README.md"
 requires-python = ">=3.10"

{fscpy-2.0.0 → fscpy-2.0.2}/src/fsc/parcellation/__init__.py

@@ -1,5 +1,6 @@
 """FSC on regional parcellation graphs and tractography streamlines."""
 
 from .connectivity import graph_from_sc, solve_from_parcellations, edge_currents_to_matrix
+from .streamlines import sc_from_streamlines, streamline_currents, streamline_support
 
-__all__ = ["graph_from_sc", "solve_from_parcellations", "edge_currents_to_matrix"]
+__all__ = ["graph_from_sc", "solve_from_parcellations", "edge_currents_to_matrix", "sc_from_streamlines", "streamline_currents", "streamline_support"]

{fscpy-2.0.0 → fscpy-2.0.2}/src/fsc/parcellation/connectivity.py

@@ -1,83 +1,135 @@
-"""Parcellation FSC from structural and functional connectivity matrices."""
-
-import numpy as np
-from scipy.sparse.csgraph import connected_components
-from scipy.sparse.linalg import factorized
-from warnings import warn
-import fsc
-
-
-def graph_from_sc(sc):
-    """Use the upper triangle of a symmetric SC matrix as graph conductances."""
-    sc = fsc.validate_symmetric_matrix(sc, "SC")
-    source, target = np.nonzero(np.triu(sc, k=1))
-    return fsc.WeightedGraph(len(sc), source, target, sc[source, target])
-
-def solve_from_parcellations(sc, fc):
-    """Calculate FSC support from parcellation SC and FC matrices."""
-    graph = graph_from_sc(sc)
-
-    if np.shape(fc) != (graph.n_nodes, graph.n_nodes):
-        raise ValueError("SC and FC dimensions differ.")
-
-    pairs, values = fsc.fc_pairs(fc)
-    edge_support = np.zeros(len(graph.edge_i))
-
-    if len(pairs) == 0:
-        return edge_currents_to_matrix(graph, edge_support, absolute=True)
-
-    laplacian = graph.laplacian()
-    _, component_labels = connected_components(laplacian, directed=False)
-
-    # Only FC pairs with a structural path can carry current.
-    connected = (
-        component_labels[pairs[:, 0]] == component_labels[pairs[:, 1]]
-    )
-
-    pairs = pairs[connected]
-    values = values[connected]
-
-    if len(pairs) == 0:
-        warn("No structural support for any FC pair.", stacklevel=2)
-        return edge_currents_to_matrix(graph, edge_support, absolute=True)
-
-    # Ground one node in each connected component.
-    _, ground_nodes = np.unique(component_labels, return_index=True)
-    mask = np.ones(graph.n_nodes, dtype=bool)
-    mask[ground_nodes] = False
-
-    solve = factorized(laplacian[mask][:, mask].tocsc())
-
-    rhs = np.zeros(graph.n_nodes)
-    potentials = np.zeros(graph.n_nodes)
-
-    for (source, target), value in zip(pairs, values):
-        rhs.fill(0)
-        rhs[source] = 1.0
-        rhs[target] = -1.0
-
-        potentials.fill(0)
-        potentials[mask] = solve(rhs[mask])
-
-        resistance = potentials[source] - potentials[target]
-        potentials *= abs(value) / resistance
-
-        currents = graph.conductance * (
-            potentials[graph.edge_i] - potentials[graph.edge_j]
-        )
-        edge_support += np.abs(currents)
-
-    return edge_currents_to_matrix(graph, edge_support, absolute=True)
-
-
-def edge_currents_to_matrix(graph, edge_currents, absolute=False):
-    """Convert graph edge currents to an N-by-N connectivity matrix."""
-    matrix = np.zeros((graph.n_nodes, graph.n_nodes))
-    for node_i, node_j, current in zip(
-        graph.edge_i, graph.edge_j, edge_currents
-    ):
-        if absolute:
-            current = abs(current)
-        matrix[node_i, node_j] += current
-        matrix[node_j, node_i] += current if absolute else -current
-    return matrix
+"""Parcellation FSC from structural and functional connectivity matrices."""
+
+import numpy as np
+from scipy import sparse
+from scipy.sparse.csgraph import connected_components
+from scipy.sparse.linalg import factorized
+from warnings import warn
+import fsc
+
+
+def graph_from_sc(sc):
+    """Use the upper triangle of a symmetric SC matrix as graph conductances."""
+    sc = fsc.validate_symmetric_matrix(sc, "SC")
+    source, target = np.nonzero(np.triu(sc, k=1))
+    return fsc.WeightedGraph(len(sc), source, target, sc[source, target])
+
+def solve_from_parcellations(sc, fc, *, method="pairwise", solver="auto"):
+    """Calculate FSC support from parcellation SC and FC matrices.
+
+    method="pairwise" solves each positive FC pair separately and sums the
+    absolute edge currents. It is defined for any FC matrix.
+
+    method="joint" solves all FC constraints in one modified-nodal-analysis
+    system (Network Neuroscience paper, Eq. 11) and returns absolute edge
+    currents. It requires the FC pairs to contain no cycles. Therefore, a dense FC likely has no exact joint solution.
+
+    solver is passed to fsc.solve_fsc() and is used only by method="joint".
+    """
+    if method == "pairwise":
+        return _solve_pairwise(sc, fc)
+    if method == "joint":
+        return _solve_joint(sc, fc, solver=solver)
+    raise ValueError(f"Unknown method: {method}")
+
+def _solve_pairwise(sc, fc):
+    """Solve each FC pair separately and sum absolute edge currents."""
+    graph = graph_from_sc(sc)
+
+    if np.shape(fc) != (graph.n_nodes, graph.n_nodes):
+        raise ValueError("SC and FC dimensions differ.")
+
+    pairs, values = fsc.fc_pairs(fc)
+    edge_support = np.zeros(len(graph.edge_i))
+
+    if len(pairs) == 0:
+        return edge_currents_to_matrix(graph, edge_support, absolute=True)
+
+    laplacian = graph.laplacian()
+    _, component_labels = connected_components(laplacian, directed=False)
+
+    # Only FC pairs with a structural path can carry current.
+    connected = (
+        component_labels[pairs[:, 0]] == component_labels[pairs[:, 1]]
+    )
+
+    pairs = pairs[connected]
+    values = values[connected]
+
+    if len(pairs) == 0:
+        warn("No structural support for any FC pair.", stacklevel=3)
+        return edge_currents_to_matrix(graph, edge_support, absolute=True)
+
+    # Ground one node in each connected component.
+    _, ground_nodes = np.unique(component_labels, return_index=True)
+    mask = np.ones(graph.n_nodes, dtype=bool)
+    mask[ground_nodes] = False
+
+    solve = factorized(laplacian[mask][:, mask].tocsc())
+
+    rhs = np.zeros(graph.n_nodes)
+    potentials = np.zeros(graph.n_nodes)
+
+    for (source, target), value in zip(pairs, values):
+        rhs.fill(0)
+        rhs[source] = 1.0
+        rhs[target] = -1.0
+
+        potentials.fill(0)
+        potentials[mask] = solve(rhs[mask])
+
+        resistance = potentials[source] - potentials[target]
+        potentials *= value / resistance
+
+        currents = graph.conductance * (
+            potentials[graph.edge_i] - potentials[graph.edge_j]
+        )
+        edge_support += np.abs(currents)
+
+    return edge_currents_to_matrix(graph, edge_support, absolute=True)
+
+def _independent_cycles(pairs, n_nodes):
+    """Number of independent cycles in the graph whose edges are FC pairs."""
+    if len(pairs) == 0:
+        return 0
+    adjacency = sparse.coo_matrix(
+        (np.ones(len(pairs)), (pairs[:, 0], pairs[:, 1])),
+        shape=(n_nodes, n_nodes),
+    )
+    n_components, _ = connected_components(adjacency, directed=False)
+    return len(pairs) - (n_nodes - n_components)
+
+def _solve_joint(sc, fc, *, solver="auto"):
+    """Solve all FC constraints jointly (NetN Eq. 11) for cycle-free FC pairs only. Subnetworks with cycles are not solved!"""
+    graph = graph_from_sc(sc)
+
+    if np.shape(fc) != (graph.n_nodes, graph.n_nodes):
+        raise ValueError("SC and FC dimensions differ.")
+
+    pairs, values = fsc.fc_pairs(fc)
+    cycles = _independent_cycles(pairs, graph.n_nodes)
+    if cycles > 0:
+        raise ValueError(
+            f"The FC pairs form {cycles} independent cycle(s). The joint "
+            "system has an exact solution only if FC values sum to zero "
+            "around every cycle, which correlation values do not. Use "
+            "method='pairwise' for dense FC."
+        )
+
+    constraints = fsc.functional_connectivity_from_fc_pairs(
+        pairs, values, graph.n_nodes
+    )
+    result = fsc.solve_fsc(graph, constraints, solver=solver)
+    return edge_currents_to_matrix(graph, result.edge_currents, absolute=True)
+
+def edge_currents_to_matrix(graph, edge_currents, absolute=False):
+    """Convert graph edge currents to an N-by-N connectivity matrix."""
+    matrix = np.zeros((graph.n_nodes, graph.n_nodes))
+    for node_i, node_j, current in zip(
+        graph.edge_i, graph.edge_j, edge_currents
+    ):
+        if absolute:
+            current = abs(current)
+        matrix[node_i, node_j] += current
+        matrix[node_j, node_i] += current if absolute else -current
+    return matrix