visualizer

tit.plotting.nilearn.visualizer

Multi-slice field figures with atlas outlines for Nilearn Visuals.

:func:field_nifti names the MNI field file one simulation contributes, and :class:NilearnVisualizer draws the 3 x 7 slice grid of a group-averaged field (:mod:tit.plotting.nilearn.img_slices wraps it for the runner).

NilearnVisualizer

Draws a group-averaged field as a multi-slice PDF with atlas outlines.

See Also

tit.plotting.nilearn.img_slices : The runner's entry point to this class. tit.plotting.nilearn.img_glass : The glass-brain PDF of the same field.

create_pdf_visualization_group

create_pdf_visualization_group(averaged_img, base_filename: str, output_dir: str, min_cutoff: float | None = None, max_cutoff: float | None = None, atlas_name: str = 'harvard_oxford_sub', selected_regions: list[int] | None = None) -> str | None

Create a multi-slice PDF from a pre-averaged group NIfTI image.

Sagittal, coronal and axial rows of seven slices each, the field on a hot colour map over the MNI template, with optional atlas outlines.

Parameters

averaged_img : nibabel.Nifti1Image Pre-averaged electric-field image. base_filename : str Base filename for output (without extension). output_dir : str Directory where the PDF will be saved. min_cutoff : float or None, optional Lower display threshold in V/m. When None the 95th percentile of non-zero voxels is used. max_cutoff : float or None, optional Upper display threshold in V/m. When None the 99.9th percentile of non-zero voxels is used. atlas_name : str, optional Nilearn atlas key. selected_regions : list of int or None, optional 0-indexed region indices for the atlas overlay.

Returns

str or None Path to the saved PDF, or None on failure.

Source code in tit/plotting/nilearn/visualizer.py

def create_pdf_visualization_group(
    self,
    averaged_img,
    base_filename: str,
    output_dir: str,
    min_cutoff: float | None = None,
    max_cutoff: float | None = None,
    atlas_name: str = "harvard_oxford_sub",
    selected_regions: list[int] | None = None,
) -> str | None:
    """Create a multi-slice PDF from a pre-averaged group NIfTI image.

    Sagittal, coronal and axial rows of seven slices each, the field on
    a hot colour map over the MNI template, with optional atlas outlines.

    Parameters
    ----------
    averaged_img : nibabel.Nifti1Image
        Pre-averaged electric-field image.
    base_filename : str
        Base filename for output (without extension).
    output_dir : str
        Directory where the PDF will be saved.
    min_cutoff : float or None, optional
        Lower display threshold in V/m.  When *None* the 95th
        percentile of non-zero voxels is used.
    max_cutoff : float or None, optional
        Upper display threshold in V/m.  When *None* the 99.9th
        percentile of non-zero voxels is used.
    atlas_name : str, optional
        Nilearn atlas key.
    selected_regions : list of int or None, optional
        0-indexed region indices for the atlas overlay.

    Returns
    -------
    str or None
        Path to the saved PDF, or *None* on failure.
    """
    print(f"=== Creating PDF Visualization for Group Averaged Data ===")

    # Load and analyze data
    data = averaged_img.get_fdata()
    data_nonzero = data[data > 0]
    if len(data_nonzero) == 0:
        print("Warning: No non-zero field values found")
        return None

    max_value = np.max(data)
    percentile_999 = np.percentile(data_nonzero, 99.9)
    min_value = np.min(data_nonzero)
    min_cutoff, max_cutoff = resolve_cutoffs(data_nonzero, min_cutoff, max_cutoff)

    print(f"Electric field statistics (averaged data):")
    print(f"  Absolute maximum: {format_vm(max_value)} V/m")
    print(f"  99.9th percentile: {format_vm(percentile_999)} V/m")
    print(f"  Minimum (non-zero): {format_vm(min_value)} V/m")
    print(
        f"  Visualization range: {format_vm(min_cutoff)} - {format_vm(max_cutoff)} V/m"
    )

    # Create output filename
    pdf_filename = f"{base_filename}_multiple_views.pdf"
    pdf_filepath = os.path.join(output_dir, pdf_filename)

    # Load atlas for contours
    atlas_img, atlas_display_name = self._load_atlas(atlas_name, selected_regions)

    # Create multi-slice plot with atlas contours
    self._create_multi_slice_plot_with_atlas(
        averaged_img,
        atlas_img,
        atlas_display_name,
        pdf_filepath,
        min_cutoff,
        max_cutoff,
    )

    print(f"✓ Saved: {pdf_filepath}")
    print(
        f"  Colorbar range: {format_vm(min_cutoff)} - {format_vm(max_cutoff)} V/m"
    )

    return pdf_filepath

field_nifti

field_nifti(subject_id: str, simulation_name: str) -> str

The MNI grey-matter field NIfTI one simulation contributes to these figures.

TI/niftis/grey_<sim>_TI_MNI_MNI_TI_max.nii.gz for a two-pair run, and mTI/niftis/grey_<sim>_mTI_MNI_MNI_mTI_max.nii.gz for an mTI run (:mod:tit.sim.mTI): the same quantity, the modulation depth, named per mode.

Source code in tit/plotting/nilearn/visualizer.py

def field_nifti(subject_id: str, simulation_name: str) -> str:
    """The MNI grey-matter field NIfTI one simulation contributes to these figures.

    ``TI/niftis/grey_<sim>_TI_MNI_MNI_TI_max.nii.gz`` for a two-pair run, and
    ``mTI/niftis/grey_<sim>_mTI_MNI_MNI_mTI_max.nii.gz`` for an mTI run
    (:mod:`tit.sim.mTI`): the same quantity, the modulation depth, named per mode.
    """
    mode = "mTI" if is_mti_simulation(subject_id, simulation_name) else "TI"
    return os.path.join(
        get_path_manager().simulation(subject_id, simulation_name),
        mode,
        "niftis",
        f"grey_{simulation_name}_{mode}_MNI_MNI_{mode}_max.nii.gz",
    )