Skip to content

nifti

tit.stats.nifti

TI-Toolbox NIfTI Module

TI-Toolbox specific NIfTI file operations. Provides functions for loading subject and group data from TI-Toolbox BIDS structure.

load_subject_nifti_ti_toolbox 

load_subject_nifti_ti_toolbox(subject_id: str, simulation_name: str, nifti_file_pattern: str = 'grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz', dtype=float32) -> tuple[ndarray, Nifti1Image, str]

Load a NIfTI file from TI-Toolbox BIDS structure

Parameters:

subject_id : str Subject ID (e.g., '070') simulation_name : str Simulation name (e.g., 'ICP_RHIPPO') nifti_file_pattern : str, optional Pattern for NIfTI files. Default: 'grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz' Available variables: {subject_id}, {simulation_name} dtype : numpy dtype, optional Data type to load (default: float32)

Returns:

data : ndarray NIfTI data img : nibabel Nifti1Image NIfTI image object filepath : str Full path to the loaded file

Source code in tit/stats/nifti.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def load_subject_nifti_ti_toolbox(
    subject_id: str,
    simulation_name: str,
    nifti_file_pattern: str = "grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz",
    dtype=np.float32,
) -> tuple[np.ndarray, nib.Nifti1Image, str]:
    """
    Load a NIfTI file from TI-Toolbox BIDS structure

    Parameters:
    -----------
    subject_id : str
        Subject ID (e.g., '070')
    simulation_name : str
        Simulation name (e.g., 'ICP_RHIPPO')
    nifti_file_pattern : str, optional
        Pattern for NIfTI files. Default: 'grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz'
        Available variables: {subject_id}, {simulation_name}
    dtype : numpy dtype, optional
        Data type to load (default: float32)

    Returns:
    --------
    data : ndarray
        NIfTI data
    img : nibabel Nifti1Image
        NIfTI image object
    filepath : str
        Full path to the loaded file
    """
    pm = get_path_manager()

    nifti_dir = os.path.join(
        pm.simulation(subject_id, simulation_name),
        "TI",
        "niftis",
    )

    # Format the filename pattern
    filename = nifti_file_pattern.format(
        subject_id=subject_id, simulation_name=simulation_name
    )
    filepath = os.path.join(nifti_dir, filename)

    # Load the file (inline basic loading)
    if not os.path.exists(filepath):
        # Provide extra context to make debugging path/layout issues easier
        if os.path.isdir(nifti_dir):
            try:
                existing = sorted(os.listdir(nifti_dir))
            except OSError:
                existing = []
            preview = existing[:20]
            suffix = ""
            if len(existing) > len(preview):
                suffix = f" (showing first {len(preview)} of {len(existing)})"
            raise FileNotFoundError(
                f"NIfTI file not found: {filepath}. "
                f"Directory exists: {nifti_dir}. "
                f"Files in directory: {preview}{suffix}"
            )
        raise FileNotFoundError(f"NIfTI file not found: {filepath}")

    img = nib.load(filepath)
    data = img.get_fdata(dtype=dtype)

    # Ensure 3D data (squeeze out extra dimensions if present)
    while data.ndim > 3:
        data = np.squeeze(data, axis=-1)

    return data, img, filepath

load_group_data_ti_toolbox 

load_group_data_ti_toolbox(subject_configs: list[dict], nifti_file_pattern: str = 'grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz', dtype=float32) -> tuple[ndarray, Nifti1Image, list[str]]

Load multiple subjects from TI-Toolbox BIDS structure

Parameters:

subject_configs : list of dict List of subject configurations with keys: - 'subject_id': Subject ID (e.g., '070') - 'simulation_name': Simulation name (e.g., 'ICP_RHIPPO') nifti_file_pattern : str, optional Pattern for NIfTI files dtype : numpy dtype, optional Data type to load (default: float32)

Returns:

data_4d : ndarray (x, y, z, n_subjects) 4D array with all loaded data template_img : nibabel Nifti1Image Template image from first subject subject_ids : list of str List of successfully loaded subject IDs

Source code in tit/stats/nifti.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def load_group_data_ti_toolbox(
    subject_configs: list[dict],
    nifti_file_pattern: str = "grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz",
    dtype=np.float32,
) -> tuple[np.ndarray, nib.Nifti1Image, list[str]]:
    """
    Load multiple subjects from TI-Toolbox BIDS structure

    Parameters:
    -----------
    subject_configs : list of dict
        List of subject configurations with keys:
        - 'subject_id': Subject ID (e.g., '070')
        - 'simulation_name': Simulation name (e.g., 'ICP_RHIPPO')
    nifti_file_pattern : str, optional
        Pattern for NIfTI files
    dtype : numpy dtype, optional
        Data type to load (default: float32)

    Returns:
    --------
    data_4d : ndarray (x, y, z, n_subjects)
        4D array with all loaded data
    template_img : nibabel Nifti1Image
        Template image from first subject
    subject_ids : list of str
        List of successfully loaded subject IDs
    """
    data_list = []
    subject_ids = []
    template_img = None
    template_affine = None
    template_header = None

    for config in subject_configs:
        subject_id = config["subject_id"]
        simulation_name = config["simulation_name"]

        data, img, filepath = load_subject_nifti_ti_toolbox(
            subject_id, simulation_name, nifti_file_pattern, dtype=dtype
        )

        # Store template image from first subject
        if template_img is None:
            template_img = img
            template_affine = img.affine.copy()
            template_header = img.header.copy()

        data_list.append(data)
        subject_ids.append(subject_id)

        # Clear the image object to free memory
        del img

    if len(data_list) == 0:
        raise ValueError("No subjects could be loaded successfully")

    # Stack into 4D array
    data_4d = np.stack(data_list, axis=-1).astype(dtype)

    # Recreate minimal template image
    template_img = nib.Nifti1Image(data_4d[..., 0], template_affine, template_header)

    # Clean up
    del data_list
    gc.collect()

    return data_4d, template_img, subject_ids

load_grouped_subjects_ti_toolbox 

load_grouped_subjects_ti_toolbox(subject_configs: list[dict], nifti_file_pattern: str = 'grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz', dtype=float32) -> tuple[dict[str, ndarray], Nifti1Image, dict[str, list[str]]]

Load subjects organized by groups from TI-Toolbox BIDS structure

Parameters:

subject_configs : list of dict List of subject configurations with keys: - 'subject_id': Subject ID (e.g., '070') - 'simulation_name': Simulation name (e.g., 'ICP_RHIPPO') - 'group': Group name (e.g., 'group1', 'Responders', etc.) nifti_file_pattern : str, optional Pattern for NIfTI files dtype : numpy dtype, optional Data type to load (default: float32)

Returns:

groups_data : dict of str -> ndarray Dictionary mapping group names to 4D arrays (x, y, z, n_subjects) template_img : nibabel Nifti1Image Template image from first subject groups_ids : dict of str -> list of str Dictionary mapping group names to lists of subject IDs

Source code in tit/stats/nifti.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def load_grouped_subjects_ti_toolbox(
    subject_configs: list[dict],
    nifti_file_pattern: str = "grey_{simulation_name}_TI_MNI_MNI_TI_max.nii.gz",
    dtype=np.float32,
) -> tuple[dict[str, np.ndarray], nib.Nifti1Image, dict[str, list[str]]]:
    """
    Load subjects organized by groups from TI-Toolbox BIDS structure

    Parameters:
    -----------
    subject_configs : list of dict
        List of subject configurations with keys:
        - 'subject_id': Subject ID (e.g., '070')
        - 'simulation_name': Simulation name (e.g., 'ICP_RHIPPO')
        - 'group': Group name (e.g., 'group1', 'Responders', etc.)
    nifti_file_pattern : str, optional
        Pattern for NIfTI files
    dtype : numpy dtype, optional
        Data type to load (default: float32)

    Returns:
    --------
    groups_data : dict of str -> ndarray
        Dictionary mapping group names to 4D arrays (x, y, z, n_subjects)
    template_img : nibabel Nifti1Image
        Template image from first subject
    groups_ids : dict of str -> list of str
        Dictionary mapping group names to lists of subject IDs
    """
    # Organize configs by group
    groups = {}
    for config in subject_configs:
        group_name = config.get("group", "default")
        if group_name not in groups:
            groups[group_name] = []
        groups[group_name].append(config)

    # Load each group
    groups_data = {}
    groups_ids = {}
    template_img = None

    for group_name, group_configs in groups.items():
        data_4d, img, subject_ids = load_group_data_ti_toolbox(
            group_configs, nifti_file_pattern, dtype=dtype
        )

        groups_data[group_name] = data_4d
        groups_ids[group_name] = subject_ids

        # Use first group's image as template
        if template_img is None:
            template_img = img

    return groups_data, template_img, groups_ids