pyLQT 1.0.dev1__py3-none-any.whl

lesion_metrics/white_matter/utils.py

@@ -0,0 +1,244 @@
+import numpy as np
+import nibabel as nib
+import dipy.io.stateful_surface
+
+from dipy.io.stateful_tractogram import StatefulTractogram
+from dipy.io.utils import Space
+from dipy.io.streamline import load_tractogram, save_tractogram
+from dipy.tracking.utils import target, density_map
+
+def get_tract(
+    tract_path,
+    reference_path = None
+    ):
+    """Load a tractogram with the possibility of assigning a new 
+    NIfTI reference. The reference should be in the same world space
+    as the tractogram.
+
+    Parameters
+    ----------
+    tract_path : Path
+        Path to the tractogram file.
+    reference_path : Path | None, optional
+        Path to a NIfTI image to use as the tractogram reference.
+        If provided, the tractogram is reconstructed in RASMM space
+        using this reference.
+
+    Returns
+    -------
+    StatefulTractogram
+        Loaded tractogram, optionally associated with the provided
+        reference image.
+    """
+    
+    tract = load_tractogram(filename=tract_path, 
+                            reference="same",
+                            bbox_valid_check=False)
+    if reference_path:
+        reference = nib.nifti1.load(reference_path)
+        tract = StatefulTractogram(tract.streamlines,
+                                   reference=reference,
+                                   space=Space.RASMM)
+    return tract
+    
+
+def get_aggregated_tracts(
+    tracts_pathlist,
+    reference_path = None,
+    out_path = None
+    ):
+    """Aggregate multiple tractograms into a single tractogram.
+
+    Parameters
+    ----------
+    tracts_pathlist : list[Path]
+        Paths to the tractogram files to aggregate.
+    reference_path : Path | None, optional
+        Path to a NIfTI image to use as the reference for all tractograms.
+        If not provided, the first loaded tractogram is used as the reference.
+    out_path : Path | None, optional
+        Path where the aggregated tractogram should be saved. If None,
+        the tractogram is not saved.
+
+    Returns
+    -------
+    StatefulTractogram
+        Aggregated tractogram containing the streamlines from all input
+        tractograms, clipped to the reference image grid.
+    """
+
+    streamlines = []
+    
+    if reference_path:
+        reference = nib.nifti1.load(reference_path)
+    else:
+        reference = None
+
+    for tract_path in tracts_pathlist:
+        tract = get_tract(tract_path, reference)
+        streamlines.extend(tract.streamlines)
+
+    if reference is None:
+        reference = tract
+    aggregated_tracts = StatefulTractogram(streamlines,
+                                           reference,
+                                           space=Space.RASMM)
+
+    aggregated_tracts = clip_tractogram_to_grid(aggregated_tracts)
+
+    if out_path:
+        save_tractogram(aggregated_tracts,
+                        out_path,
+                        bbox_valid_check=False,)
+
+    return aggregated_tracts
+
+def clip_streamline_to_grid(
+    streamline,
+    inv_affine,
+    shape
+    ):
+    """Clip a streamline to the voxel grid of a reference image.
+
+    Parameters
+    ----------
+    streamline : ndarray
+        Streamline coordinates in world space.
+    inv_affine : ndarray
+        Inverse affine transformation from world space to voxel space.
+    shape : tuple
+        Shape of the reference image grid.
+
+    Returns
+    -------
+    ndarray
+        Streamline containing only the points that fall within the voxel grid.
+    """
+    
+    voxel = np.column_stack((
+        streamline,
+        np.ones(len(streamline))
+    )) @ inv_affine.T
+
+    voxel = voxel[:, :3]
+
+    valid = np.all(
+        (voxel >= 0) &
+        (voxel < shape),
+        axis=1
+    )
+
+    return streamline[valid]
+
+
+def clip_tractogram_to_grid(tract):
+    """Clip a tractogram to the voxel grid of its reference space.
+
+    Parameters
+    ----------
+    tract : StatefulTractogram
+        Tractogram to clip. Its streamlines are expected to be in the
+        same world space as its reference image.
+
+    Returns
+    -------
+    StatefulTractogram
+        Tractogram containing only streamline points within the reference
+        voxel grid. Streamlines with fewer than two remaining points are
+        removed.
+    """
+    
+    inv_affine = np.linalg.inv(tract.affine)
+    shape = np.asarray(tract.space_attributes[1])
+
+    clipped_streamlines = [
+        clip_streamline_to_grid(
+            streamline,
+            inv_affine,
+            shape
+        )
+        for streamline in tract.streamlines
+    ]
+
+    clipped_streamlines = [
+        streamline
+        for streamline in clipped_streamlines
+        if len(streamline) >= 2
+    ]
+
+    return StatefulTractogram.from_sft(clipped_streamlines, tract)
+
+def get_streamlines_disconnection(
+    tract,
+    lesion,
+    out_path=None
+):
+    """Return the streamlines intersecting a lesion and compute the proportion 
+    of streamlines intersecting this lesion.
+
+    Parameters
+    ----------
+    tract : dipy.io.stateful_tractogram.StatefulTractogram
+        Tractogram from which to identify intersecting streamlines.
+    lesion : nib.Nifti1Image
+        NIfTI lesion. Converted to binary mask where voxels with values
+        greater than zero are considered part of the lesion.
+    out_path : Path | None, optional
+        Path where the disconnected streamlines should be saved. If None,
+        the tractogram is not saved.
+
+    Returns
+    -------
+    dipy.io.stateful_tractogram.StatefulTractogram
+        Tractogram of the intersecting streamlines.
+    float
+        Proportion of streamlines that intersect the lesion, between 0 and 1.
+    """
+
+    lesion_mask = lesion.get_fdata() > 0
+
+    disconnected_streamlines = list(
+        target(tract.streamlines, lesion.affine, lesion_mask)
+    )
+
+    disconnected_tract = StatefulTractogram.from_sft(
+                disconnected_streamlines,
+                tract
+            )
+
+    if out_path:
+        save_tractogram(
+            disconnected_tract,
+            out_path,
+            bbox_valid_check=False
+        )
+
+    return disconnected_tract, len(disconnected_streamlines) / len(tract.streamlines)
+
+def get_tdi(
+    tract,
+    out_path = None
+    ):
+    """Compute a track density image (TDI) from a tractogram.
+
+    Parameters
+    ----------
+    tract : StatefulTractogram
+        Tractogram from which to compute the track density image.
+    out_path : Path | None, optional
+        Path where the TDI NIfTI image should be saved. If None, the image
+        is not saved.
+
+    Returns
+    -------
+    nib.Nifti1Image
+        NIfTI image containing the number of streamlines passing through
+        each voxel.
+    """
+    
+    tdi = density_map(tract.streamlines, tract.affine, tract.space_attributes[1])
+    tdi = nib.Nifti1Image(tdi.astype("uint32"), tract.affine)
+    if out_path:
+        nib.nifti1.save(tdi, out_path)
+    
+    return tdi

pyLQT_cli.py

@@ -0,0 +1,180 @@
+from lesion_metrics.white_matter.metrics import get_tracts_disconnections_severity, get_tracts_disconnections_map
+from lesion_metrics.white_matter.utils import get_streamlines_disconnection, get_aggregated_tracts, clip_tractogram_to_grid
+from lesion_metrics.network.metrics import get_sspl_increase, get_parcel_wise_disconnection_severity
+from lesion_metrics.gray_matter.metrics import get_parcel_damage
+from lesion_metrics.utils.configs import atlas_cfg_read, tracts_cfg_read, lesion_cfg_read
+from lesion_metrics.utils.downloads import default_download, create_tract_list, uncompress_trk_gz, get_ref_space_tf
+from lesion_metrics.utils.registration import register_affine, register_syn
+from pathlib import Path
+
+import nibabel as nib
+import shutil
+import tempfile
+import argparse
+
+
+def run_pyLQT():
+    """Run the pyLQT lesion quantification pipeline.
+
+    Parses the command-line arguments, loads the lesion, atlas, and
+    tractography configurations, performs the required registrations,
+    and computes the different lesion quantification measures.
+    """
+    
+    parser = argparse.ArgumentParser()
+    
+    parser.add_argument(
+        "--lesion_cfg",
+        required=True,
+        help='[Path] Path to lesion config'
+    )
+    
+    parser.add_argument(
+        "--atlas_cfg",
+        required=True,
+        help='[Path] Path to atlas config'
+    )
+    
+    parser.add_argument(
+        "--tracts_cfg",
+        default=None,
+        help='[Path] Path to tracts config'
+    )
+    
+    parser.add_argument(
+        "--out_folder",
+        required=True,
+        help='[Path] Output folder path'
+    )
+    
+    parser.add_argument(
+        "--registration_type",
+        choices=['affine', 'syn'],
+        default='syn',
+        help='[str, default=syn] Registration type, from lesion space and atlas space to tract space'
+    )
+    
+    parser.add_argument(
+        "--spared_threshold",
+        default=0.5,
+        help='[float (0,1), default=0.5] Defines threshold for spared parcel-to-parcel connectivity'
+    )
+    
+    parser.add_argument(
+        "--delete_tmp",
+        default=False,
+        help='[bool, default=False] Delete temporary folder'
+    )
+
+    args = parser.parse_args()
+    
+    out_folder = Path(args.out_folder)
+    out_folder.mkdir(parents=True, exist_ok=True)
+    tmp_folder = Path(tempfile.mkdtemp(prefix="LQT_tmp_", dir=out_folder))
+    
+    lesion_cfg_path = Path(args.lesion_cfg)
+    atlas_cfg_path = Path(args.atlas_cfg)
+    if not args.tracts_cfg:
+        tracts_cfg_path = default_download(out_folder)
+    else: 
+        tracts_cfg_path = Path(args.tracts_cfg)
+    
+    lesion_cohort_name, lesion_folder, lesion_space = lesion_cfg_read(lesion_cfg_path)
+    atlas_name, atlas, atlas_labels, atlas_space = atlas_cfg_read(atlas_cfg_path)
+    tracts_name, tracts_folder, references_folder, tracts_space = tracts_cfg_read(tracts_cfg_path)
+    
+    if lesion_space.endswith(".nii.gz") or lesion_space.endswith(".nii"):
+        lesion_ref_space = nib.nifti1.load(lesion_space)
+    else: lesion_ref_space = get_ref_space_tf(lesion_space)
+    if atlas_space.endswith(".nii.gz") or atlas_space.endswith(".nii"):
+        atlas_ref_space = nib.nifti1.load(atlas_space)
+    else: atlas_ref_space = get_ref_space_tf(atlas_space)
+    if tracts_space.endswith(".nii.gz") or tracts_space.endswith(".nii"):
+        tracts_ref_space = nib.nifti1.load(tracts_space)
+    else: tracts_ref_space = get_ref_space_tf(tracts_space)
+    
+    if args.registration_type == "affine":
+        registrator = register_affine
+    else:
+        registrator = register_syn
+    lesion_tracts_mapping = registrator(lesion_ref_space, tracts_ref_space)
+    atlas_tracts_mapping = registrator(atlas_ref_space, tracts_ref_space)
+    
+    atlas_trans_volume = atlas_tracts_mapping.transform(atlas.get_fdata(), interpolation='nearest')
+    atlas_trans = nib.Nifti1Image(atlas_trans_volume, tracts_ref_space.affine, tracts_ref_space.header)
+    nib.nifti1.save(atlas_trans, tmp_folder / "atlas_trans.nii.gz")
+    
+    spared_threshold = float(args.spared_threshold)
+    tracts_pathlist_gz, references_pathlist = create_tract_list(references_folder=references_folder,
+                                                                tracts_folder=tracts_folder)
+    
+    tracts_pathlist = []
+    for tract_path in tracts_pathlist_gz:
+        relative_path = tract_path.relative_to(tracts_folder)
+        out_path = tmp_folder / relative_path.with_suffix("")
+
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        tracts_pathlist.append(
+            uncompress_trk_gz(tract_path, out_path)
+        )
+    
+    aggregated_tracts_path = tmp_folder / "aggregated_tracts.trk"
+    aggregated_tracts = get_aggregated_tracts(tracts_pathlist=tracts_pathlist,
+                                              out_path=aggregated_tracts_path)
+    
+    for lesion_path in lesion_folder.glob("*.nii*"):
+        
+        lesion_name = lesion_path.name.removesuffix(".nii.gz").removesuffix(".nii")
+        out_dir = out_folder / lesion_name
+        out_dir.mkdir(parents=True, exist_ok=True)
+        tmp_dir = tmp_folder / lesion_name
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        
+        lesion = nib.nifti1.load(lesion_path)
+        lesion_trans_volume = lesion_tracts_mapping.transform(lesion.get_fdata(), interpolation='linear')
+        lesion_trans = nib.Nifti1Image(lesion_trans_volume, tracts_ref_space.affine, tracts_ref_space.header)
+        nib.nifti1.save(lesion_trans, tmp_dir / "lesion_trans.nii.gz")
+
+        aggregated_tracts_disconnected_path = tmp_dir / f"aggregated_disconnected.trk"
+        aggregated_tracts_disconnected, _ = get_streamlines_disconnection(tract=aggregated_tracts,
+                                                                          lesion=lesion_trans,
+                                                                          out_path=aggregated_tracts_disconnected_path)
+        aggregated_tracts_disconnected = clip_tractogram_to_grid(aggregated_tracts_disconnected)
+        
+        get_parcel_damage(lesion=lesion_trans, 
+                          atlas=atlas_trans, 
+                          atlas_labels=atlas_labels,
+                          parcel_column="Parcel",
+                          out_path=out_dir / "parcel_damage")
+        
+        get_tracts_disconnections_severity(tracts_path=tracts_pathlist,
+                                           references_path=references_pathlist,
+                                           lesion=lesion_trans,
+                                           disc_tracts_out_path=tmp_dir / "wm_disconnections_severity",
+                                           disc_frame_out_path=out_dir / "wm_disconnections_severity")
+        
+        get_tracts_disconnections_map(tracts=aggregated_tracts,
+                                      tracts_disconnected=aggregated_tracts_disconnected,
+                                      out_path=out_dir / "wm_disconnections_map")
+        
+        structural_connectivity, _, _, per_spared_connections = (
+            get_parcel_wise_disconnection_severity(
+                aggregated_tracts=aggregated_tracts,
+                aggregated_tracts_disconnected=aggregated_tracts_disconnected,
+                atlas=atlas_trans,
+                out_path=out_dir / "parcel_wise_disconnection_severity",
+            )
+        )
+        
+        get_sspl_increase(structural_connectivity=structural_connectivity,
+                          per_spared_connections=per_spared_connections,
+                          out_path=out_dir / "sspl_increase",
+                          spared_threshold=spared_threshold)
+
+    if args.delete_tmp == True:
+        shutil.rmtree(tmp_folder)
+        
+        
+if __name__ == "__main__":
+    run_pyLQT()

pylqt-1.0.dev1.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: pyLQT
+Version: 1.0.dev1
+Summary: Python version of LQT from Griffis et al. 2021 (https://www.sciencedirect.com/science/article/pii/S2213158221000838)
+Author-email: Antonin HUDRY <hudryantoninm@gmail.com>
+License-Expression: GPL-3.0-only
+Keywords: LQT,lqt,lesion,brain,
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Programming Language :: Python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0
+Requires-Dist: nibabel>5.0
+Requires-Dist: pandas>3.0
+Requires-Dist: scipy>1.15
+Requires-Dist: requests>2.0
+Requires-Dist: dipy>1.10
+Requires-Dist: templateflow
+Dynamic: license-file
+
+# pyLQT
+Python library to revamp the work on LQT, since it is no longer actively maintained. 
+
+# install
+
+Make sure to update your python environment with the `requirements.txt`: `pip install -r requirements.txt`
+
+# Running pyLQT
+
+The main pyLQT pipeline can be run using the `full_pipeline.py` file.
+
+### Usage
+
+```bash
+python full_pipeline.py \
+    --lesion_cfg <path/to/lesion_config> \
+    --atlas_cfg <path/to/atlas_config> \
+    --tracts_cfg <path/to/tracts_config> \
+    --out_folder <path/to/output> \
+    --spared_threshold 
+```
+
+| Argument             | Required | Default | Description                                                                                                                |
+| -------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `--lesion_cfg`    | Yes      | —       | Path to the lesion configuration file (`.json`).                                   |
+| `--atlas_cfg`        | Yes      | —       | Path to the atlas configuration file (`.json`).                                                                                      |
+| `--tracts_cfg`           | No       | `None`  | Path to the tracts configuration file (`.json`).                        |
+| `--out_folder`       | Yes      | —       | Path to the output folder.                                                                                                 |
+| `--spared_threshold` | No       | `0.5`   | Threshold between 0 and 1 used to define spared parcel-to-parcel connectivity.                                             |
+| `--delete_tmp`       | No       | `True`  | Whether to delete the temporary files generated during processing.                                                         |
+
+### Configuration files
+
+The CLI version of pyLQT relies on 3 configuration files, one for the lesions, one for the atlas and one for the tracts:
+
+- Lesions: "cohort_name": name of the cohort of lesion used mainly for the naming of subsequent files; "lesion_folder": relative folder (should be next the config file) containing all the lesion niftis. The folder is scanned integrally so that all niftis in the folder and subfolders are processed; "space": world space in which the lesion are registered, can be a nifti directly given as relative path (with extensions) or a standard space name that will be fetched via templateflow (i.e. MNI152NLin2009cAsym).
+- Atlas: "name": name of the atlas used mainly for naming subsequent files; "atlas": relative path to nifti file corresponding to atlas; "atlas_labels": relative path to `.csv` file containing the labels of the atlas. Format should contain columns "Parcel" and "Label", corresponding to the parcel number inside the nifti and the name of the parcel respectively; "space": world space in which the lesion are registered, can be a nifti directly given as relative path (with extensions) or a standard space name that will be fetched via templateflow (i.e. MNI152NLin2009cAsym).
+
+Note: niftis can be given as raw or gzipped niftis (`.nii` or `.nii.gz`)

pylqt-1.0.dev1.dist-info/RECORD

@@ -0,0 +1,21 @@
+pyLQT_cli.py,sha256=FlTLPGcoq-xwPeGwVUfe_W_dg8yMpYV1X1jPBf-EefA,7937
+lesion_metrics/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lesion_metrics/gray_matter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lesion_metrics/gray_matter/metrics.py,sha256=RzUS9glbin9Xn5ZldB7fGg2XiPS1P21e_7l02ZErk-I,2617
+lesion_metrics/gray_matter/utils.py,sha256=czxyAESP0neVCue424L0hon-5Tdbsl0pN0zJHWG5HiQ,840
+lesion_metrics/network/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lesion_metrics/network/metrics.py,sha256=Ka3G8_dIq-8H3b8mvRR96QM7p_gR2yFLKUxQOLYMWM4,8281
+lesion_metrics/network/utils.py,sha256=fcakfKSMortNIE3TfJP8zwanzBiT1McsYnHcTgwbxE4,3283
+lesion_metrics/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lesion_metrics/utils/configs.py,sha256=FFur04Sh48IlxUTmz4kRkyLKWffi7bvzyw8B2GclpRU,4961
+lesion_metrics/utils/downloads.py,sha256=yu-rcuIDcgsDa7gxoLGyIewsk2DF2WGgCYe5bCOso0M,8031
+lesion_metrics/utils/registration.py,sha256=rB4vEMBrlshofOxaKrSqyE3Wvgq2_o3y5T3dCS_9sM0,3174
+lesion_metrics/white_matter/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lesion_metrics/white_matter/metrics.py,sha256=sujuHry19XpVWFNo52Ntq7h3JkWEcgsZ1-rNFr7E940,6155
+lesion_metrics/white_matter/utils.py,sha256=oo492yzxsPACMvHEyYhoYVqgVRrv8mpqP7FOf5OU_Ms,7087
+pylqt-1.0.dev1.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+pylqt-1.0.dev1.dist-info/METADATA,sha256=gMSuT2w08jR1QSTH_C9TRsLVsJBEnCh98jSDH4_eCGs,3990
+pylqt-1.0.dev1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pylqt-1.0.dev1.dist-info/entry_points.txt,sha256=1mhG9fCXeDnL9VEBbsIN34GU90953e85325pG_wo6l8,46
+pylqt-1.0.dev1.dist-info/top_level.txt,sha256=KT_xuwXScSnV5QoZAXnCzeTOq23xQ_V9ESEh4jrfxBM,25
+pylqt-1.0.dev1.dist-info/RECORD,,

pylqt-1.0.dev1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pylqt-1.0.dev1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyLQT = pyLQT_cli:run_pyLQT