clabtoolkit 0.4.4__tar.gz → 0.4.5__tar.gz

clabtoolkit-0.4.5/DOCUMENTATION.md

@@ -0,0 +1,498 @@
+# Connectomics Lab Toolkit (clabtoolkit)
+
+## Overview
+
+**clabtoolkit** is a comprehensive Python toolkit designed for neuroimaging data processing and analysis, with specialized focus on brain connectivity data, BIDS datasets, and various neuroimaging formats. Developed by Yasser Alemán-Gómez, this toolkit provides an end-to-end solution for connectomics research and surface-based brain analysis.
+
+**Version**: 0.4.0  
+**License**: Apache Software License 2.0  
+**Python Support**: 3.9+  
+**Documentation**: https://clabtoolkit.readthedocs.io  
+**Repository**: https://github.com/connectomicslab/clabtoolkit
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install clabtoolkit
+```
+
+### Development Installation with Conda
+
+```bash
+git clone https://github.com/connectomicslab/clabtoolkit.git
+cd clabtoolkit
+conda env create -f environment.yaml
+conda activate clabtoolkit
+pip install -e .[dev]
+```
+
+## Quick Start
+
+```python
+import clabtoolkit.bidstools as cltbids
+import clabtoolkit.surfacetools as cltsurf
+
+# Extract entities from BIDS filename
+entities = cltbids.str2entity("sub-01_ses-M00_T1w.nii.gz")
+print(entities)  # {'sub': '01', 'ses': 'M00', 'suffix': 'T1w', 'extension': 'nii.gz'}
+
+# Load and visualize a brain surface
+surface = cltsurf.Surface("/path/to/surface.pial")
+surface.plot()
+```
+
+## Package Architecture
+
+The toolkit follows a modular, layered architecture designed for scalability and ease of use:
+
+-   **Foundation Layer**: Core utilities and plotting infrastructure
+-   **Data Layer**: BIDS compliance and image processing
+-   **Analysis Layer**: Specialized neuroimaging analysis tools
+-   **Workflow Layer**: Pipeline management and quality control
+
+## Module Reference
+
+### Core Data Management
+
+#### bidstools - BIDS Dataset Management
+
+**Purpose**: Comprehensive BIDS (Brain Imaging Data Structure) compliance and dataset management
+
+**Key Features**:
+
+-   BIDS entity manipulation and validation
+-   Dataset organization and structure analysis
+-   Batch processing utilities
+-   Automated database table generation from BIDS datasets
+
+**Key Functions**:
+
+```python
+# Convert BIDS filename to entity dictionary
+entities = cltbids.str2entity("sub-01_ses-M00_acq-3T_T1w.nii.gz")
+
+# Manipulate BIDS entities
+cltbids.replace_entity_value(filename, 'ses', 'new_session')
+cltbids.insert_entity(filename, 'run', '01', prev_entity='acq')
+
+# Generate and display BIDS dataset structure
+tree = cltbids.generate_bids_tree("/path/to/bids/dataset")
+print(tree)
+
+# Get all subjects from a BIDS dataset
+subjects = cltbids.get_subjects("/path/to/bids/dataset")
+
+# Generate comprehensive dataset overview
+database = cltbids.get_bids_database_table("/path/to/bids/dataset")
+print(database.head())
+```
+
+#### imagetools - Image Processing Engine
+
+**Purpose**: Neuroimaging operations and morphological processing
+
+**Key Classes**:
+
+-   `MorphologicalOperations`: Binary image morphology (erosion, dilation, opening, closing)
+
+**Key Features**:
+
+-   2D/3D morphological operations
+-   Volume filtering and hole filling
+-   Image resampling and transformation
+-   Quality control utilities
+
+**Usage Example**:
+
+```python
+from clabtoolkit.imagetools import MorphologicalOperations
+
+morph = MorphologicalOperations()
+# Perform morphological closing on binary image
+filled = morph.closing(image_with_holes, iterations=1)
+```
+
+### FreeSurfer Integration
+
+#### freesurfertools - FreeSurfer Ecosystem Interface
+
+**Purpose**: Complete interface with FreeSurfer outputs and cortical surface analysis
+
+**Key Classes**:
+
+-   `AnnotParcellation`: Advanced annotation file management
+    -   Load/save annotation files (.annot, .gcs formats)
+    -   Parcellation correction and validation
+    -   Format conversion between annotation types
+
+**Key Features**:
+
+-   FreeSurfer stats file parsing
+-   Surface-based morphometry computation
+-   Container technology integration
+-   Annotation file correction and processing
+
+**Usage Example**:
+
+```python
+import clabtoolkit.freesurfertools as cltfree
+import os
+
+# Get FreeSurfer environment variables
+freesurfer_home = os.environ.get('FREESURFER_HOME')
+fs_subject_dir = os.path.join(freesurfer_home, 'subjects')
+fs_fullid = 'bert'
+
+# Load the Subject object
+subject = cltfree.FreeSurferSubject(fs_fullid, fs_subject_dir)
+
+# Obtain dictionaries containing hemisphere-specific FreeSurfer file paths
+surf, maps, parc, stats = subject.get_hemi_dicts(fs_subject_dir, 'lh')
+
+# Get the processing status
+print(f"Processing status for subject {fs_fullid}:")
+subject.get_proc_status()
+print(subject.pstatus)
+
+# Load and process annotation file
+annot = cltfree.AnnotParcellation("lh.aparc.a2009s.annot")
+annot.correct_parcellation()  # Fix unlabeled vertices
+```
+
+### Analysis and Processing
+
+#### parcellationtools - Brain Parcellation Management
+
+**Purpose**: Comprehensive brain parcellation handling and regional analysis
+
+**Key Classes**:
+
+-   `Parcellation`: Complete parcellation ecosystem
+    -   Load parcellations with lookup tables
+    -   Regional filtering and grouping
+    -   Volume calculations and statistics
+    -   Multi-format export capabilities
+
+**Key Features**:
+
+-   Flexible parcellation filtering and modification
+-   Regional statistics computation
+-   Atlas integration and validation
+-   BIDS-compliant output generation
+
+**Usage Example**:
+
+```python
+import clabtoolkit.parcellationtools as cltparc
+
+# Load parcellation (automatically detects and loads lookup table if available)
+vol_parc = cltparc.Parcellation("/path/to/parcellation/parcellation.nii.gz")
+```
+
+If a lookup table with the same filename and extension (.lut or .tsv) exists, it will be loaded automatically. Otherwise, load it manually:
+
+```python
+# Load the LUT file manually
+vol_parc.load_colortable("/path/to/lookuptable/lookuptable.lut", lut_type="lut")
+```
+
+Compute regional volumes for all structures in the parcellation:
+
+```python
+# Compute regional volumes
+volumes = vol_parc.compute_regional_volumes()
+```
+
+Filter structures by name or code if only specific regions are of interest:
+
+```python
+# Select structures to keep by their name
+names_to_keep = ["thalamus", "cerebellum"]
+
+# Keep only the specified structures
+vol_parc.keep_by_name(names2keep=names_to_keep)
+
+# Save the modified parcellation
+out_parc_path = "/tmp/sub-test_desc-tha+cer_dseg.nii.gz"
+vol_parc.save_parcellation(out_parc_path, save_lut=True)
+```
+
+#### surfacetools - Surface Geometry Processing
+
+**Purpose**: Brain surface mesh processing and advanced visualization
+
+**Key Classes**:
+
+-   `Surface`: Comprehensive surface management
+    -   FreeSurfer surface file support (.pial, .white, .inflated)
+    -   Scalar data overlay and visualization
+    -   Parcellation integration
+    -   PyVista-powered 3D rendering
+
+**Key Features**:
+
+-   Multi-format surface loading
+-   Scalar map management and visualization
+-   Interactive 3D plotting
+-   Surface-based analysis tools
+
+**Usage Example**:
+
+```python
+from clabtoolkit.surfacetools import Surface
+
+# Load surface with scalar data
+surface = Surface("/path/to/lh.pial")
+surface.load_scalar_data("/path/to/thickness.mgh", maps_names="Thickness")
+surface.plot(overlay_name="Thickness", cmap='viridis', views=["lateral", "medial"])
+
+# Load annotations
+surface.load_annotation("/path/to/lh.aparc.annot", 'aparc')
+surface.plot(overlay_name="Thickness", cmap='viridis', views="8_views")
+```
+
+#### morphometrytools - Morphometric Analysis
+
+**Purpose**: Surface-based morphometric computations and statistics
+
+**Key Features**:
+
+-   Regional value extraction from surface annotations
+-   Multi-hemisphere morphometric analysis
+-   Statistical summary generation
+-   Integration with parcellation workflows
+
+**Usage Examples**:
+
+Extract regional values by combining vertex-wise surface metrics with anatomical parcellation data:
+
+```python
+import clabtoolkit.morphometrytools as morpho
+
+metric_file = '/path/to/metric/lh.thickness'
+parc_file = '/path/to/annotation/lh.atlas.annot'
+
+df_region, metric_values, _ = morpho.compute_reg_val_fromannot(
+    metric_file, parc_file, hemi, metric=metric_name, include_global=False
+)
+```
+
+Compute regional statistics from a volumetric metric map and a parcellation:
+
+```python
+import clabtoolkit.morphometrytools as morpho
+
+metric_file = '/path/to/metric/fa.nii.gz'
+parc_file = '/path/to/parcellation/parc.nii.gz'
+
+# Compute regional statistics
+df, metric_values, _ = morpho.compute_reg_val_fromparcellation(
+    metric_file, parc_file, metric='intensity'
+)
+```
+
+### Specialized Analysis
+
+#### dwitools - Diffusion MRI Analysis
+
+**Purpose**: Diffusion-weighted imaging analysis and tractography processing
+
+**Key Features**:
+
+-   DWI volume manipulation and quality control
+-   Tractography file processing (.trk, .tck formats)
+-   Bundle analysis and clustering
+
+**Usage Example**:
+
+```python
+from clabtoolkit.dwitools import delete_dwi_volumes
+
+# Remove specific DWI volumes
+delete_dwi_volumes(
+    dwi_file="dwi.nii.gz",
+    bval_file="dwi.bval",
+    bvec_file="dwi.bvec",
+    volumes_to_delete=[0, 5, 10]  # Remove specific volumes
+)
+```
+
+#### networktools - Graph Analysis
+
+**Purpose**: Network analysis and graph theory applications for brain connectivity
+
+**Key Features**:
+
+-   Graph representation creation from brain meshes
+-   Sparse matrix operations for large-scale networks
+-   Connectivity analysis utilities
+
+**Usage Example**:
+
+```python
+from clabtoolkit.networktools import triangulated_mesh_to_csr
+
+# Convert mesh to graph representation
+graph = triangulated_mesh_to_csr(vertices, faces)
+```
+
+#### segmentationtools - Image Segmentation
+
+**Purpose**: Atlas-based and automated image segmentation
+
+**Key Features**:
+
+-   Atlas-based parcellation using ANTs
+-   Template registration workflows
+-   Multi-atlas segmentation support
+
+**Usage Example**:
+
+```python
+from clabtoolkit.segmentationtools import abased_parcellation
+
+# Perform atlas-based segmentation
+abased_parcellation(
+    moving_image="T1w.nii.gz",
+    atlas_image="template.nii.gz",
+    atlas_labels="template_labels.nii.gz"
+)
+```
+
+### Quality Control and Visualization
+
+#### qcqatools - Quality Control Framework
+
+**Purpose**: Comprehensive quality assessment for neuroimaging data
+
+**Key Features**:
+
+-   Automated slice selection for quality control
+-   Multi-modal data validation
+-   Visual quality assessment tools
+-   Report generation capabilities
+
+#### visualizationtools - Advanced Brain Visualization
+
+**Purpose**: Publication-quality brain visualization system
+
+**Key Classes**:
+
+-   `BrainPlotter`: Multi-view brain surface visualization
+    -   Configurable view layouts
+    -   Custom colormap support
+    -   Publication-ready output
+    -   Multi-hemisphere rendering
+
+**Key Features**:
+
+-   JSON-based view configuration system
+-   Flexible layout management
+-   High-quality rendering for publications
+-   Interactive visualization capabilities
+
+### Utilities and Infrastructure
+
+#### misctools - Core Utilities
+
+**Purpose**: Foundation utility functions supporting all modules
+
+**Key Features**:
+
+-   Enhanced command-line argument parsing
+-   File system operations
+-   Color processing utilities
+-   Documentation generation helpers
+
+#### pipelinetools - Workflow Management
+
+**Purpose**: Pipeline orchestration and batch processing
+
+**Key Features**:
+
+-   Subject ID management for batch workflows
+-   Parallel processing utilities
+-   Progress tracking and monitoring
+
+#### plottools - Plotting Infrastructure
+
+**Purpose**: Low-level plotting support and layout calculations
+
+**Key Features**:
+
+-   Dynamic subplot grid calculation
+-   Screen size detection
+-   Multi-monitor support
+
+#### dicomtools - DICOM Processing
+
+**Purpose**: DICOM file organization and BIDS conversion
+
+**Key Features**:
+
+-   Multi-threaded DICOM organization
+-   BIDS conversion workflows
+-   Demographics integration
+-   Session management
+
+## Configuration System
+
+clabtoolkit uses a sophisticated JSON-based configuration system located in `clabtoolkit/config/`:
+
+-   **bids.json**: BIDS entity definitions and validation rules
+-   **viz_views.json**: Visualization layout configurations
+-   **lobes.json**: Anatomical lobe definitions for parcellation
+-   **stats_mapping.json**: Statistical measure mappings and metadata
+
+## Dependencies
+
+### Core Dependencies
+
+-   **nibabel**: Neuroimaging file I/O
+-   **numpy**: Numerical computing
+-   **pandas**: Data manipulation
+-   **scipy**: Scientific computing
+-   **matplotlib**: Basic plotting
+
+### Specialized Dependencies
+
+-   **pyvista**: 3D visualization and mesh processing
+-   **rich**: Enhanced console output
+-   **dipy**: Diffusion MRI processing
+-   **h5py**: HDF5 file support
+
+### Environment
+
+All dependencies are specified in the **environment.yaml** file for reproducible conda environments.
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## Support and Documentation
+
+-   **GitHub Issues**: Report bugs and request features
+-   **Documentation**: Comprehensive API documentation with examples
+-   **Test Suite**: Extensive test coverage with example data
+-   **Jupyter Notebooks**: Interactive examples and tutorials
+
+## Research Applications
+
+clabtoolkit is particularly well-suited for:
+
+-   **Connectomics Research**: Brain connectivity analysis and visualization
+-   **Surface-based Analysis**: Cortical thickness, area, and curvature studies
+-   **BIDS Data Management**: Large-scale neuroimaging dataset organization
+-   **Multi-modal Integration**: Combined structural and diffusion MRI analysis
+-   **Quality Control**: Automated quality assessment for neuroimaging data
+-   **Publication Visualization**: High-quality brain visualizations for research papers
+
+---
+
+_This toolkit represents a comprehensive solution for modern neuroimaging research, combining robust data management with advanced analysis capabilities and publication-quality visualization tools._

{clabtoolkit-0.4.4 → clabtoolkit-0.4.5}/HISTORY.rst

@@ -2,6 +2,29 @@
 History
 =======
 
+0.4.5 (2026-08-28)
+------------------
+
+* Added create_5tt to parcellationtools to generate MRtrix3 5TT images
+* Added a method to merge the cortical gray matter with the white matter adjacent to the cortex, and used the merged image to build the 5TT image
+* Added the apply_affine method to the Surface, PointCloud and Tractogram classes, with an inplace option
+* Added connected components detection for binary images
+* Added the option to interpolate on Parcellation objects
+* Added a method to compare dictionaries
+* Added the process_subject function to bidstools
+* Added the brain_pos_col and cb_pos functions to build_visualization_layout
+* Added the ventral DC to the list of subcortical regions
+* Added examples for create_5tt, merge_ctx_wm, apply_cras and apply_affine
+* Refactored the visualizationtools module and fixed several plotting errors
+* Renamed the force parameter to overwrite in all the functions and methods writing files
+* Renamed the transform method of the PointCloud class to apply_affine
+* Fixed the apply_cras method of the Surface class
+* Fixed a bug in the subject selection of bidstools
+* Fixed the line spacing, the append handling and the header lines of export_to_lutctab in colorstools
+* Fixed the anchors, the links and the FreeSurfer paths of the notebooks
+* Silenced the tight_layout warning of create_carpet_plot
+* Raised the minimum Python version to 3.11 and adopted the built-in generics and the union operator in the type hints
+
 0.4.4 (2026-07-17)
 ------------------
 

{clabtoolkit-0.4.4 → clabtoolkit-0.4.5}/MANIFEST.in

@@ -5,21 +5,36 @@ include LICENSE
 include README.rst
 include pyproject.toml
 
+# Project metadata and reproducible environments
+include DOCUMENTATION.md
+include architecture_diagram.md
+include Makefile
+include tox.ini
+include requirements.txt
+include requirements_dev.txt
+include requirements-docs.txt
+include environment.yaml
+include environment-mac.yaml
+
 # Include package source code
 recursive-include clabtoolkit *.py
 recursive-include clabtoolkit/config *.json
 
 # Include documentation
-recursive-include docs *.rst *.py *.bat *.png
+recursive-include docs *.rst *.py *.bat *.png *.ico
 recursive-include docs Makefile
 include docs/make.bat
 
 # Include usage examples
 recursive-include usage_examples *.ipynb *.py *.md
 
-# EXCLUDE tests data completely  
+# EXCLUDE tests data completely
 prune tests
 
+# Build output and tool caches must never reach the sdist
+prune docs/build
+prune usage_examples/nilearn_cache
+
 # Exclude unwanted files (only those that exist)
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

clabtoolkit-0.4.5/Makefile

@@ -0,0 +1,87 @@
+.PHONY: clean clean-build clean-pyc clean-test coverage dist docs help install lint lint/flake8
+.DEFAULT_GOAL := help
+
+define BROWSER_PYSCRIPT
+import os, webbrowser, sys
+
+from urllib.request import pathname2url
+
+webbrowser.open("file://" + pathname2url(os.path.abspath(sys.argv[1])))
+endef
+export BROWSER_PYSCRIPT
+
+define PRINT_HELP_PYSCRIPT
+import re, sys
+
+for line in sys.stdin:
+	match = re.match(r'^([a-zA-Z_-]+):.*?## (.*)$$', line)
+	if match:
+		target, help = match.groups()
+		print("%-20s %s" % (target, help))
+endef
+export PRINT_HELP_PYSCRIPT
+
+BROWSER := python -c "$$BROWSER_PYSCRIPT"
+
+help:
+	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
+
+clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
+
+clean-build: ## remove build artifacts
+	rm -fr build/
+	rm -fr dist/
+	rm -fr .eggs/
+	find . -name '*.egg-info' -exec rm -fr {} +
+	find . -name '*.egg' -exec rm -f {} +
+
+clean-pyc: ## remove Python file artifacts
+	find . -name '*.pyc' -exec rm -f {} +
+	find . -name '*.pyo' -exec rm -f {} +
+	find . -name '*~' -exec rm -f {} +
+	find . -name '__pycache__' -exec rm -fr {} +
+
+clean-test: ## remove test and coverage artifacts
+	rm -fr .tox/
+	rm -f .coverage
+	rm -fr htmlcov/
+	rm -fr .pytest_cache
+
+lint/flake8: ## check style with flake8
+	flake8 clabtoolkit tests
+
+lint: lint/flake8 ## check style
+
+test: ## run tests quickly with the default Python
+	python setup.py test
+
+test-all: ## run tests on every Python version with tox
+	tox
+
+coverage: ## check code coverage quickly with the default Python
+	coverage run --source clabtoolkit setup.py test
+	coverage report -m
+	coverage html
+	$(BROWSER) htmlcov/index.html
+
+docs: ## generate Sphinx HTML documentation, including API docs
+	rm -f docs/clabtoolkit.rst
+	rm -f docs/modules.rst
+	sphinx-apidoc -o docs/ clabtoolkit
+	$(MAKE) -C docs clean
+	$(MAKE) -C docs html
+	$(BROWSER) docs/_build/html/index.html
+
+servedocs: docs ## compile the docs watching for changes
+	watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D .
+
+release: dist ## package and upload a release
+	twine upload dist/*
+
+dist: clean ## builds source and wheel package
+	python setup.py sdist
+	python setup.py bdist_wheel
+	ls -l dist
+
+install: clean ## install the package to the active Python's site-packages
+	python setup.py install

{clabtoolkit-0.4.4 → clabtoolkit-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clabtoolkit
-Version: 0.4.4
+Version: 0.4.5
 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>
@@ -16,13 +16,12 @@ Classifier: Intended Audience :: Developers
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 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.9
+Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: AUTHORS.rst