pyLQT 1.0.dev1__py3-none-any.whl

lesion_metrics/utils/downloads.py

@@ -0,0 +1,250 @@
+import zipfile
+import json
+import warnings
+import requests
+import shutil
+import gzip
+import nibabel as nib
+import numpy as np
+
+from templateflow import api as tf
+from pathlib import Path
+
+def create_tract_list(
+    references_folder, 
+    tracts_folder
+    ):
+    """Create paired lists of tractogram and reference image paths.
+
+    Tractograms and their corresponding NIfTI reference images are matched
+    based on their relative paths within their respective folders. The
+    function also checks that all reference images share the same voxel
+    grid and affine.
+
+    Parameters
+    ----------
+    references_folder : Path
+        Root directory containing the NIfTI reference images.
+    tracts_folder : Path
+        Root directory containing the tractogram files.
+
+    Returns
+    -------
+    tuple[list[Path], list[Path]]
+        Two lists containing:
+
+        - tracts_pathlist : list[Path]
+            Paths to the tractogram files.
+        - references_pathlist : list[Path]
+            Paths to the corresponding NIfTI reference images.
+
+        Only tractograms with a corresponding NIfTI reference are included.
+        Warnings are issued for missing pairs and for reference images with
+        mismatched grids or affines.
+    """
+    trk_paths = sorted(tracts_folder.rglob("*.trk.gz"))
+    nifti_paths = sorted(references_folder.rglob("*.nii.gz"))
+    
+    # Check that every TRK has a corresponding NIfTI
+    nifti_relatives = {
+        p.relative_to(references_folder)
+        for p in nifti_paths
+    }
+
+    for trk_path in trk_paths:
+        trk_relative = trk_path.relative_to(tracts_folder)
+        expected_nifti = Path(
+            str(trk_relative).replace(".trk.gz", ".nii.gz")
+        )
+
+        if expected_nifti not in nifti_relatives:
+            warnings.warn(f"No NIfTI found for {expected_nifti}")
+
+    # Check that every NIfTI has a corresponding TRK
+    trk_relatives = {
+        p.relative_to(tracts_folder)
+        for p in trk_paths
+    }
+
+    for nifti_path in nifti_paths:
+        nifti_relative = nifti_path.relative_to(references_folder)
+        expected_trk = Path(
+            str(nifti_relative).replace(".nii.gz", ".trk.gz")
+        )
+
+        if expected_trk not in trk_relatives:
+            warnings.warn(f"No TRK found for {expected_trk}")
+
+    tracts_pathlist = []
+    references_pathlist = []
+
+    for trk_path in trk_paths:
+        trk_relative = trk_path.relative_to(tracts_folder)
+
+        nifti_path = (
+            references_folder
+            / Path(str(trk_relative).replace(".trk.gz", ".nii.gz"))
+        )
+
+        if not nifti_path.exists():
+            continue
+
+        tracts_pathlist.append(trk_path)
+        references_pathlist.append(nifti_path)
+
+    # Verify that all NIfTIs are on the same grid
+    reference = None
+
+    for nifti_path in references_pathlist:
+        nifti = nib.nifti1.load(nifti_path)
+
+        if reference is None:
+            reference = nifti
+        else:
+            if nifti.shape != reference.shape:
+                warnings.warn(f"NIfTI grid mismatch: {nifti_path}")
+            if not np.allclose(nifti.affine, reference.affine):
+                warnings.warn(f"NIfTI affine mismatch: {nifti_path}")    
+
+    return tracts_pathlist, references_pathlist
+    
+def uncompress_trk_gz(
+    trk_path, 
+    out_path
+    ):
+    """Uncompress a .trk file if needed and save it to the output path.
+
+    Parameters
+    ----------
+    trk_path : Path
+        Path to the input .trk or compressed .trk.gz file.
+    out_path : Path
+        Path where the uncompressed .trk file is saved.
+
+    Returns
+    -------
+    Path
+        Path to the resulting .trk file.
+    """
+    if trk_path.suffix == ".gz":
+        with gzip.open(trk_path, "rb") as f_in:
+            with open(out_path, "wb") as f_out:
+                shutil.copyfileobj(f_in, f_out)
+    else:
+        shutil.copyfile(trk_path, out_path)
+
+    return out_path
+
+def default_download(out_folder: Path):
+    """Download the default HCP1065 tractography dataset and create its configuration.
+
+    The function downloads the HCP1065 average tractograms and their
+    corresponding NIfTI reference images, extracts them into the output
+    directory, and creates a JSON configuration file describing the
+    downloaded dataset. Existing folders are reused.
+
+    Parameters
+    ----------
+    out_folder : pathlib.Path
+        Directory where the HCP1065 dataset, reference images, and
+        configuration file are stored.
+
+    Returns
+    -------
+    pathlib.Path
+        Path to the generated HCP1065 configuration JSON file.
+    """
+
+    tracts_cfg_folder = out_folder / "HCP1065_cfg"
+    tracts_cfg_folder.mkdir(parents=True, exist_ok=True)
+        
+    tracts_folder = tracts_cfg_folder / "hcp1065_avg_tracts_trk"
+        
+    if tracts_folder.exists():
+        warnings.warn(
+            f"Tracts folder already exists, using it: {tracts_folder}"
+        )
+    else:
+        url = "https://github.com/data-others/atlas/releases/download/hcp1065/hcp1065_avg_tracts_trk.zip"
+        zip_path = out_folder / "hcp1065_avg_tracts_trk.zip"
+            
+        response = requests.get(url, stream=True, timeout=60)
+        response.raise_for_status()
+            
+        with zip_path.open("wb") as f:
+            for chunk in response.iter_content(chunk_size=1024*1024):
+                if chunk:
+                    f.write(chunk)
+            
+        with zipfile.ZipFile(zip_path) as zip_file:
+            zip_file.extractall(tracts_folder)
+                
+        zip_path.unlink()
+
+    references_folder = tracts_cfg_folder / "hcp1065_avg_tracts"
+
+    if references_folder.exists():
+        warnings.warn(
+            f"References folder already exists, using it: {references_folder}"
+        )
+    else:
+        url = "https://github.com/data-others/atlas/releases/download/hcp1065/hcp1065_avg_tracts_nifti.zip"
+        zip_path = out_folder / "hcp1065_avg_tracts_nifti.zip"
+
+        response = requests.get(url, stream=True, timeout=60)
+        response.raise_for_status()
+
+        with zip_path.open("wb") as f:
+            for chunk in response.iter_content(chunk_size=1024*1024):
+                if chunk:
+                    f.write(chunk)
+
+        with zipfile.ZipFile(zip_path) as zip_file:
+            zip_file.extractall(zip_path.parent)
+
+        zip_path.unlink()
+
+        references_folder = zip_path.parent / "nifti"
+        references_folder.rename(
+            zip_path.parent / "hcp1065_avg_tracts"
+        )
+            
+    tracts_name = "HCP1065"
+    tracts_space = "MNI152NLin2009aAsym"
+        
+    config = {"name": tracts_name,
+              "tracts": "hcp1065_avg_tracts_trk",
+              "references": "hcp1065_avg_tracts",
+              "space": tracts_space}
+        
+    tracts_cfg = Path(tracts_cfg_folder / "HCP1065_config.json")
+        
+    with open(tracts_cfg, "w") as f:
+        json.dump(config, f, indent=4)
+        
+    return tracts_cfg
+
+def get_ref_space_tf(space: str, res: int = 1):
+    """Load a templateflow T1w template and apply its brain mask.
+
+    Parameters
+    ----------
+    space : str
+        TemplateFlow template identifier.
+    res : int, optional
+        Template resolution to load. Defaults to 1.
+
+    Returns
+    -------
+    nibabel.Nifti1Image
+        T1w template with voxels outside the brain mask set to zero.
+    """
+    t1w_ref_path = tf.get(space, resolution=res, desc=None, suffix="T1w")
+    brain_mask_path = tf.get(space, resolution=res, desc="brain", suffix="mask")
+    t1w_ref = nib.load(t1w_ref_path)
+    brain_mask = nib.load(brain_mask_path)
+    ref_space_volume = t1w_ref.get_fdata().copy()
+    ref_space_volume[brain_mask.get_fdata() <= 0] = 0
+    ref_space = nib.Nifti1Image(ref_space_volume, t1w_ref.affine, t1w_ref.header)
+    
+    return ref_space

lesion_metrics/utils/registration.py

@@ -0,0 +1,106 @@
+from dipy.align.imaffine import AffineRegistration, MutualInformationMetric, transform_centers_of_mass
+from dipy.align.transforms import TranslationTransform3D, RigidTransform3D, AffineTransform3D
+from dipy.align.imwarp import SymmetricDiffeomorphicRegistration
+from dipy.align.metrics import CCMetric
+from dipy.align import write_mapping
+
+def register_affine(
+    moving,
+    static,
+    out_path=None
+):
+    """Register a moving image to a static image using affine registration.
+
+    Parameters
+    ----------
+    moving : nibabel.Nifti1Image
+        Image to be registered to the static image.
+    static : nibabel.Nifti1Image
+        Reference image defining the target space for the registration.
+    out_path : pathlib.Path | None, optional
+        Path where the resulting registration mapping is saved. If None,
+        the mapping is not saved.
+
+    Returns
+    -------
+    AffineMap
+        Affine mapping from the moving image space to the static image space.
+    """
+    metric = MutualInformationMetric()
+
+    affreg = AffineRegistration(metric=metric)
+
+    transform = TranslationTransform3D()
+    translation = affreg.optimize(
+        static.get_fdata(),
+        moving.get_fdata(),
+        transform,
+        params0=None,
+        static_grid2world=static.affine,
+        moving_grid2world=moving.affine,
+    )
+
+    transform = RigidTransform3D()
+    rigid = affreg.optimize(
+        static.get_fdata(),
+        moving.get_fdata(),
+        transform,
+        starting_affine=translation.affine,
+        params0=None,
+        static_grid2world=static.affine,
+        moving_grid2world=moving.affine,
+    )
+
+    transform = AffineTransform3D()
+    mapping = affreg.optimize(
+        static.get_fdata(),
+        moving.get_fdata(),
+        transform,
+        starting_affine=rigid.affine,
+        params0=None,
+        static_grid2world=static.affine,
+        moving_grid2world=moving.affine,
+    )
+
+    if out_path:
+        write_mapping(mapping, out_path)
+
+    return mapping
+
+def register_syn(
+    moving,
+    static,
+    out_path = None
+    ):
+    """Register a moving image to a static image using SyN registration,
+    with default settings from dipy.
+
+    Parameters
+    ----------
+    moving : nibabel.Nifti1Image
+        Image to be registered to the static image.
+    static : nibabel.Nifti1Image
+        Reference image defining the target space for the registration.
+    out_path : pathlib.Path | None, optional
+        Path where the resulting registration mapping is saved. If None,
+        the mapping is not saved.
+
+    Returns
+    -------
+    DiffeomorphicMap
+        Diffeomorphic mapping from the moving image space to the static
+        image space.
+    """
+    metric = CCMetric(dim=3)
+
+    syn = SymmetricDiffeomorphicRegistration(metric)
+
+    mapping = syn.optimize(static.get_fdata(),
+                           moving.get_fdata(),
+                           static_grid2world=static.affine,
+                           moving_grid2world=moving.affine)
+
+    if out_path:
+        write_mapping(mapping, out_path)
+
+    return mapping

lesion_metrics/white_matter/metrics.py

@@ -0,0 +1,160 @@
+import nibabel as nib
+import pandas as pd
+import numpy as np
+
+from nibabel.processing import resample_from_to
+from .utils import get_tract, get_tdi, get_streamlines_disconnection
+
+from pathlib import Path
+
+
+def get_tracts_disconnections_severity(
+    tracts_path,
+    references_path,
+    lesion,
+    disc_tracts_out_path = None,
+    disc_frame_out_path = None
+    ):
+
+    """Compute the proportion of disconnected streamlines for a list of tracts.
+
+    Parameters
+    ----------
+    tracts_path : list[Path]
+        Paths to the tractogram files in order.
+    references_path : list[Path] | Path
+        Paths to the NIfTI reference images corresponding to the tractograms.
+        If a single path is provided, it is used as the reference for all
+        tractograms. If a list, it should be in the same order as tracts_path.
+    lesion : nib.Nifti1Image
+        NIfTI lesion mask. Voxels with values greater than zero are considered
+        part of the lesion.
+    disc_tracts_out_path : Path | None, optional
+        Directory where tractograms containing the disconnected streamlines
+        are saved. If None, disconnected tractograms are not saved.
+    disc_frame_out_path : Path | None, optional
+        Directory where the resulting CSV file containing the disconnection
+        severity for each tract is saved. If None, the results are not saved.
+
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame containing the disconnection proportion for each tract,
+        together with its tract and pathway (parent directory) names. The ``Discon`` column
+        contains the proportion of streamlines intersecting the lesion.
+    """
+
+    if disc_tracts_out_path:
+        disc_tracts_out_path.mkdir(parents=True, exist_ok=True)
+    disconnections = []
+    if isinstance(references_path, Path):
+        references_path = [references_path] * len(tracts_path)
+    for tract_path, reference_path in zip(tracts_path, references_path):
+        
+        tract_name = tract_path.name.removesuffix(".gz").removesuffix(".trk")
+        pathway_name = tract_path.parent.name
+        
+        reference = nib.nifti1.load(reference_path)
+        
+        # grid can differ between lesion and average tracts (due to voxel size notably), 
+        # resample_from_to shifts/scales the grid of the lesion to match the one of the tract
+        lesion_resampled = resample_from_to(lesion,
+                                            reference,
+                                            order=1)
+        
+        lesion_mask = lesion_resampled.get_fdata() > 0
+        tract_mask = reference.get_fdata() > 0
+        
+        if not np.any(tract_mask & lesion_mask):
+            disconnections.append({
+                "Tract": tract_name,
+                "Discon": np.round(0.0, 3),
+                "Pathway": pathway_name,
+            })
+            continue
+        
+        if disc_tracts_out_path:
+            disconnected_tract_path = disc_tracts_out_path / f"{tract_name}_disconnected.trk"
+        else:
+            disconnected_tract_path = None
+        
+        tract = get_tract(tract_path=tract_path, reference_path=reference_path)
+        disconnected_tract, discon = get_streamlines_disconnection(tract=tract, 
+                                                                   lesion=lesion, 
+                                                                   out_path=disconnected_tract_path)
+        
+        disconnections.append({
+            "Tract": tract_name,
+            "Discon": np.round(discon, 5),
+            "Pathway": pathway_name,
+        })
+    
+    disconnections_frame = pd.DataFrame(disconnections)
+    
+    if disc_frame_out_path:
+        disc_frame_out_path.mkdir(parents=True, exist_ok=True)
+        out_csv = disc_frame_out_path / "percent_discon_tract.csv"
+        disconnections_frame.to_csv(out_csv, index=False)
+    
+    return disconnections_frame
+
+
+def get_tracts_disconnections_map(
+    tracts,
+    tracts_disconnected,
+    out_path = None
+    ):
+    """Compute a voxel-wise tracts disconnection map.
+
+    The disconnection map is computed as the ratio of the tract density
+    of disconnected streamlines to the tract density of all streamlines.
+    Voxels with no streamlines are not considered.
+
+    Parameters
+    ----------
+    tracts : StatefulTractogram
+        Tractogram containing all streamlines.
+    tracts_disconnected : StatefulTractogram
+        Tractogram containing the streamlines disconnected.
+    out_path : Path | None, optional
+        Directory where the TDI images and disconnection map are saved.
+        If None, no files are saved.
+
+    Returns
+    -------
+    tuple[nib.Nifti1Image, nib.Nifti1Image, nib.Nifti1Image]
+        A tuple containing:
+        
+        - disconnections_map : nib.Nifti1Image
+            Voxel-wise ratio of disconnected to total streamline density.
+        - tdi_aggregated : nib.Nifti1Image
+            Track density image of all streamlines.
+        - tdi_disconnected : nib.Nifti1Image
+            Track density image of disconnected streamlines.
+    """
+    
+    
+    if out_path:
+        out_path.mkdir(parents=True, exist_ok=True)
+        tdi_path = out_path / "tdi_mask.nii.gz"
+        tdi_disconnected_path = out_path / "tdi_disconnected_mask.nii.gz"
+    else:
+        tdi_path = None
+        tdi_disconnected_path = None
+    
+    tdi_aggregated = get_tdi(tracts, out_path=tdi_path)
+    tdi_disconnected = get_tdi(tracts_disconnected, out_path=tdi_disconnected_path)
+
+    disconnections_map = np.divide(
+        tdi_disconnected.get_fdata(),
+        tdi_aggregated.get_fdata(),
+        out=np.zeros_like(tdi_aggregated.get_fdata(), dtype=float),
+        where=tdi_aggregated.get_fdata() != 0
+    )
+    
+    disconnections_map = nib.Nifti1Image(disconnections_map, tdi_aggregated.affine, tdi_aggregated.header)
+    
+    if out_path:
+        nib.nifti1.save(disconnections_map, (out_path / "disconnections_map.nii.gz"))
+        
+    return disconnections_map, tdi_aggregated, tdi_disconnected