pyLQT 1.0.dev1__py3-none-any.whl

lesion_metrics/gray_matter/metrics.py

@@ -0,0 +1,78 @@
+import numpy as np
+import nibabel as nib
+
+from nibabel.processing import resample_from_to
+from .utils import compute_parcel_damage
+
+
+def get_parcel_damage(
+    lesion, 
+    atlas,
+    atlas_labels,
+    parcel_column,
+    out_path = None
+    ):
+    """Compute lesion damage for each parcel of an atlas.
+
+    The lesion is resampled to the atlas space, and the proportion of
+    each parcel overlapping with the lesion is computed. A parcel damage 
+    map is created, where each parcel voxel is assigned the damage proportion 
+    of its parcel.
+
+    Parameters
+    ----------
+    lesion : nibabel.Nifti1Image
+        NIfTI lesion mask. Voxels with values greater than zero are
+        considered lesioned.
+    atlas : nibabel.Nifti1Image
+        NIfTI parcellation atlas containing integer parcel labels.
+    atlas_labels : pandas.DataFrame
+        DataFrame containing the parcel labels corresponding to the
+        values in ``parcel_column``.
+    parcel_column : str
+        Name of the column in ``atlas_labels`` containing the parcel
+        labels used in the atlas.
+    out_path : pathlib.Path | None, optional
+        Directory where the parcel damage map and damage DataFrame are
+        saved. If None, no files are saved.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Copy of ``atlas_labels`` with an additional ``PercentDamage``
+        column containing the proportion of each parcel affected by the
+        lesion.
+    """
+    
+    lesion_resampled = resample_from_to(lesion,
+                                        atlas,
+                                        order=1)
+    
+    lesion_volume = lesion_resampled.get_fdata()
+    atlas_volume = atlas.get_fdata().astype(np.int32)
+
+    parcel_damages = []
+    parcel_damage_map = np.zeros_like(atlas_volume, dtype=np.float32)
+
+    for parcel in atlas_labels[parcel_column]:
+        parcel_volume = atlas_volume == parcel
+        parcel_damage = compute_parcel_damage(parcel_volume, lesion_volume)
+
+        parcel_damages.append(parcel_damage)
+        parcel_damage_map[parcel_volume] = np.round(parcel_damage, 5)
+
+    if out_path:
+        out_path.mkdir(parents=True, exist_ok=True)
+
+        nib.save(
+            nib.Nifti1Image(parcel_damage_map, atlas.affine, atlas.header),
+            out_path / "parcel_damage_map.nii.gz"
+        )
+
+    damage_frame = atlas_labels.copy(deep=True)
+    damage_frame["PercentDamage"] = parcel_damages
+    if out_path:
+        damage_frame.to_csv(out_path / 'parcel_damage_frame.csv', index=False)
+    
+    return damage_frame
+    

lesion_metrics/gray_matter/utils.py

@@ -0,0 +1,30 @@
+import numpy as np
+
+def compute_parcel_damage(
+    parcel_volume, 
+    lesion_volume
+    ):
+    """Compute the percentage of overlap of a lesion on a parcel.
+
+    Parameters
+    ----------
+    parcel_volume : numpy.ndarray
+        Binary or boolean mask representing the voxels belonging to the
+        parcel.
+    lesion_volume : numpy.ndarray
+        Lesion mask. Voxels with values greater than zero are considered
+        lesioned.
+
+    Returns
+    -------
+    float
+        Proportion of parcel voxels overlapping with the lesion, between
+        0 and 1. Returns 0 if the parcel contains no voxels.
+    """
+    
+    parcel_size = np.count_nonzero(parcel_volume)
+    if parcel_size == 0:
+        return 0
+    overlap = np.count_nonzero(parcel_volume & (lesion_volume > 0))
+
+    return overlap / parcel_size

lesion_metrics/network/metrics.py

@@ -0,0 +1,190 @@
+import numpy as np
+import networkx as nx
+import pickle
+
+from scipy.sparse import csr_matrix
+from scipy.sparse.csgraph import shortest_path
+from nibabel.processing import resample_from_to
+from .utils import create_structural_connectivity
+
+def get_parcel_wise_disconnection_severity(
+    aggregated_tracts,
+    aggregated_tracts_disconnected,
+    atlas,
+    out_path = None
+    ):
+    """Compute parcel-wise structural disconnection severity.
+
+    Structural connectivity is computed for all streamlines and for
+    disconnected streamlines separately. The disconnection severity is
+    then calculated as the proportion of connections that are disconnected
+    for each pair of atlas parcels.
+
+    Parameters
+    ----------
+    aggregated_tracts : StatefulTractogram
+        Tractogram containing all aggregated streamlines.
+    aggregated_tracts_disconnected : StatefulTractogram
+        Tractogram containing the subset of aggregated streamlines that
+        are disconnected.
+    atlas : nib.Nifti1Image
+        Parcellation atlas. The atlas is resampled to the tractogram
+        reference grid using nearest-neighbor interpolation.
+    out_path : Path | None, optional
+        Directory where the structural connectivity matrices and
+        disconnection measures are saved. If None, no files are saved.
+
+    Returns
+    -------
+    tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]
+        A tuple containing:
+
+        - structural_connectivity : numpy.ndarray
+            Structural connectivity matrix computed from all streamlines.
+        - structural_connectivity_disconnected : numpy.ndarray
+            Structural connectivity matrix computed from disconnected
+            streamlines.
+        - disconnections_severity : numpy.ndarray
+            Proportion of connections that are disconnected for each
+            pair of parcels.
+        - per_spared_connections : numpy.ndarray
+            Proportion of connections that remain spared for each pair
+            of parcels.
+    """
+    
+    if out_path:
+        out_path.mkdir(parents=True, exist_ok=True)
+        sc_path = out_path / "structural_connectivity"
+        sc_disconnected_path = out_path / "structural_connectivity_disconnected"
+    else:
+        sc_path = None
+        sc_disconnected_path = None
+    
+    atlas_resampled = resample_from_to(atlas,
+                                       aggregated_tracts.space_attributes[1::-1],
+                                       order=0)
+    
+    structural_connectivity = create_structural_connectivity(tract=aggregated_tracts,
+                                                             atlas_resampled=atlas_resampled,
+                                                             out_path=sc_path)
+    structural_connectivity_disconnected = create_structural_connectivity(tract=aggregated_tracts_disconnected,
+                                                                          atlas_resampled=atlas_resampled,
+                                                                          out_path=sc_disconnected_path)
+
+    disconnections_severity = np.divide(structural_connectivity_disconnected,
+                                        structural_connectivity,
+                                        out=np.zeros_like(structural_connectivity, dtype=float),
+                                        where=structural_connectivity != 0
+                                        )
+    
+    per_spared_connections = np.divide(
+        structural_connectivity-structural_connectivity_disconnected,
+        structural_connectivity,
+        out=np.zeros_like(structural_connectivity, dtype=float),
+        where=structural_connectivity != 0
+        )
+    
+    if out_path:
+        np.save((out_path / "structural_connectivity.npy"), structural_connectivity)
+        np.save((out_path / "structural_connectivity_disconnected.npy"), structural_connectivity_disconnected)
+        np.save((out_path / "disconnections_severity.npy"), disconnections_severity)
+        np.save((out_path / "per_spared_connections.npy"), per_spared_connections)
+
+    return (structural_connectivity,
+            structural_connectivity_disconnected,
+            disconnections_severity,
+            per_spared_connections)
+
+
+def get_sspl_increase(
+    structural_connectivity, 
+    per_spared_connections,
+    out_path = None, 
+    spared_threshold = 0.5
+    ):
+    
+    """Compute the increase in shortest structural path length after damage.
+
+    The structural connectivity matrix is converted to a binary graph.
+    Connections are considered spared when their proportion of
+    remaining streamlines exceeds ``spared_threshold``. Shortest path
+    lengths are computed for the full and spared connectivity graphs,
+    and their difference is used to quantify the increase in shortest
+    structural path length.
+
+    Parameters
+    ----------
+    structural_connectivity : numpy.ndarray
+        Structural connectivity matrix representing the intact network.
+        Non-zero entries are treated as existing connections.
+    per_spared_connections : numpy.ndarray
+        Matrix containing the proportion of streamlines spared for each
+        connection.
+    out_path : Path | None, optional
+        Directory where the shortest path matrices and their differences
+        are saved. If None, no files are saved.
+    spared_threshold : float, optional
+        Minimum proportion of spared streamlines required for a connection
+        to be considered present in the spared network. Defaults to 0.5.
+
+    Returns
+    -------
+    tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]
+        A tuple containing:
+
+        - SSPL_full_connections : numpy.ndarray
+            Shortest structural path lengths in the intact connectivity
+            network.
+        - SSPL_spared_connections : numpy.ndarray
+            Shortest structural path lengths in the spared connectivity
+            network.
+        - SSPL_increase : numpy.ndarray
+            Increase in shortest structural path length between the intact
+            and spared networks.
+        - SSPL_indirect_increase : numpy.ndarray
+            SSPL increase for indirect connections only. Direct connections
+            are set to zero.
+    """
+    
+    
+    # fix inf values, maybe set them to max+1 as it is done for pathway that completely disconnects
+
+    binary_structural_connectivity = structural_connectivity > 0
+    binary_spared_connections = per_spared_connections > spared_threshold
+    
+    structural_connectivity_graph = csr_matrix(binary_structural_connectivity)
+    spared_connections_graph = csr_matrix(binary_spared_connections)
+    
+    # selects automatically the correct algorithm (Dijkstra, Floyd-Warshall, Bellman-Ford, Johnson). 
+    # Only Dijkstra or Floyd-Warshall will be used since the graph should be only positive
+    SSPL_full_connections = shortest_path(
+        structural_connectivity_graph,
+        directed=False,
+        unweighted=True)
+    max_SSPL = np.max(SSPL_full_connections[np.isfinite(SSPL_full_connections)])
+    SSPL_full_connections[
+            np.isinf(SSPL_full_connections)
+        ] = max_SSPL + 1
+    
+    direct_connections = (SSPL_full_connections == 1)
+    
+    SSPL_spared_connections = shortest_path(
+        spared_connections_graph,
+        directed=False,
+        unweighted=True)
+    SSPL_spared_connections[
+        np.isinf(SSPL_spared_connections)
+    ] = max_SSPL + 1
+
+    SSPL_increase = SSPL_spared_connections - SSPL_full_connections
+    SSPL_indirect_increase = SSPL_increase.copy()
+    SSPL_indirect_increase[~direct_connections] = 0.0
+    
+    if out_path:
+        out_path.mkdir(parents=True, exist_ok=True)
+        np.save((out_path / "SSPL_full_connections.npy"), SSPL_full_connections)
+        np.save((out_path / "SSPL_spared_connections.npy"), SSPL_spared_connections)
+        np.save((out_path / "SSPL_increase.npy"), SSPL_increase)
+        np.save((out_path / "SSPL_indirect_increase.npy"), SSPL_indirect_increase)
+    
+    return SSPL_full_connections, SSPL_spared_connections, SSPL_increase, SSPL_indirect_increase

lesion_metrics/network/utils.py

@@ -0,0 +1,104 @@
+import numpy as np
+import networkx as nx
+import dipy.io.stateful_surface
+
+from scipy.spatial.distance import cdist
+from scipy import ndimage
+from dipy.io.stateful_tractogram import StatefulTractogram
+
+def create_structural_connectivity(
+    tract,
+    atlas_resampled,
+    threshold=5.0,
+    out_path=None
+):
+    """Compute a structural connectivity matrix from a tractogram and atlas.
+
+    Streamline endpoints are assigned to the first parcel crossed when
+    following the streamline from the endpoint inward. Streamlines are
+    only included if both endpoints are within ``threshold`` of a parcel.
+
+    Parameters
+    ----------
+    tract : StatefulTractogram
+        Tractogram containing the streamlines used to estimate structural
+        connectivity.
+    atlas_resampled : nibabel.Nifti1Image
+        Parcellation atlas resampled to the same space and grid as the
+        tractogram.
+    threshold : float | None, optional
+        Maximum distance along the streamline from each endpoint to the
+        first crossed parcel. If None, no distance threshold is applied.
+    out_path : pathlib.Path | None, optional
+        Path where the structural connectivity matrix should be saved
+        as a NumPy array. If None, the matrix is not saved.
+
+    Returns
+    -------
+    numpy.ndarray
+        Symmetric structural connectivity matrix with the background
+        label removed.
+    """
+    atlas = atlas_resampled.get_fdata().astype(int)
+    atlas_affine_inv = np.linalg.inv(atlas_resampled.affine)
+
+    n_parcels = int(np.max(atlas))
+
+    sc = np.zeros((n_parcels, n_parcels), dtype=np.int32)
+
+    for streamline in tract.streamlines:
+
+        points = np.asarray(streamline)
+        points_h = np.column_stack((points, np.ones(len(points))))
+
+        voxel_coords = (atlas_affine_inv @ points_h.T).T[:, :3]
+        voxel_coords = np.rint(voxel_coords).astype(int)
+
+        # Keep only points inside the atlas volume
+        valid = np.all((voxel_coords >= 0) & (voxel_coords < np.array(atlas.shape)), axis=1)
+
+        parcel_labels = np.zeros(len(points), dtype=int)
+        parcel_labels[valid] = atlas[
+            voxel_coords[valid, 0],
+            voxel_coords[valid, 1],
+            voxel_coords[valid, 2]
+        ]
+
+        endpoints = []
+
+        for indices in (range(len(points)), range(len(points) - 1, -1, -1)):
+
+            distance = 0.0
+            parcel = 0
+            previous = None
+
+            for i in indices:
+                if previous is not None:
+                    distance += np.linalg.norm(
+                        points[i] - points[previous]
+                    )
+                if parcel_labels[i] > 0:
+                    parcel = parcel_labels[i]
+                    break
+                previous = i
+            endpoints.append((parcel, distance))
+
+        p1, d1 = endpoints[0]
+        p2, d2 = endpoints[1]
+
+        if p1 == 0 or p2 == 0:
+            continue
+        if threshold is not None and (d1 > threshold or d2 > threshold):
+            continue
+
+        p1 -= 1
+        p2 -= 1
+        sc[p1, p2] += 1
+        if p1 != p2:
+            sc[p2, p1] += 1
+
+    if out_path:
+        np.save(out_path, sc)
+
+    return sc
+

lesion_metrics/utils/configs.py

@@ -0,0 +1,137 @@
+import nibabel as nib
+import pandas as pd
+import json
+
+from pathlib import Path
+
+def atlas_cfg_read(atlas_cfg_path):
+    """Read an atlas configuration file and load the associated data.
+
+    Parameters
+    ----------
+    atlas_cfg_path : Path
+        Path to the .json atlas configuration file. The configuration must
+        contain the following fields: 
+        
+        - 'name': 
+            a string naming the atlas
+        - 'atlas': 
+            path to the nifti atlas file, relative to the folder 
+            containing the config file
+        - 'labels': 
+            path to the csv containing the labels and their associated
+            parcel name, relative to the folder containing the config file
+        - 'space': 
+            standard space name available in templateflow or path
+            to reference nifti relative to the folder containing the config file
+
+    Returns
+    -------
+    tuple[str, nibabel.Nifti1Image, pandas.DataFrame, str]
+        A tuple containing:
+
+        - atlas_name : str
+            Name of the atlas.
+        - atlas : nibabel.Nifti1Image
+            Loaded atlas image.
+        - atlas_labels : pandas.DataFrame
+            DataFrame containing the atlas parcel labels.
+        - atlas_space : str
+            Space in which the atlas is defined.
+    """
+    with atlas_cfg_path.open("r") as f:
+        atlas_cfg = json.load(f)
+
+    atlas_name = atlas_cfg.get("name")
+    atlas_path = atlas_cfg_path.parent / atlas_cfg.get("atlas")
+    atlas_labels_path = atlas_cfg_path.parent / atlas_cfg.get("labels")
+    atlas_space = atlas_cfg.get("space")
+    
+    atlas = nib.nifti1.load(atlas_path)
+    atlas_labels = pd.read_csv(atlas_labels_path)
+
+    return atlas_name, atlas, atlas_labels, atlas_space
+
+def tracts_cfg_read(tracts_cfg_path):
+    """Read a tracts configuration file and load the associated data.
+
+    Parameters
+    ----------
+    tracts_cfg_path : Path
+        Path to the .json tracts configuration file. The configuration must
+        contain the following fields: 
+        
+        - 'name': 
+            a string naming the tracts 
+        - 'tracts_folder': 
+            path to the folder containing .trk files, relative to 
+            the folder containing the config file
+        - 'references_folder': 
+            path to the folder containing nifti reference files 
+            of the tracts, relative to the folder containing the config file
+        - 'space': 
+            standard space name available in templateflow or path
+            to reference nifti relative to the folder containing the config file
+
+    Returns
+    -------
+    tuple[str, pathlib.Path, pathlib.Path, str]
+        A tuple containing:
+
+        - tracts_name : str
+            Name of the tracts.
+        - tracts_folder : pathlib.Path
+            Path to folder containing .trk tract files.
+        - references_folder : pathlib.Path
+            Path to folder containing .nii tract reference files.
+        - tracts_space : str
+            Space in which the tracts are defined.
+    """
+    with tracts_cfg_path.open("r") as f:
+        tracts_cfg = json.load(f)
+
+    tracts_name = tracts_cfg.get("name")
+    tracts_folder = Path(tracts_cfg_path.parent / tracts_cfg.get("tracts"))
+    references_folder = Path(tracts_cfg_path.parent / tracts_cfg.get("references"))
+    tracts_space = tracts_cfg.get("space")
+
+    return tracts_name, tracts_folder, references_folder, tracts_space
+
+def lesion_cfg_read(lesion_cfg_path: Path):
+    """Read a tracts configuration file and load the associated data.
+
+    Parameters
+    ----------
+    tracts_cfg_path : Path
+        Path to the .json tracts configuration file. The configuration must
+        contain the following fields: 
+        
+        - 'cohort_name': 
+            a string naming the tracts 
+        - 'tracts_folder': 
+            path to the folder containing segemented lesion files, 
+            relative to the folder containing the config file
+        - 'space': 
+            standard space name available in templateflow or path
+            to reference nifti relative to the folder containing the config file
+
+    Returns
+    -------
+    tuple[str, pathlib.Path, pathlib.Path, str]
+        A tuple containing:
+
+        - lesion_cohort_name : str
+            Name of the lesion cohort.
+        - lesion_folder : pathlib.Path
+            Path to folder containing nifti segmented lesion files.
+        - lesion_space : str
+            Space in which the lesions are defined.
+    """    
+    with lesion_cfg_path.open("r") as f:
+        lesion_cfg = json.load(f)
+        
+    lesion_cohort_name = lesion_cfg.get("cohort_name")
+    lesion_folder = Path(lesion_cfg_path.parent / lesion_cfg.get("lesion_folder"))
+    lesion_space = lesion_cfg.get("space")
+    
+    return lesion_cohort_name, lesion_folder, lesion_space