Metadata-Version: 2.4
Name: pyLQT
Version: 1.0.dev6
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)
