misctools module

class clabtoolkit.misctools.ExplorerDict(*args, name='root', force_mode=None, **kwargs)

Bases: dict

Enhanced dictionary with built-in exploration and visualization methods.

Works like a regular dict but adds methods for tree visualization, summaries, searching, and safe updating.

Examples

>>> data = ExplorerDict({
...     'subject': 'sub-001',
...     'metadata': {'age': 25, 'sessions': ['ses-01', 'ses-02']}
... })
>>> data.tree()           # Print tree visualization
>>> data.summary()        # Get statistics
>>> data.search('age')    # Find keys

__init__(*args, name='root', force_mode=None, **kwargs)

Initialize ExplorerDict.

Parameters:

• *args – Same as dict initialization

• **kwargs – Same as dict initialization

• name (str) – Name for the root object (for display)

• force_mode (str, optional) – Force display mode: ‘notebook’, ‘terminal’, or None (auto-detect)

get_path(path)

Get value at a specific path.

search(pattern, case_sensitive=False)

Search for keys matching a pattern.

structure(max_depth=3)

Get simplified structure showing types and shapes.

Parameters:

max_depth (int, optional) – Maximum depth to explore

Returns:

Simplified structure representation

Return type:

dict

Examples

>>> data = ExplorerDict({'a': [1, 2], 'b': {'c': np.array([3, 4])}})
>>> data.structure(max_depth=2)
{'a': ['<int>'], 'b': {'c': '<ndarray: shape=(2,), dtype=int64>'}}

summary(verbose=False)

Get comprehensive summary statistics.

Parameters:

verbose (bool) – Show detailed information

Returns:

Statistics about the dictionary structure

Return type:

dict

Examples

>>> data = ExplorerDict({'a': [1, 2], 'b': {'c': 3}})
>>> stats = data.summary()
📊 Dictionary Summary: root
...

to_dataframe(exclude_keys=None, include_keys=None)

Convert dictionary to pandas DataFrame.

Returns:

DataFrame representation of the dictionary

Return type:

pd.DataFrame

Examples

>>> data = ExplorerDict({'a': 1, 'b': 2})
>>> df = data.to_dataframe()

tree(max_depth=None, max_items=10, max_str_len=50, show_types=True, show_shapes=True)

Print tree visualization of the dictionary structure.

Parameters:

• max_depth (int, optional) – Maximum depth to display

• max_items (int) – Maximum items to show per level

• max_str_len (int) – Maximum string length before truncation

• show_types (bool) – Show type information

• show_shapes (bool) – Show array shapes

Examples

>>> data = ExplorerDict({'a': [1, 2, 3], 'b': {'c': 4}})
>>> data.tree()
🌳 root
├── a: [1, 2, 3] (list, len=3)
└── b: (dict, len=1)
    └── c: 4 (int)

clabtoolkit.misctools.update_dict(orig_dict, new_dict, merge_lists=False, allow_new_keys=False)

Deep update dictionary with type safety and optional new key support.

Provides type-safe updates for existing keys while optionally allowing new keys to be added. Type checking ensures that existing values can only be updated with values of the same type.

Parameters:

• orig_dict (dict) – The original dictionary to be updated. This dictionary is modified in-place.

• new_dict (dict) – Dictionary containing the updates to apply.

• merge_lists (bool, optional) – If True, lists are extended rather than replaced. Default is False.

• allow_new_keys (bool, optional) – If True, new keys from new_dict are added to orig_dict. If False, only existing keys can be updated. Default is False.

Returns:

The updated original dictionary.

Return type:

dict

Raises:

• TypeError – If an update value has a different type than the original value for existing keys.

• KeyError – If update_dict contains new keys and allow_new_keys is False.

Examples

>>> # With allow_new_keys=True
>>> original = {'name': 'John', 'items': [1, 2]}
>>> updates = {'name': 'Jane', 'age': 30, 'items': [3, 4]}
>>> deep_update_flexible(original, updates, merge_lists=True, allow_new_keys=True)
{'name': 'Jane', 'items': [1, 2, 3, 4], 'age': 30}

The misctools module provides essential utility functions and helper classes that support all other modules in the clabtoolkit package.

Key Features

• Enhanced command-line argument parsing

• File system operations and path management

• Color processing and conversion utilities

• Documentation generation helpers

• Progress tracking and console output

• String manipulation and validation

Main Classes

SmartFormatter

Enhanced argparse formatter for better help text display.

Key Methods: - Custom help text formatting with preserved line breaks - Improved readability for complex command-line interfaces - Support for structured help documentation

Common Usage Examples

Enhanced argument parsing:

from clabtoolkit.misctools import SmartFormatter
import argparse

# Create parser with enhanced formatting
parser = argparse.ArgumentParser(
    formatter_class=SmartFormatter,
    description="Enhanced command-line tool"
)

parser.add_argument(
    '--input',
    help='R|Input file path\n'
         'Supports multiple formats:\n'
         '  - NIfTI (.nii.gz)\n'
         '  - FreeSurfer (.mgh)\n'
         '  - GIFTI (.gii)'
)

Utility functions:

# File system operations
from clabtoolkit import misctools as utils

# Validate file existence and format
if utils.validate_file_format(filepath, ['.nii.gz', '.mgh']):
    print("Valid neuroimaging file")

# Color processing
rgb_color = utils.hex_to_rgb('#FF5733')
hex_color = utils.rgb_to_hex((255, 87, 51))

# Progress tracking
utils.display_progress("Processing subjects", current=5, total=20)

String and path utilities:

# Path manipulation
clean_path = utils.normalize_path("/path/with/../redundant/./parts")

# String validation
if utils.validate_subject_id("sub-001"):
    print("Valid BIDS subject ID")

# Generate unique identifiers
unique_id = utils.generate_unique_id(prefix="session")