pyLQT 1.0.dev1__tar.gz → 1.0.dev2__tar.gz

pylqt-1.0.dev2/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: pyLQT
+Version: 1.0.dev2
+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
+Requires-Dist: networkx>3.6.1
+Dynamic: license-file
+
+# pyLQT
+
+pyLQT, standing for “Python Lesion Quantification Toolkit”, is a toolbox designed for analysis brain-lesioned patients scans with minimal resources, regrouping several metrics for lesion quantification. It is a sucessor to LQT [[1]](#ref1) which was originally developped on MATLAB and remastered on R [[2]](#ref2).
+
+The metrics are divided into three main domains:
+
+* **Grey matter:** lesion effects on grey-matter regions and parcels.
+* **White matter:** lesion effects on white-matter tracts and streamlines.
+* **Network:** lesion effects on structural or functional brain networks.
+
+## installation
+
+```bash
+pip install pyLQT
+```
+
+## Running pyLQT
+
+### Configuration files
+
+pyLQT uses three JSON configuration files to define the lesion cohort, atlas, and tractography dataset. Each file specifies the relevant data paths and reference space. For the simplest usage, only the lesion cohort configuration file is required, in which case the atlas and tractogram files are automatically downloaded.
+
+##### Lesion configuration
+
+Defines the lesion cohort, the folder containing the lesion NIfTI files, and their reference space.
+
+```json
+{
+    "cohort_name": "ExampleCohort",
+    "lesion_folder": "lesions",
+    "space": "MNI152NLin6Asym"
+}
+```
+
+##### Atlas configuration
+
+Specifies the atlas NIfTI file, its corresponding label CSV, and its reference space. The CSV must contain a `Parcel` column with parcel indices matching the atlas NIfTI and a `Label` column with the corresponding parcel names.
+
+```json
+{
+    "name": "glasser360",
+    "atlas": "glasser360.nii.gz",
+    "atlas_labels": "glasser360_labels.csv",
+    "space": "MNI152NLin2009cAsym"
+}
+```
+
+##### Tractography configuration
+
+Specifies the tractography dataset, the folder containing its `.trk` files, the folder containing its reference NIfTI files, and its reference space.
+
+```json
+{
+    "name": "HCP1065",
+    "tracts": "hcp1065_avg_tracts_trk",
+    "references": "hcp1065_avg_tracts",
+    "space": "MNI152NLin2009aAsym"
+}
+```
+
+**Notes:**
+- All paths are relative to the corresponding configuration file.
+- NIfTI files can be uncompressed (`.nii`) or gzipped (`.nii.gz`).
+- The `space` field can specify either a standard space supported by TemplateFlow (e.g., `MNI152NLin2009cAsym`) or a relative path to a reference NIfTI file (`.nii` or `.nii.gz`).
+- All paths and names above are examples and should be adapted to your dataset.
+
+### basic use
+
+Below is the simplest usage that only requires the [lesion cohort configuration file](#lesion-configuration). By default, the Glasser360 atlas and the HCP1065 tractogram are downloaded if not provided in the arguments.
+
+```bash
+pyLQT --lesion_cfg <path/to/lesion_config> --out_folder <path/to/outputs>
+```
+
+
+| Argument | Default | Options / Range | Description |
+|---|---|---|---|
+| `--lesion_cfg` | — | Path to a `.json` file | Path to the lesion cohort configuration file. |
+| `--atlas_cfg` | `None` | Path to a `.json` file or `None` | Path to the atlas configuration file. |
+| `--tracts_cfg` | `None` | Path to a `.json` file or `None` | Path to the tracts configuration file. |
+| `--out_folder` | — | Path to a directory | Path to the output folder. |
+| `--registration_type` | `syn` | `syn`, `affine` | Registration type used to transform the lesion and atlas from their respective spaces to tract space. |
+| `--spared_threshold` | `0.5` | Float between `0` and `1` | Threshold used to define spared parcel-to-parcel connectivity. |
+| `--delete_tmp` | `True` | `True`, `False` | Whether to delete temporary files generated during processing. |
+
+
+## Dependencies
+
+pyLQT relies on the following libraries:
+-    `numpy`
+-    `nibabel`
+-    `pandas`
+-    `scipy`
+-    `requests`
+-    `dipy`
+-    `templateflow`
+-    `networkx`
+
+
+## Links
+
+- [Source](https://github.com/AntoninHUDRY/pyLQT)
+- [documentation]() [TODO, deploy via github]
+- [PyPI](https://pypi.org/project/pyLQT/)
+
+## References
+
+<a id="ref1"></a>
+[1] Griffis et al. (2021). [Lesion Quantification Toolkit: A MATLAB software tool for estimating grey matter damage and white matter disconnections in patients with focal brain lesions](https://doi.org/10.1016/j.nicl.2021.102639). *NeuroImage: Clinical*.
+
+<a id="ref2"></a>
+[2] Dworkin Jordan (https://github.com/jdwor/LQT)

pylqt-1.0.dev2/README.md

@@ -0,0 +1,112 @@
+# pyLQT
+
+pyLQT, standing for “Python Lesion Quantification Toolkit”, is a toolbox designed for analysis brain-lesioned patients scans with minimal resources, regrouping several metrics for lesion quantification. It is a sucessor to LQT [[1]](#ref1) which was originally developped on MATLAB and remastered on R [[2]](#ref2).
+
+The metrics are divided into three main domains:
+
+* **Grey matter:** lesion effects on grey-matter regions and parcels.
+* **White matter:** lesion effects on white-matter tracts and streamlines.
+* **Network:** lesion effects on structural or functional brain networks.
+
+## installation
+
+```bash
+pip install pyLQT
+```
+
+## Running pyLQT
+
+### Configuration files
+
+pyLQT uses three JSON configuration files to define the lesion cohort, atlas, and tractography dataset. Each file specifies the relevant data paths and reference space. For the simplest usage, only the lesion cohort configuration file is required, in which case the atlas and tractogram files are automatically downloaded.
+
+##### Lesion configuration
+
+Defines the lesion cohort, the folder containing the lesion NIfTI files, and their reference space.
+
+```json
+{
+    "cohort_name": "ExampleCohort",
+    "lesion_folder": "lesions",
+    "space": "MNI152NLin6Asym"
+}
+```
+
+##### Atlas configuration
+
+Specifies the atlas NIfTI file, its corresponding label CSV, and its reference space. The CSV must contain a `Parcel` column with parcel indices matching the atlas NIfTI and a `Label` column with the corresponding parcel names.
+
+```json
+{
+    "name": "glasser360",
+    "atlas": "glasser360.nii.gz",
+    "atlas_labels": "glasser360_labels.csv",
+    "space": "MNI152NLin2009cAsym"
+}
+```
+
+##### Tractography configuration
+
+Specifies the tractography dataset, the folder containing its `.trk` files, the folder containing its reference NIfTI files, and its reference space.
+
+```json
+{
+    "name": "HCP1065",
+    "tracts": "hcp1065_avg_tracts_trk",
+    "references": "hcp1065_avg_tracts",
+    "space": "MNI152NLin2009aAsym"
+}
+```
+
+**Notes:**
+- All paths are relative to the corresponding configuration file.
+- NIfTI files can be uncompressed (`.nii`) or gzipped (`.nii.gz`).
+- The `space` field can specify either a standard space supported by TemplateFlow (e.g., `MNI152NLin2009cAsym`) or a relative path to a reference NIfTI file (`.nii` or `.nii.gz`).
+- All paths and names above are examples and should be adapted to your dataset.
+
+### basic use
+
+Below is the simplest usage that only requires the [lesion cohort configuration file](#lesion-configuration). By default, the Glasser360 atlas and the HCP1065 tractogram are downloaded if not provided in the arguments.
+
+```bash
+pyLQT --lesion_cfg <path/to/lesion_config> --out_folder <path/to/outputs>
+```
+
+
+| Argument | Default | Options / Range | Description |
+|---|---|---|---|
+| `--lesion_cfg` | — | Path to a `.json` file | Path to the lesion cohort configuration file. |
+| `--atlas_cfg` | `None` | Path to a `.json` file or `None` | Path to the atlas configuration file. |
+| `--tracts_cfg` | `None` | Path to a `.json` file or `None` | Path to the tracts configuration file. |
+| `--out_folder` | — | Path to a directory | Path to the output folder. |
+| `--registration_type` | `syn` | `syn`, `affine` | Registration type used to transform the lesion and atlas from their respective spaces to tract space. |
+| `--spared_threshold` | `0.5` | Float between `0` and `1` | Threshold used to define spared parcel-to-parcel connectivity. |
+| `--delete_tmp` | `True` | `True`, `False` | Whether to delete temporary files generated during processing. |
+
+
+## Dependencies
+
+pyLQT relies on the following libraries:
+-    `numpy`
+-    `nibabel`
+-    `pandas`
+-    `scipy`
+-    `requests`
+-    `dipy`
+-    `templateflow`
+-    `networkx`
+
+
+## Links
+
+- [Source](https://github.com/AntoninHUDRY/pyLQT)
+- [documentation]() [TODO, deploy via github]
+- [PyPI](https://pypi.org/project/pyLQT/)
+
+## References
+
+<a id="ref1"></a>
+[1] Griffis et al. (2021). [Lesion Quantification Toolkit: A MATLAB software tool for estimating grey matter damage and white matter disconnections in patients with focal brain lesions](https://doi.org/10.1016/j.nicl.2021.102639). *NeuroImage: Clinical*.
+
+<a id="ref2"></a>
+[2] Dworkin Jordan (https://github.com/jdwor/LQT)

{pylqt-1.0.dev1 → pylqt-1.0.dev2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "pyLQT"
 keywords = ["LQT", "lqt", "lesion", "brain", ""]
-version = "1.0.dev1"
+version = "1.0.dev2"
 authors = [
     {name="Antonin HUDRY", email="hudryantoninm@gmail.com"},
 ]
@@ -28,17 +28,18 @@ dependencies = [
     "requests>2.0",
     "dipy>1.10",
     "templateflow",
+    "networkx>3.6.1",
 ]
 
 license = "GPL-3.0-only"
 license-files = ["LICEN[CS]E*"]
 
 [project.scripts]
-pyLQT = "pyLQT_cli:run_pyLQT"
+pyLQT = "pyLQT.cli:main"
 
 [tool.setuptools]
 package-dir = {"" = "src"}
-py-modules = ["pyLQT_cli"]
+py-modules = ["pyLQT"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

pylqt-1.0.dev2/src/pyLQT/__init__.py

@@ -0,0 +1,3 @@
+from .pipeline import run_pyLQT
+
+__all__ = ["run_pyLQT"]

pylqt-1.0.dev2/src/pyLQT/cli.py

@@ -0,0 +1,71 @@
+import argparse
+
+from pipeline import run_pyLQT
+
+
+def main():
+    """Run the pyLQT pipeline through the command-line interface."""
+
+    parser = argparse.ArgumentParser(
+        prog="pyLQT",
+        description="Run the pyLQT lesion quantification pipeline."
+    )
+
+    parser.add_argument(
+        "--lesion_cfg",
+        required=True,
+        help='[Path] Path to lesion config'
+    )
+    
+    parser.add_argument(
+        "--atlas_cfg",
+        default=None,
+        help='[Path, optional] Path to atlas config. If none provided, a default atlas is downloaded.'
+    )
+    
+    parser.add_argument(
+        "--tracts_cfg",
+        default=None,
+        help='[Path, optional] Path to tracts config. If none provided, default tracts are downloaded.'
+    )
+    
+    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()
+
+    run_pyLQT(
+        lesion_cfg=args.lesion_cfg,
+        atlas_cfg=args.atlas_cfg,
+        tracts_cfg=args.tracts_cfg,
+        out_folder=args.out_folder,
+        registration_type=args.registration_type,
+        spared_threshold=args.spared_threshold,
+        delete_tmp=args.delete_tmp,
+    )
+
+
+if __name__ == "__main__":
+    main()

{pylqt-1.0.dev1/src → pylqt-1.0.dev2/src/pyLQT}/lesion_metrics/gray_matter/metrics.py

@@ -14,7 +14,7 @@ def get_parcel_damage(
     ):
     """Compute lesion damage for each parcel of an atlas.
 
-    The lesion is resampled to the atlas space, and the proportion of
+    The lesion is resampled to the atlas grid, 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.

{pylqt-1.0.dev1/src → pylqt-1.0.dev2/src/pyLQT}/lesion_metrics/utils/downloads.py

@@ -6,6 +6,7 @@ import shutil
 import gzip
 import nibabel as nib
 import numpy as np
+import pandas as pd
 
 from templateflow import api as tf
 from pathlib import Path
@@ -135,7 +136,72 @@ def uncompress_trk_gz(
 
     return out_path
 
-def default_download(out_folder: Path):
+def default_atlas_download(out_folder: Path):
+    atlas_cfg_folder = out_folder / "glasser360_config"
+    atlas_cfg_folder.mkdir(parents=True, exist_ok=True)
+    
+    atlas_path = atlas_cfg_folder / "glasser360_MNI152NLin2009cAsym.nii.gz"
+    atlas_labels_path = atlas_cfg_folder / "glasser360_labels.csv"
+    atlas_labels_path_txt = atlas_labels_path.with_suffix(".txt")
+    atlas_cfg_path = atlas_cfg_folder / "glasser360_config.json"
+    
+    if atlas_path.exists():
+        warnings.warn(
+            f"atlas already exists, using it: {atlas_path}"
+        )
+    else:
+        url_atlas = "https://ndownloader.figshare.com/files/43043653"
+        
+        response = requests.get(url_atlas, stream=True, timeout=60)
+        response.raise_for_status()
+        
+        with atlas_path.open("wb") as f:
+            for chunk in response.iter_content(chunk_size=1024*1024):
+                if chunk:
+                    f.write(chunk)
+
+    if atlas_labels_path.exists():
+        warnings.warn(
+            f"atlas labels already exist, using it: {atlas_labels_path}"
+        )
+    else:
+        url_labels =  "https://ndownloader.figshare.com/files/43041079"
+        
+        response = requests.get(url_labels, stream=True, timeout=60)
+        response.raise_for_status()
+        
+        with atlas_labels_path_txt.open("wb") as f:
+            for chunk in response.iter_content(chunk_size=1024*1024):
+                if chunk:
+                    f.write(chunk)
+
+        with open(atlas_labels_path_txt, "r") as f:
+            labels = [line.strip() for line in f if line.strip()]
+
+        atlas_labels = pd.DataFrame({
+            "Parcel": range(1, len(labels) + 1),
+            "Label": labels
+        })
+
+        atlas_labels.to_csv(atlas_labels_path, index=False)
+        atlas_labels_path_txt.unlink()
+
+    config = {
+        "name": "glasser360",
+        "atlas": "glasser360_MNI152NLin2009cAsym.nii.gz",
+        "atlas_labels": "glasser360_labels.csv",
+        "space": "MNI152NLin2009cAsym"
+    }
+            
+    atlas_cfg = Path(atlas_cfg_folder / "glasser360_config.json")
+            
+    with open(atlas_cfg, "w") as f:
+        json.dump(config, f, indent=4)
+        
+    return atlas_cfg
+    
+
+def default_tracts_download(out_folder: Path):
     """Download the default HCP1065 tractography dataset and create its configuration.
 
     The function downloads the HCP1065 average tractograms and their
@@ -162,7 +228,9 @@ def default_download(out_folder: Path):
         
     if tracts_folder.exists():
         warnings.warn(
-            f"Tracts folder already exists, using it: {tracts_folder}"
+            f"Tracts folder already exists, using it: {tracts_folder}",
+            UserWarning,
+            stacklevel=2
         )
     else:
         url = "https://github.com/data-others/atlas/releases/download/hcp1065/hcp1065_avg_tracts_trk.zip"
@@ -185,7 +253,9 @@ def default_download(out_folder: Path):
 
     if references_folder.exists():
         warnings.warn(
-            f"References folder already exists, using it: {references_folder}"
+            f"References folder already exists, using it: {references_folder}",
+            UserWarning,
+            stacklevel=2
         )
     else:
         url = "https://github.com/data-others/atlas/releases/download/hcp1065/hcp1065_avg_tracts_nifti.zip"
@@ -200,14 +270,13 @@ def default_download(out_folder: Path):
                     f.write(chunk)
 
         with zipfile.ZipFile(zip_path) as zip_file:
-            zip_file.extractall(zip_path.parent)
+            zip_file.extractall(tracts_cfg_folder)
 
         zip_path.unlink()
 
-        references_folder = zip_path.parent / "nifti"
-        references_folder.rename(
-            zip_path.parent / "hcp1065_avg_tracts"
-        )
+        extracted_niftis = tracts_cfg_folder / "nifti"
+        if extracted_niftis.exists():
+            extracted_niftis.rename(references_folder)
             
     tracts_name = "HCP1065"
     tracts_space = "MNI152NLin2009aAsym"
@@ -247,4 +316,8 @@ def get_ref_space_tf(space: str, res: int = 1):
     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
+    return ref_space
+
+if __name__=="__main__":
+    
+    default_atlas_download(Path("D:/internship_myspace_lab/pyLQT/test_download_atlas"))

{pylqt-1.0.dev1/src → pylqt-1.0.dev2/src/pyLQT}/lesion_metrics/utils/registration.py

@@ -26,14 +26,18 @@ def register_affine(
     AffineMap
         Affine mapping from the moving image space to the static image space.
     """
-    metric = MutualInformationMetric()
+    
+    moving_data = moving.get_fdata()
+    static_data = static.get_fdata()
+    
+    metric = MutualInformationMetric(nbins=32, sampling_proportion=0.2)
 
-    affreg = AffineRegistration(metric=metric)
+    affreg = AffineRegistration(metric=metric, level_iters=[500, 250, 100])
 
     transform = TranslationTransform3D()
     translation = affreg.optimize(
-        static.get_fdata(),
-        moving.get_fdata(),
+        static_data,
+        moving_data,
         transform,
         params0=None,
         static_grid2world=static.affine,
@@ -42,8 +46,8 @@ def register_affine(
 
     transform = RigidTransform3D()
     rigid = affreg.optimize(
-        static.get_fdata(),
-        moving.get_fdata(),
+        static_data,
+        moving_data,
         transform,
         starting_affine=translation.affine,
         params0=None,
@@ -53,8 +57,8 @@ def register_affine(
 
     transform = AffineTransform3D()
     mapping = affreg.optimize(
-        static.get_fdata(),
-        moving.get_fdata(),
+        static_data,
+        moving_data,
         transform,
         starting_affine=rigid.affine,
         params0=None,
@@ -93,7 +97,7 @@ def register_syn(
     """
     metric = CCMetric(dim=3)
 
-    syn = SymmetricDiffeomorphicRegistration(metric)
+    syn = SymmetricDiffeomorphicRegistration(metric, level_iters=[20, 10, 5])
 
     mapping = syn.optimize(static.get_fdata(),
                            moving.get_fdata(),