clabtoolkit 0.4.2__tar.gz → 0.4.4__tar.gz

clabtoolkit-0.4.4/HISTORY.rst

@@ -0,0 +1,81 @@
+=======
+History
+=======
+
+0.4.4 (2026-07-17)
+------------------
+
+* Added get/set accessor methods for Parcellation attributes (data, affine, index, names and colors) with validation
+* Added support for organizing DICOM folders without requiring individual per-series folders
+* Improved the method to compress DICOM sessions
+* Fixed save_tractogram writing the wrong format when overwriting an existing file
+* Fixed colortable loading in tracttools for point-only maps and for maps absent from both data_per_point and data_per_streamline
+* Fixed tractogram merging in tracttools
+* Fixed out_image=None crash and added pathlib.Path support in delete_dwi_volumes
+* Fixed docstrings and type hints in tracttools
+* Renamed the streamline point count variable to nb_points for consistency
+* Removed surf as a variable name for tractograms
+* Removed the old connectome and old_dwitool modules (use connectivitytools and dwitools instead)
+* Reorganized the package imports
+* Documented the tracttools, pointstools and colorstools modules for the first time
+* Corrected the module documentation to match the actual API
+
+0.4.3 (2026-06-10)
+------------------
+
+* Added compute_fc_matrix method to Parcellation class
+* Added get_info method to Connectome and Parcellation classes
+* Added create_carpet_plot function in visualizationtools
+* Added compute_scalar_maps_from_tensor in diffusiontools
+* Added RegionTimeSeries object and integration across the package
+* Added method to generate connectomes
+* Added connected components computation from edge arrays
+* Added region lookup methods in AnnotParcellation
+* Added comprehensive get_info() for AnnotParcellation
+* Added method to binarize and dilate 3D arrays by millimeter distance
+* Added support for pathlib.Path objects as inputs
+* Added option to make TSV file compatible with templateflow
+* Added new colors to the bcolors class
+* Added bundle id map and updated names
+* Added notebook with examples for OHBM 2026
+* Added new ecosystem figure and logo
+* Refactored stats_from_vector for edge cases with nonzeros_only=True
+* Refactored AnnotParcellation gii2annot/annot2gii to use nibabel instead of FreeSurfer mris_convert
+* Extended merge_to_4d method to deal with DWI data
+* Fixed strict entity and suffix validation in is_bids_filename
+* Fixed pyvista notebook crash from threaded display
+* Fixed color table names bug
+* Fixed dimensions field bugs ("dims" vs "dim")
+* Multiple bug fixes, dependency updates, and documentation improvements
+
+0.4.1 (2026-02-19)
+------------------
+
+* Major refactoring of Parcellation class with improved attribute handling
+* Enhanced color table loading and export with multiple format support
+* Added region adjacency computation to Parcellation
+* Improved BIDS file entity extraction with parallel processing
+* Added DiffusionScheme class for gradient visualization
+* Enhanced Connectome class initialization and metrics computation
+* Added derivatives inventory functionality
+* Improved surface tools with PyVista fallback support
+* Added usage examples notebooks
+* Multiple bug fixes in mask handling, color processing, and data type conversion
+* Improved documentation and code organization
+
+0.3.4 (2025-01-09)
+------------------
+
+* Enhanced documentation and ReadTheDocs configuration
+* Moved region growing method to imagetools module  
+* Improved Sphinx autodoc configuration for better API documentation
+* Multiple improvements to surface visualization and plotting functionality
+* Added new morphometry and connectivity analysis tools
+* Enhanced BIDS dataset handling and entity management
+* Improved surface mesh operations and color mapping
+* Added network analysis tools and visualization capabilities
+
+0.3.1 (2025-05-22)
+------------------
+
+* Fourth release on PyPI. 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clabtoolkit
-Version: 0.4.2
+Version: 0.4.4
 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>
@@ -39,6 +39,10 @@ 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
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.1; extra == "dev"
 Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
@@ -63,6 +67,11 @@ Dynamic: license-file
 Connectomics Lab Toolkit
 ========================
 
+.. image:: 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

{clabtoolkit-0.4.2 → clabtoolkit-0.4.4}/README.rst

@@ -2,6 +2,11 @@
 Connectomics Lab Toolkit
 ========================
 
+.. image:: 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

{clabtoolkit-0.4.2 → clabtoolkit-0.4.4}/clabtoolkit/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Yasser Alemán-Gómez"""
 __email__ = "yasseraleman@protonmail.com"
-__version__ = "0.4.1"
+__version__ = "0.4.4"

{clabtoolkit-0.4.2 → clabtoolkit-0.4.4}/clabtoolkit/bidstools.py

@@ -389,7 +389,18 @@ def insert_entity(
     # If `entity2add` is empty after filtering, return the original entity
     if not entity2add:
         if is_string:
+            # Restore `suffix` and `extension` if they were removed
+            if suffix:
+                entity["suffix"] = suffix
+            if extension:
+                entity["extension"] = extension
             return entity2str(entity)
+
+        # Restore `suffix` and `extension` if they were removed
+        if suffix:
+            entity["suffix"] = suffix
+        if extension:
+            entity["extension"] = extension
         return entity
 
     else:
@@ -561,6 +572,7 @@ def recursively_replace_entity_key(root_dir: str, replacements: dict):
         cltmisc.rename_folders(all_dirs, replacements)
 
 
+####################################################################################################
 def recursively_delete_entity(root_dir: str, key2rem: Union[List[str], str, dict]):
     """
     This method deletes entities in all the files and folders of a BIDs dataset.
@@ -627,6 +639,7 @@ def recursively_delete_entity(root_dir: str, key2rem: Union[List[str], str, dict
         cltmisc.rename_folders(all_dirs, key2rem_dict)
 
 
+####################################################################################################
 def recursively_insert_entity(
     root_dir: str, entity2add: Dict[str, str], prev_entity: str = None
 ) -> None:
@@ -788,7 +801,6 @@ def get_all_entities(root_dir: str) -> Tuple[Dict[str, Set[str]], List[str]]:
             suffix = ent_dict.pop("suffix")
 
         ent_dict.pop("extension", None)
-        ent_dict.pop("run", None)
 
         return list(ent_dict.keys()), suffix
 
@@ -1040,7 +1052,12 @@ def entities_to_table(
             entities_dict.pop("extension")
 
         # Extract suffix before removing it
-        suffix = entities_dict.pop("suffix", "")
+        if "suffix" in entities_dict:
+            if include_suffix:
+                # Add an entity at the end called "Type"
+                tmp_suffix = entities_dict["suffix"]
+
+            entities_dict.pop("suffix")
 
         if entities_to_extract is not None:
             if isinstance(entities_to_extract, str):
@@ -1079,8 +1096,8 @@ def entities_to_table(
                 result_df.insert(0, entity.capitalize(), value)
 
         # Append Type column at the end if requested
-        if include_suffix:
-            result_df["Type"] = suffix
+        if "tmp_suffix" in locals() and include_suffix:
+            result_df.insert(0, "Type", tmp_suffix)
 
     else:
         if result_df.empty:
@@ -1754,36 +1771,106 @@ def get_derivatives_folders(
 
 
 ####################################################################################################
-def is_bids_filename(filename: str) -> bool:
+def is_bids_filename(filename: str, extensive: bool = False) -> bool:
     """
     Validates a BIDS filename structure, handling extensions and entity order.
 
-    Args:
-        filename (str): The filename to validate.
+    Parameters:
+    -----------
+    filename : str
+        The filename to validate, which may include extensions (e.g., .nii.gz).
+
+    extensive : bool, default=False
+        If True, performs additional checks against a BIDS configuration file to ensure that all
+        entities in the filename are defined in the config. If False, only checks the basic structure
+        of the filename.
+
+    Returns:
+    --------
+    bool
+        True if the filename follows BIDS conventions, False otherwise.
+
+    Examples:
+    ---------
+    >>> is_bids_filename("sub-01_ses-pre_task-rest_bold.nii.gz")
+    True
+    >>> is_bids_filename("sub-01_ses-pre_task-rest_bold")
+    True
+    >>> is_bids_filename("sub-01_ses-pre_task-rest.nii.gz")
+    True
+    >>> is_bids_filename("sub-01_ses-pre_task-rest")
+    True
+    >>> is_bids_filename("sub-01_ses-pre_task-rest_bold_extra.nii.gz")
+    False
+    >>> is_bids_filename("sub-01_ses-pre_task-rest_bold_extra")
 
-    Returns
-        bool: True if valid BIDS filename, False otherwise.
     """
     # Remove extension if present
     filename = cltmisc.get_real_basename(filename)
     base_filename = filename.split(".")[0]
 
     parts = base_filename.split("_")
-    if not parts:
+    if len(parts) < 2:
+        # Need at least one entity-label pair + a suffix
         return False
 
     entity_pattern = re.compile(r"^[a-zA-Z0-9]+-[a-zA-Z0-9]+$")
+    suffix_pattern = re.compile(r"^[a-zA-Z0-9]+$")
 
-    # Check that at least one entity-label pair is present
-    has_entity_label = False
-    for part in parts:
-        if "-" in part:
-            has_entity_label = True
-            if not entity_pattern.match(part):
-                return False
-    if not has_entity_label:
+    # All parts except the last must be valid entity-label pairs (e.g. sub-01, ses-M00)
+    for part in parts[:-1]:
+        if not entity_pattern.match(part):
+            return False
+
+    # The last part is the suffix (e.g. T1w, bold) — no dash allowed
+    if not suffix_pattern.match(parts[-1]):
         return False
 
+    # Check also that all the entities are on the json config file
+    cwd = os.path.dirname(os.path.abspath(__file__))
+    default_config_path = os.path.join(cwd, "config", "bids.json")
+
+    if extensive:
+        try:
+            with open(default_config_path, "r") as f:
+                config_data = json.load(f)
+
+            if (
+                "bids_entities" in config_data
+                and "raw_entities" in config_data["bids_entities"]
+                and "derivatives_entities" in config_data["bids_entities"]
+            ):
+                valid_entities = set(
+                    list(config_data["bids_entities"]["raw_entities"].keys())
+                    + list(config_data["bids_entities"]["derivatives_entities"].keys())
+                )
+                valid_suffixes = set(
+                    config_data["bids_entities"].get("raw_suffix", [])
+                    + config_data["bids_entities"].get("derivatives_suffix", [])
+                )
+            else:
+                raise ValueError(
+                    "Default config JSON does not have the expected structure."
+                )
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                f"Default configuration file not found at: {default_config_path}"
+            )
+        except json.JSONDecodeError:
+            raise ValueError(
+                f"Error parsing the default configuration file: {default_config_path}"
+            )
+
+        # Validate each entity key against the known BIDS entities
+        for part in parts[:-1]:
+            entity_key = part.split("-")[0]
+            if entity_key not in valid_entities:
+                return False
+
+        # Validate the suffix against the known BIDS suffixes
+        if parts[-1] not in valid_suffixes:
+            return False
+
     return True
 
 

{clabtoolkit-0.4.2 → clabtoolkit-0.4.4}/clabtoolkit/colorstools.py

@@ -122,6 +122,9 @@ class bcolors:
     BOLD = "\033[1m"
     ITALIC = "\033[3m"
     UNDERLINE = "\033[4m"
+    DIM = "\033[2m"
+    NORMAL = "\033[22m"
+    RESET_ALL = "\033[0m"
 
 
 ####################################################################################################
@@ -899,27 +902,38 @@ def harmonize_colors(
 
     >>> harmonize_colors(colors, output_format='rgb')
     array([[255,  87,  51],
-           [255,  87,  51],
-           [ 51,  87, 255]], dtype=uint8)
+            [255,  87,  51],
+            [ 51,  87, 255]], dtype=uint8)
 
     >>> harmonize_colors(colors, output_format='rgbnorm')
     array([[1.        , 0.34117647, 0.2       ],
-           [1.        , 0.34117647, 0.2       ],
-           [0.2       , 0.34117647, 1.        ]])
+            [1.        , 0.34117647, 0.2       ],
+            [0.2       , 0.34117647, 1.        ]])
 
     >>> # Single color input
     >>> harmonize_colors((255, 87, 51))
     ['#ff5733']
     """
 
-    # Handle single color inputs
+    # Normalize input into iterable of colors
     if isinstance(colors, str):
         colors = [colors]
+
     elif isinstance(colors, tuple):
         colors = [colors]
 
-    # Validate input type
-    if not isinstance(colors, (list, np.ndarray)):
+    elif isinstance(colors, np.ndarray):
+        if colors.ndim == 1:
+            # Single color (e.g., [R,G,B] or [R,G,B,A])
+            colors = [colors]
+        elif colors.ndim == 2:
+            # Multiple colors (Nx3 or Nx4)
+            colors = [row for row in colors]
+        else:
+            raise ValueError("NumPy array must be 1D or 2D for colors")
+
+    # Final validation
+    if not isinstance(colors, list):
         raise TypeError("Input must be a string, tuple, list, or numpy array")
 
     # Validate output format

{clabtoolkit-0.4.2 → clabtoolkit-0.4.4}/clabtoolkit/config/config.json

@@ -1,6 +1,7 @@
 {
     "metrics_units": {
         "thickness": "mm",
+        "nvertices": "au",
         "area": "cm2",
         "volume": "cm3",
         "curv": "mm-1",