qcqatools module

clabtoolkit.qcqatools.get_valid_slices(data, ignore_value=None, slice_positions=[0.3, 0.5, 0.7])[source]

Get valid slice indices along each dimension by identifying regions with signal.

Determines optimal slice positions by finding the spatial extent of non-background voxels and calculating slice indices at specified relative positions within that extent.

Parameters:

  • data (np.ndarray) – 3D neuroimaging data array.

  • ignore_value (int, optional) – Value to treat as background. If None, uses 0 as background. Default is None.

  • slice_positions (list, optional) – Relative positions (0-1) for slices along each axis. Default is [0.3, 0.5, 0.7].

Returns:

Three lists of slice indices for sagittal, coronal, and axial views.

Return type:

tuple

Examples

>>> # Get slice indices for standard positions
>>> sag_slices, cor_slices, ax_slices = get_valid_slices(brain_data)
>>> print(f"Sagittal slices: {sag_slices}")
>>>
>>> # Custom positions and background value
>>> slices = get_valid_slices(data, ignore_value=-1, slice_positions=[0.25, 0.75])
clabtoolkit.qcqatools.generate_slices(nifti_path, output_path=None, slice_positions=[0.3, 0.5, 0.7], ignore_value=None, remove_invalid=True, fig_size=None, dpi=300, bg_color='black', text_color='white', cmap='gray', intensity_percentiles=(1, 99), show_colorbar=True, colorbar_width_inches=0.2, colorbar_height_fraction=0.7, overwrite=False)[source]

Generate composite visualization of brain image slices from neuroimaging file.

Creates a figure showing slices from sagittal, coronal, and axial views at specified positions with consistent intensity scaling and optional colorbar.

Parameters:

  • nifti_path (str or Path) – Path to input neuroimaging file (NIfTI, MGZ, MINC, etc.).

  • output_path (str or Path, optional) – Output PNG path. If None, saves alongside input file. Default is None.

  • slice_positions (list, optional) – Relative positions (0-1) for slices along each axis. Default is [0.3, 0.5, 0.7].

  • ignore_value (int, optional) – Value to ignore for slice selection. Default is None.

  • remove_invalid (bool, optional) – Whether to remove invalid files when detected. Default is True.

  • fig_size (tuple, optional) – Figure size (width, height) in inches. Auto-calculated if None. Default is None.

  • dpi (int, optional) – Output resolution in dots per inch. Default is 300.

  • bg_color (str, optional) – Background color. Default is ‘black’.

  • text_color (str, optional) – Text color. Default is ‘white’.

  • cmap (str, optional) – Colormap for image display. Default is ‘gray’.

  • intensity_percentiles (tuple, optional) – Percentiles for intensity normalization. Default is (1, 99).

  • show_colorbar (bool, optional) – Whether to show colorbar. Default is True.

  • colorbar_width_inches (float, optional) – Colorbar width in inches. Default is 0.2.

  • colorbar_height_fraction (float, optional) – Colorbar height as fraction of figure height. Default is 0.7.

  • overwrite (bool, optional) – Whether to overwrite existing files. Default is False.

Returns:

Path to generated PNG file, or None if generation failed.

Return type:

str or None

Raises:

Examples

>>> # Basic slice generation
>>> png_path = generate_slices('brain.nii.gz')
>>> print(f"Generated: {png_path}")
>>>
>>> # Custom output with high resolution
>>> png_path = generate_slices(
...     'T1w.nii.gz',
...     output_path='slices.png',
...     dpi=600,
...     slice_positions=[0.4, 0.6]
... )
clabtoolkit.qcqatools.recursively_generate_slices(input_folder, output_folder=None, and_filter=None, or_filter=None, slice_positions=[0.3, 0.5, 0.7], ignore_value=None, recursive=True, n_jobs=1, file_extensions=['.nii', '.nii.gz', '.mgz', '.mnc'], overwrite=False, verbose=True)[source]

Recursively process neuroimaging files in a folder to generate PNG visualizations.

Searches through directory structure, identifies neuroimaging files based on filters and extensions, then generates slice visualizations with optional parallel processing and progress tracking.

Parameters:

  • input_folder (str or Path) – Root directory containing neuroimaging files.

  • output_folder (str or Path, optional) – Output directory for PNG files. If None, saves alongside inputs. Default is None.

  • and_filter (str, list, or dict, optional) – AND filter for file selection. Default is None.

  • or_filter (str, list, or dict, optional) – OR filter for file selection. Default is None.

  • slice_positions (list, optional) – Relative positions for slices. Default is [0.3, 0.5, 0.7].

  • ignore_value (int, optional) – Background value to ignore. Default is None.

  • recursive (bool, optional) – Whether to search subdirectories. Default is True.

  • n_jobs (int, optional) – Number of parallel processing jobs. Default is 1.

  • file_extensions (list, optional) – Valid neuroimaging file extensions. Default is [‘.nii’, ‘.nii.gz’, ‘.mgz’, ‘.mnc’].

  • overwrite (bool, optional) – Whether to overwrite existing PNG files. Default is False.

  • verbose (bool, optional) – Whether to show progress information. Default is True.

Returns:

Paths to generated PNG files.

Return type:

list

Raises:

FileNotFoundError – If input folder doesn’t exist.

Examples

>>> # Process all files in directory
>>> png_files = recursively_generate_slices('/data/dataset')
>>> print(f"Generated {len(png_files)} visualizations")
>>>
>>> # Filter T1w files and use parallel processing
>>> png_files = recursively_generate_slices(
...     '/data/bids_dataset',
...     and_filter='T1w',
...     n_jobs=4,
...     output_folder='/output/figures'
... )
>>>
>>> # Custom slice positions
>>> png_files = recursively_generate_slices(
...     '/data/dataset',
...     slice_positions=[0.25, 0.5, 0.75],
...     overwrite=True
... )
clabtoolkit.qcqatools.generate_image_selection_webpage(root_directory, output_html=None, png_pattern='**/*.png', title='PNG Image Selection', recursive=True, show_descriptions=True, image_width='1400px', overwrite=False)[source]

Generate interactive HTML webpage to display PNG images with selection checkboxes.

Creates a webpage showing images in hierarchical folder structure with checkboxes for selection, descriptions from JSON files, and download functionality for creating file lists.

Parameters:

  • root_directory (str or Path) – Root directory to search for PNG files.

  • output_html (str or Path, optional) – Output HTML file path. If None, saves as ‘png_selection.html’ in root directory. Default is None.

  • png_pattern (str, optional) – Glob pattern for finding PNG files. Default is ‘**/*.png’.

  • title (str, optional) – HTML page title. Default is ‘PNG Image Selection’.

  • recursive (bool, optional) – Whether to search recursively. Default is True.

  • show_descriptions (bool, optional) – Whether to extract descriptions from JSON files. Default is True.

  • image_width (str, optional) – CSS width for images. Default is ‘1400px’.

  • overwrite (bool, optional) – Whether to overwrite existing HTML file. Default is False.

Returns:

Path to generated HTML file.

Return type:

str

Notes

The webpage includes: - Hierarchical display of images by folder structure - Checkboxes for image selection - Descriptions extracted from associated JSON files - Select all/none buttons - Download selected files list functionality - Dark theme optimized for neuroimaging

Examples

>>> # Create webpage for all PNGs
>>> html_file = generate_image_selection_webpage('/data/figures')
>>> print(f"Webpage created: {html_file}")
>>>
>>> # Custom settings
>>> html_file = generate_image_selection_webpage(
...     '/data/qc_images',
...     output_html='/reports/qc_selection.html',
...     title='Quality Control Images',
...     image_width='1000px'
... )
clabtoolkit.qcqatools.create_png_webpage_from_generated_slices(root_directory, output_html=None, overwrite=False)[source]

Convenience function to create webpage from PNG files generated by slice functions.

Creates an HTML selection interface specifically optimized for brain slice visualizations with appropriate title and settings.

Parameters:

  • root_directory (str or Path) – Root directory containing generated PNG files.

  • output_html (str or Path, optional) – Output HTML file path. Default is None.

  • overwrite (bool, optional) – Whether to overwrite existing HTML file. Default is False.

Returns:

Path to generated HTML file.

Return type:

str

Examples

>>> # Create webpage after generating slices
>>> png_files = recursively_generate_slices('/data/dataset')
>>> html_file = create_png_webpage_from_generated_slices('/data/dataset')
>>> print(f"Browse results at: {html_file}")

The qcqatools module provides comprehensive quality control and quality assessment tools for neuroimaging data, enabling automated validation and visual inspection workflows.

Key Features

  • Automated quality control metrics computation

  • Image artifact detection and reporting

  • Optimal slice selection for visual inspection

  • Multi-modal data validation

  • Quality report generation

  • Visual assessment tools

Main Functions

Quality Assessment

  • get_valid_slices(): Identify optimal slice positions for visualization

  • generate_slices(): Generate image slices for quality control

  • recursively_generate_slices(): Recursively generate slices for multiple files

  • generate_image_selection_webpage(): Generate webpage for image selection

  • create_png_webpage_from_generated_slices(): Create PNG webpage from generated slices

Common Usage Examples

Automated slice selection:

from clabtoolkit.qcqatools import get_valid_slices

# Find optimal slices for quality control visualization
optimal_slices = get_valid_slices(
    image_file="/path/to/T1w.nii.gz",
    n_slices=5,
    plane='axial'
)

print(f"Recommended slices: {optimal_slices}")

Generate quality control slices:

# Generate slices for quality control
generate_slices(
    image_file="/path/to/T1w.nii.gz",
    output_dir="/path/to/qc_slices",
    n_slices=5,
    plane='axial'
)

Create QC webpage:

# Generate interactive QC webpage
generate_image_selection_webpage(
    image_dir="/path/to/qc_slices",
    output_html="/path/to/qc_report.html",
    title="Quality Control Report"
)

# Process multiple files recursively
recursively_generate_slices(
    input_dir="/path/to/bids/dataset",
    output_dir="/path/to/qc_output",
    file_pattern="*T1w.nii.gz"
)