Metadata-Version: 2.4
Name: clabtoolkit
Version: 0.5.3
Summary: A comprehensive toolkit for neuroimaging data processing and analysis
Author-email: Yasser Alemán-Gómez <yasseraleman@protonmail.com>
Maintainer-email: Yasser Alemán-Gómez <yasseraleman@protonmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/connectomicslab/clabtoolkit
Project-URL: Repository, https://github.com/connectomicslab/clabtoolkit
Project-URL: Documentation, https://clabtoolkit.readthedocs.io
Project-URL: Bug Tracker, https://github.com/connectomicslab/clabtoolkit/issues
Keywords: neuroimaging,image-processing,bids,freesurfer,connectivity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: NOTICE
License-File: AUTHORS.rst
Requires-Dist: nibabel>=5.3.2
Requires-Dist: numpy>=1.23.5
Requires-Dist: pandas>=2.3.1
Requires-Dist: pydicom>=3.0.1
Requires-Dist: rich>=14.1.0
Requires-Dist: scipy>=1.16.0
Requires-Dist: setuptools>=80.9.0
Requires-Dist: scikit-image>=0.25.2
Requires-Dist: h5py>=3.14.0
Requires-Dist: matplotlib>=3.10.3
Requires-Dist: pyvista>=0.45.3
Requires-Dist: nilearn>=0.12.0
Requires-Dist: joblib>=1.5.1
Requires-Dist: colorama>=0.4.6
Requires-Dist: dipy>=1.11.0
Requires-Dist: screeninfo>=0.8.1
Requires-Dist: ipython>=8.0.0
Requires-Dist: bctpy>=0.6.1
Provides-Extra: dev
Requires-Dist: pytest>=8.4.1; extra == "dev"
Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: ruff>=0.12.5; extra == "dev"
Requires-Dist: mypy>=1.17.0; extra == "dev"
Requires-Dist: pre-commit>=4.2.0; extra == "dev"
Requires-Dist: tox>=4.28.1; extra == "dev"
Requires-Dist: termcolor>=3.1.0; extra == "dev"
Requires-Dist: tabulate>=0.9.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: itables>=2.8.0; extra == "examples"
Provides-Extra: docs
Requires-Dist: sphinx>=8.2.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0.2; extra == "docs"
Requires-Dist: myst-parser>=4.0.1; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8.4.1; extra == "test"
Requires-Dist: pytest-cov>=6.2.1; extra == "test"
Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
Dynamic: license-file

========================
Connectomics Lab Toolkit
========================

.. image:: https://raw.githubusercontent.com/connectomicslab/clabtoolkit/main/docs/source/_static/clabtoolkit_logo.png
        :alt: clabtoolkit logo
        :align: center
        :width: 400


.. image:: https://img.shields.io/pypi/v/clabtoolkit.svg
        :target: https://pypi.python.org/pypi/clabtoolkit
        :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/clabtoolkit.svg
        :target: https://pypi.python.org/pypi/clabtoolkit
        :alt: Python versions

.. image:: https://img.shields.io/badge/License-Apache_2.0-blue.svg
        :target: https://opensource.org/licenses/Apache-2.0
        :alt: License: Apache 2.0

.. image:: https://github.com/connectomicslab/clabtoolkit/actions/workflows/ci.yml/badge.svg
        :target: https://github.com/connectomicslab/clabtoolkit/actions/workflows/ci.yml
        :alt: CI status

.. image:: https://codecov.io/gh/connectomicslab/clabtoolkit/branch/main/graph/badge.svg
        :target: https://codecov.io/gh/connectomicslab/clabtoolkit
        :alt: Code coverage

.. image:: https://app.readthedocs.org/projects/clabtoolkit/badge/?version=latest
        :target: https://clabtoolkit.readthedocs.io/en/latest/?version=latest
        :alt: Documentation Status

.. image:: https://img.shields.io/badge/arXiv-2607.02638-b31b1b.svg
        :target: https://arxiv.org/abs/2607.02638
        :alt: arXiv

.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.23540587.svg
        :target: https://doi.org/10.5281/zenodo.23540587
        :alt: Zenodo DOI


**clabtoolkit** (Connectomics Lab Toolkit) is a Python toolkit for neuroimaging data processing
and analysis, with a focus on brain connectivity, BIDS datasets and common neuroimaging formats.

It is built around a small set of objects (``Surface``, ``Parcellation``, ``Tractogram`` and
``Connectome``) that share a common plotting layer (``BrainPlotter``), so surfaces, parcellations,
streamlines and connectivity matrices can be loaded, processed and visualized with a consistent API.
It is designed to work alongside libraries such as nibabel, nilearn and DIPY.

* **Free software**: Apache Software License 2.0
* **Documentation**: https://clabtoolkit.readthedocs.io
* **Source code**: https://github.com/connectomicslab/clabtoolkit

Installation
------------

Install from PyPI::

    pip install clabtoolkit

For a development installation::

    git clone https://github.com/connectomicslab/clabtoolkit.git
    cd clabtoolkit
    pip install -e ".[dev]"

Requirements and optional dependencies:

* Python 3.11 or newer.
* 3D plotting (``visualizationtools``) uses PyVista and needs either a display or off-screen
  rendering (for example ``PYVISTA_OFF_SCREEN=true`` on a server).
* FreeSurfer is **not** required. If it is installed and ``FREESURFER_HOME`` is set, the example
  notebooks use its sample subjects; otherwise they run on simulated data.

Features
--------

.. image:: https://raw.githubusercontent.com/connectomicslab/clabtoolkit/main/docs/source/_static/clabtoolkit_ecosystem.png
        :alt: clabtoolkit ecosystem
        :align: center
        :width: 700

Every module has a notebook with runnable examples in the
`usage_examples <https://github.com/connectomicslab/clabtoolkit/tree/main/usage_examples>`_ folder
(``examples-<module>-methods.ipynb``), and
`clabtoolkit_examples.ipynb <https://github.com/connectomicslab/clabtoolkit/blob/main/usage_examples/clabtoolkit_examples.ipynb>`_
gives an overview of the whole toolkit.

**Data organization**

* **BIDS Tools** (``clabtoolkit.bidstools``): entity extraction and editing in BIDS filenames,
  BIDS tree generation and validation, derivatives discovery.
* **DICOM Tools** (``clabtoolkit.dicomtools``): DICOM organization, compression and metadata extraction.
* **Pipeline Tools** (``clabtoolkit.pipelinetools``): processing-status tables and inventories of
  derivatives, with JSON and SQLite export.

**Images and diffusion**

* **Image Tools** (``clabtoolkit.imagetools``): voxel/world conversions, cropping, morphology,
  interpolation, 4D volume handling and image simulation.
* **DWI Tools** (``clabtoolkit.dwitools``): volume removal by index or b-value, B0 extraction,
  acquisition schemes from bvec/bval files, q-space visualization and tensor-derived maps (FA, MD, AD, RD).
* **Tract Tools** (``clabtoolkit.tracttools``): the ``Tractogram`` class, with streamline filtering,
  resampling, image interpolation along streamlines, merging and TRK/TCK conversion.
* **Segmentation Tools** (``clabtoolkit.segmentationtools``): atlas-based parcellation and tissue
  segmentation tables.

**Surfaces and parcellations**

* **Surface Tools** (``clabtoolkit.surfacetools``): the ``Surface`` class, with scalar maps, annotations,
  volume-to-surface mapping, smoothing and export.
* **Parcellation Tools** (``clabtoolkit.parcellationtools``): the ``Parcellation`` class, with region
  selection by name or code, centroids, volumes, region-wise time series and functional connectivity.
* **FreeSurfer Tools** (``clabtoolkit.freesurfertools``): FreeSurfer subjects, annotations, statistics
  tables and transforms.
* **Morphometry Tools** (``clabtoolkit.morphometrytools``): region-wise area, volume and Euler number,
  and parsing of FreeSurfer statistics.
* **Point Tools** (``clabtoolkit.pointstools``): point clouds, merging and curve smoothing.

**Connectivity and networks**

* **Connectivity Tools** (``clabtoolkit.connectivitytools``): the ``Connectome`` class, with thresholding,
  graph metrics, matrix plotting, 3D visualization and CSV/HDF5 I/O.
* **Network Tools** (``clabtoolkit.networktools``): sparse-matrix conversion and connected components.

**Visualization and utilities**

* **Visualization Tools** (``clabtoolkit.visualizationtools``): ``BrainPlotter`` for surfaces, tractograms
  and volumes, multi-view layouts and carpet plots.
* **Plot Tools** (``clabtoolkit.plottools``): figure layout and font helpers for the plotting classes.
* **Colors Tools** (``clabtoolkit.colorstools``): color validation, RGB/hex conversion and color tables.
* **Quality Control Tools** (``clabtoolkit.qcqatools``): slice generation and HTML pages for visual quality control.
* **Misc Tools** (``clabtoolkit.misctools``): condition-based selection and general-purpose helpers.

Quick Start
-----------

The examples below are self-contained: they use simulated data, so you can run them as they are.

**Filter a parcellation by region name** (``keep_by_name``)

.. code-block:: python

    import clabtoolkit.parcellationtools as cltparc

    # Simulate a parcellation with 10 regions and name them
    parc = cltparc.Parcellation.simulate_parcellation(n_regions=10, seed=42)
    parc.set_names(['ctx-rh-precentral', 'ctx-lh-precentral', 'ctx-rh-postcentral', 'ctx-lh-postcentral',
                    'ctx-rh-superiorfrontal', 'ctx-lh-superiorfrontal', 'ctx-rh-supramarginal',
                    'ctx-lh-supramarginal', 'subc-rh-amygdala', 'subc-lh-amygdala'])

    # Keep only the precentral regions (the object is modified in place)
    parc.keep_by_name(['ctx-rh-precentral', 'ctx-lh-precentral'])
    print(parc.name)  # ['ctx-rh-precentral', 'ctx-lh-precentral']

To load your own parcellation, use ``cltparc.Parcellation("parc.nii.gz", color_table="lut.txt")``.

.. note::

   If a file called ``parc.lut`` is in the same directory as the parcellation, it is used as the
   color table by default, so ``cltparc.Parcellation("parc.nii.gz")`` is enough. As long as they 
   share the same base name, the LUT file will be automatically detected.

**Sample an image along the streamlines of a tractogram** (``interpolate_on_tractogram``)

.. code-block:: python

    import os
    import tempfile

    import clabtoolkit.imagetools as cltimg
    import clabtoolkit.tracttools as clttract

    image_path = os.path.join(tempfile.gettempdir(), "image.nii.gz")

    # Simulate a reference image and a tractogram with 5 bundles
    cltimg.simulate_image(reference=(100, 100, 70), simulated_image=image_path)
    tract = clttract.Tractogram.simulate_tractogram(ref_image=image_path)

    # Sample the image at every point of every streamline
    tract.interpolate_on_tractogram(image_path, map_name="fa",
                                    storage_mode="data_per_point", interp_method="linear")

    print(tract.list_maps()["maps_per_point"])  # ['fa']
    print(tract.data_per_point["fa"][0][:5])    # values along the first streamline

Use ``storage_mode="data_per_streamline"`` with ``reduction="mean"`` to store a single value per streamline.

**Plot a surface with a scalar map** (``BrainPlotter``)

.. code-block:: python

    import clabtoolkit.surfacetools as cltsurf
    import clabtoolkit.visualizationtools as cltvis

    # On a server without a display, set PYVISTA_OFF_SCREEN=true before running

    # Simulate a surface and a thickness map
    surf = cltsurf.Surface.simulate_surface(seed=42, shape="sphere")
    surf.simulate_map(map_name="thickness")

    # Option 1 (Surface object): plot the lateral and medial views of the map
    surf.plot(views=["lateral", "medial"],
              maps="thickness",
              colorbar_title="Thickness (mm)")

    # Option 2 (BrainPlotter): the same plot, with more control over colormaps and colorbars
    plotter = cltvis.BrainPlotter()
    plotter.plot(objs2plot=surf,
                 views=["lateral", "medial"],
                 map_names="thickness",
                 colormaps="hot",
                 colorbar=True,
                 colorbar_titles="Thickness (mm)")

To plot your own data, load a surface with ``cltsurf.Surface("lh.pial")`` and its map with
``surf.load_scalar_maps("lh.thickness", maps_names="thickness")``.

Citing
------

If you use clabtoolkit in your work, please cite the toolkit paper:

    Alemán-Gómez, Y., et al. CLABTOOLKIT: An Open-Source Toolkit for Routine Processing, Manipulation, and Visualization of Neuroimaging Data. arXiv:2607.02638.
    https://arxiv.org/abs/2607.02638

.. code-block:: bibtex

    @article{aleman2026clabtoolkit,
      title   = {CLABTOOLKIT: An Open-Source Toolkit for Routine Processing, Manipulation, and Visualization of Neuroimaging Data},
      author  = {Alem{\'a}n-G{\'o}mez, Yasser and Herv{\'e} Nino and Hagmann, Patric},
      journal = {arXiv preprint arXiv:2607.02638},
      year    = {2026},
      url     = {https://arxiv.org/abs/2607.02638}
    }

The repository includes a ``CITATION.cff`` file, and every release is archived in Zenodo: the DOI
`10.5281/zenodo.23540587 <https://doi.org/10.5281/zenodo.23540587>`_ always points to the latest
version, and each version has its own DOI listed on that page.

Contributing
------------

Contributions are welcome! Please open an issue first to discuss major changes. See
`CONTRIBUTING.rst <https://github.com/connectomicslab/clabtoolkit/blob/main/CONTRIBUTING.rst>`_
for the guidelines, including how to run the test suite.

Changelog
---------

See `HISTORY.rst <https://github.com/connectomicslab/clabtoolkit/blob/main/HISTORY.rst>`_ for a
detailed changelog.

Credits
-------

Developed by Yasser Alemán-Gómez and collaborators at the Connectomics Lab (Lausanne University
Hospital, CHUV). See `AUTHORS.rst <https://github.com/connectomicslab/clabtoolkit/blob/main/AUTHORS.rst>`_
for the full list.
