19471672015

Committed 18 Nov 2025 03:32PM UTC coverage: 79.472% (+0.02%) from 79.449%

Build # 19471672015

Build Type

push

github

Committed by

AGrigis

Commit Message

doc: fix documentation.

Coverage Stats

1444 of 1817 relevant lines covered (79.47%)

0.79 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.51

/brainprep/interfaces/fsl.py

##########################################################################
# NSAp - Copyright (C) CEA, 2021 - 2025
# Distributed under the terms of the CeCILL-B license, as published by
# the CEA-CNRS-INRIA. Refer to the LICENSE file or to
# http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
# for details.
##########################################################################


"""
FSL functions.
"""

from pathlib import Path

from ..reporting import log_runtime
from ..typing import (
    Directory,
    File,
)
from ..utils import (
    coerceparams,
    outputdir,
)
from ..wrappers import cmdwrapper


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def reorient(
        image_file: File,
        output_dir: Directory,
        entities: dict) -> tuple[list[str], tuple[File]]:
    """
    Reorients a BIDS-compliant anatomical image using FSL's `fslreorient2std`.

    Parameters
    ----------
    image_file : File
        Path to the input image file.
    output_dir : Directory
        Directory where the reoriented image will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.

    Returns
    -------
    command : list[str]
        Reorientation command-line.
    outputs : tuple[File]
        - reorient_image_file : File - Reoriented input image file.
    """
    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-T1w_reorient".format(
        **entities)
    reorient_image_file = output_dir / f"{basename}.nii.gz"

    command = [
        "fslreorient2std",
        str(image_file),
        str(reorient_image_file)
    ]

    return command, (reorient_image_file, )


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def deface(
        t1_file: File,
        output_dir: Directory,
        entities: dict) -> tuple[list[str], tuple[File | list[File]]]:
    """
    Defaces a BIDS-compliant T1-weighted anatomical image using FSL's
    `fsl_deface`.

    Parameters
    ----------
    t1_file : File
        Path to the input T1w image file.
    output_dir : Directory
        Directory where the defaced T1w image will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.

    Returns
    -------
    command : list[str]
        Defacing command-line.
    outputs : tuple[File | list[File]]
        - deface_file : File - Defaced input T1w image file.
        - mask_file : File - Defacing binary mask.
        - vol_files : list[File] - Defacing 3d rendering.

    Raises
    ------
    ValueError
        If the input image is not a T1-weighted image.
    """
    modality = entities.get("mod")
    if modality is None or modality != "T1w":
        raise ValueError(
            f"The '{t1_file}' input anatomical file must be a T1w image."
        )

    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-T1w_deface".format(
        **entities)
    deface_file = output_dir / f"{basename}.nii.gz"
    mask_file = output_dir / f"{basename}mask.nii.gz"
    snap_pattern = output_dir / basename

    command = [
        "fsl_deface",
        str(t1_file),
        str(deface_file),
        "-d", str(mask_file),
        "-f", "0.5",
        "-B",
        "-p", str(snap_pattern),
    ]
    vol_files = [Path(f"{snap_pattern}_{idx}.png") for idx in range(1, 3)]

    return command, (deface_file, mask_file, vol_files)


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def applymask(
        image_file: File,
        mask_file: File,
        output_dir: Directory,
        entities: dict) -> tuple[list[str], tuple[File]]:
    """
    Apply an isotropic resampling transformation to a BIDS-compliant image
    file using FSL's `fslmaths`.

    Parameters
    ----------
    image_file : File
        Path to the input image file.
    mask_file : File
        Path to a binary mask file.
    output_dir : Directory
        Directory where the masked image will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.

    Returns
    -------
    command : list[str]
        Masking command-line.
    outputs : tuple[File]
        - masked_image_file : File - masked input image file.
    """
    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_applymask".format(
        **entities)
    masked_image_file = output_dir / f"{basename}.nii.gz"

    command = [
        "fslmaths",
        str(image_file),
        "-mas", str(mask_file),
        str(masked_image_file),
    ]

    return command, (masked_image_file, )


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def scale(
        image_file: File,
        scale: int,
        output_dir: Directory,
        entities: dict) -> tuple[list[str], tuple[File]]:
    """
    Apply an isotropic resampling transformation to a BIDS-compliant image
    file using FSL's `flirt`.

    Parameters
    ----------
    image_file : File
        Path to the input image file.
    scale : int
        Scale factor applied in all directions.
    output_dir : Directory
        Directory where the scaled image will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.

    Returns
    -------
    command : list[str]
        Scaling command-line.
    outputs : tuple[File]
        - scaled_anatomical_file : File - Scaled input image file.
        - transform_file : File - The associated transformation file.
    """
    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_scale".format(
        **entities)
    scaled_anatomical_file = output_dir / f"{basename}.nii.gz"
    transform_file = output_dir / f"{basename}.txt"

    command = [
        "flirt",
        "-in", str(image_file),
        "-ref", str(image_file),
        "-applyisoxfm", str(scale),
        "-out", str(scaled_anatomical_file),
        "-omat", str(transform_file),
        "-verbose", "1",
    ]

    return command, (scaled_anatomical_file, transform_file)


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def affine(
        anatomical_file: File,
        template_file: File,
        output_dir: Directory,
        entities: dict) -> tuple[list[str], tuple[File]]:
    """
    Affinely register a BIDS-compliant anatomical image to a template file
    using FSL's `flirt`.

    Parameters
    ----------
    anatomical_file : File
        Path to the input image file.
    template_file: File
        Path to the image file defining the template space.
    output_dir : Directory
        Directory where the affine transformation will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.

    Returns
    -------
    command : list[str]
        Registration command-line.
    outputs : tuple[File]
        - aligned_anatomical_file : File - Aligned input image file.
        - transform_file : File - The affine transformation file.
    """
    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_affine".format(
        **entities)
    aligned_anatomical_file = output_dir / f"{basename}.nii.gz"
    transform_file = output_dir / f"{basename}.txt"

    command = [
        "flirt",
        "-in", str(anatomical_file),
        "-ref", str(template_file),
        "-cost", "normmi",
        "-searchcost", "normmi",
        "-anglerep", "euler",
        "-bins", "256",
        "-interp", "trilinear",
        "-dof", "9",
        "-out", str(aligned_anatomical_file),
        "-omat", str(transform_file),
        "-verbose", "1"
    ]

    return command, (aligned_anatomical_file, transform_file)


@coerceparams
@outputdir
@log_runtime(
    bunched=False)
@cmdwrapper
def applyaffine(
        image_file: File,
        template_file: File,
        transform_file: File,
        output_dir: Directory,
        entities: dict,
        interpolation: str = "spline") -> tuple[list[str], tuple[File]]:
    """
    Apply an affine transformation to a BIDS-compliant image file using FSL's
    `flirt`.

    Parameters
    ----------
    image_file : File
        Path to the input image file.
    template_file: File
        Path to the image file defining the template space.
    transform_file : File
        Path to the affine transformation file.
    output_dir : Directory
        Directory where the aligned image will be saved.
    entities : dict
        A dictionary of parsed BIDS entities including modality.
    interpolation: str
        The interpolation method: 'trilinear', 'nearestneighbour', 'sinc', or
        'spline'. Default 'spline'.

    Returns
    -------
    command : list[str]
        Alignment command-line.
    outputs : tuple[File]
        - aligned_image_file : File - Aligned input image file.
    """
    basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_applyaffine".format(
        **entities)
    aligned_image_file = output_dir / f"{basename}.nii.gz"

    command = [
        "flirt",
        "-in", str(image_file),
        "-ref", str(template_file),
        "-init", str(transform_file),
        "-interp", str(interpolation),
        "-applyxfm",
        "-out", str(aligned_image_file),
    ]

    return command, (aligned_image_file, )

1	##########################################################################
2	# NSAp - Copyright (C) CEA, 2021 - 2025
3	# Distributed under the terms of the CeCILL-B license, as published by
4	# the CEA-CNRS-INRIA. Refer to the LICENSE file or to
5	# http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
6	# for details.
7	##########################################################################
8
9
10	"""
11	FSL functions.
12	"""
13
14	from pathlib import Path	1✔
15
16	from ..reporting import log_runtime	1✔
17	from ..typing import (	1✔
18	Directory,
19	File,
20	)
21	from ..utils import (	1✔
22	coerceparams,
23	outputdir,
24	)
25	from ..wrappers import cmdwrapper	1✔
26
27
28	@coerceparams	1✔
29	@outputdir	1✔
30	@log_runtime(	1✔
31	bunched=False)
32	@cmdwrapper	1✔
33	def reorient(	1✔
34	image_file: File,
35	output_dir: Directory,
36	entities: dict) -> tuple[list[str], tuple[File]]:
37	"""
38	Reorients a BIDS-compliant anatomical image using FSL's `fslreorient2std`.
39
40	Parameters
41	----------
42	image_file : File
43	Path to the input image file.
44	output_dir : Directory
45	Directory where the reoriented image will be saved.
46	entities : dict
47	A dictionary of parsed BIDS entities including modality.
48
49	Returns
50	-------
51	command : list[str]
52	Reorientation command-line.
53	outputs : tuple[File]
54	- reorient_image_file : File - Reoriented input image file.
55	"""
56	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-T1w_reorient".format(	1✔
57	**entities)
58	reorient_image_file = output_dir / f"{basename}.nii.gz"	1✔
59
60	command = [	1✔
61	"fslreorient2std",
62	str(image_file),
63	str(reorient_image_file)
64	]
65
66	return command, (reorient_image_file, )	1✔
67
68
69	@coerceparams	1✔
70	@outputdir	1✔
71	@log_runtime(	1✔
72	bunched=False)
73	@cmdwrapper	1✔
74	def deface(	1✔
75	t1_file: File,
76	output_dir: Directory,
77	entities: dict) -> tuple[list[str], tuple[File \| list[File]]]:
78	"""
79	Defaces a BIDS-compliant T1-weighted anatomical image using FSL's
80	`fsl_deface`.
81
82	Parameters
83	----------
84	t1_file : File
85	Path to the input T1w image file.
86	output_dir : Directory
87	Directory where the defaced T1w image will be saved.
88	entities : dict
89	A dictionary of parsed BIDS entities including modality.
90
91	Returns
92	-------
93	command : list[str]
94	Defacing command-line.
95	outputs : tuple[File \| list[File]]
96	- deface_file : File - Defaced input T1w image file.
97	- mask_file : File - Defacing binary mask.
98	- vol_files : list[File] - Defacing 3d rendering.
99
100	Raises
101	------
102	ValueError
103	If the input image is not a T1-weighted image.
104	"""
105	modality = entities.get("mod")	1✔
106	if modality is None or modality != "T1w":	1✔
107	raise ValueError(	×
108	f"The '{t1_file}' input anatomical file must be a T1w image."
109	)
110
111	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-T1w_deface".format(	1✔
112	**entities)
113	deface_file = output_dir / f"{basename}.nii.gz"	1✔
114	mask_file = output_dir / f"{basename}mask.nii.gz"	1✔
115	snap_pattern = output_dir / basename	1✔
116
117	command = [	1✔
118	"fsl_deface",
119	str(t1_file),
120	str(deface_file),
121	"-d", str(mask_file),
122	"-f", "0.5",
123	"-B",
124	"-p", str(snap_pattern),
125	]
126	vol_files = [Path(f"{snap_pattern}_{idx}.png") for idx in range(1, 3)]	1✔
127
128	return command, (deface_file, mask_file, vol_files)	1✔
129
130
131	@coerceparams	1✔
132	@outputdir	1✔
133	@log_runtime(	1✔
134	bunched=False)
135	@cmdwrapper	1✔
136	def applymask(	1✔
137	image_file: File,
138	mask_file: File,
139	output_dir: Directory,
140	entities: dict) -> tuple[list[str], tuple[File]]:
141	"""
142	Apply an isotropic resampling transformation to a BIDS-compliant image
143	file using FSL's `fslmaths`.
144
145	Parameters
146	----------
147	image_file : File
148	Path to the input image file.
149	mask_file : File
150	Path to a binary mask file.
151	output_dir : Directory
152	Directory where the masked image will be saved.
153	entities : dict
154	A dictionary of parsed BIDS entities including modality.
155
156	Returns
157	-------
158	command : list[str]
159	Masking command-line.
160	outputs : tuple[File]
161	- masked_image_file : File - masked input image file.
162	"""
163	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_applymask".format(	1✔
164	**entities)
165	masked_image_file = output_dir / f"{basename}.nii.gz"	1✔
166
167	command = [	1✔
168	"fslmaths",
169	str(image_file),
170	"-mas", str(mask_file),
171	str(masked_image_file),
172	]
173
174	return command, (masked_image_file, )	1✔
175
176
177	@coerceparams	1✔
178	@outputdir	1✔
179	@log_runtime(	1✔
180	bunched=False)
181	@cmdwrapper	1✔
182	def scale(	1✔
183	image_file: File,
184	scale: int,
185	output_dir: Directory,
186	entities: dict) -> tuple[list[str], tuple[File]]:
187	"""
188	Apply an isotropic resampling transformation to a BIDS-compliant image
189	file using FSL's `flirt`.
190
191	Parameters
192	----------
193	image_file : File
194	Path to the input image file.
195	scale : int
196	Scale factor applied in all directions.
197	output_dir : Directory
198	Directory where the scaled image will be saved.
199	entities : dict
200	A dictionary of parsed BIDS entities including modality.
201
202	Returns
203	-------
204	command : list[str]
205	Scaling command-line.
206	outputs : tuple[File]
207	- scaled_anatomical_file : File - Scaled input image file.
208	- transform_file : File - The associated transformation file.
209	"""
210	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_scale".format(	1✔
211	**entities)
212	scaled_anatomical_file = output_dir / f"{basename}.nii.gz"	1✔
213	transform_file = output_dir / f"{basename}.txt"	1✔
214
215	command = [	1✔
216	"flirt",
217	"-in", str(image_file),
218	"-ref", str(image_file),
219	"-applyisoxfm", str(scale),
220	"-out", str(scaled_anatomical_file),
221	"-omat", str(transform_file),
222	"-verbose", "1",
223	]
224
225	return command, (scaled_anatomical_file, transform_file)	1✔
226
227
228	@coerceparams	1✔
229	@outputdir	1✔
230	@log_runtime(	1✔
231	bunched=False)
232	@cmdwrapper	1✔
233	def affine(	1✔
234	anatomical_file: File,
235	template_file: File,
236	output_dir: Directory,
237	entities: dict) -> tuple[list[str], tuple[File]]:
238	"""
239	Affinely register a BIDS-compliant anatomical image to a template file
240	using FSL's `flirt`.
241
242	Parameters
243	----------
244	anatomical_file : File
245	Path to the input image file.
246	template_file: File
247	Path to the image file defining the template space.
248	output_dir : Directory
249	Directory where the affine transformation will be saved.
250	entities : dict
251	A dictionary of parsed BIDS entities including modality.
252
253	Returns
254	-------
255	command : list[str]
256	Registration command-line.
257	outputs : tuple[File]
258	- aligned_anatomical_file : File - Aligned input image file.
259	- transform_file : File - The affine transformation file.
260	"""
261	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_affine".format(	1✔
262	**entities)
263	aligned_anatomical_file = output_dir / f"{basename}.nii.gz"	1✔
264	transform_file = output_dir / f"{basename}.txt"	1✔
265
266	command = [	1✔
267	"flirt",
268	"-in", str(anatomical_file),
269	"-ref", str(template_file),
270	"-cost", "normmi",
271	"-searchcost", "normmi",
272	"-anglerep", "euler",
273	"-bins", "256",
274	"-interp", "trilinear",
275	"-dof", "9",
276	"-out", str(aligned_anatomical_file),
277	"-omat", str(transform_file),
278	"-verbose", "1"
279	]
280
281	return command, (aligned_anatomical_file, transform_file)	1✔
282
283
284	@coerceparams	1✔
285	@outputdir	1✔
286	@log_runtime(	1✔
287	bunched=False)
288	@cmdwrapper	1✔
289	def applyaffine(	1✔
290	image_file: File,
291	template_file: File,
292	transform_file: File,
293	output_dir: Directory,
294	entities: dict,
295	interpolation: str = "spline") -> tuple[list[str], tuple[File]]:
296	"""
297	Apply an affine transformation to a BIDS-compliant image file using FSL's
298	`flirt`.
299
300	Parameters
301	----------
302	image_file : File
303	Path to the input image file.
304	template_file: File
305	Path to the image file defining the template space.
306	transform_file : File
307	Path to the affine transformation file.
308	output_dir : Directory
309	Directory where the aligned image will be saved.
310	entities : dict
311	A dictionary of parsed BIDS entities including modality.
312	interpolation: str
313	The interpolation method: 'trilinear', 'nearestneighbour', 'sinc', or
314	'spline'. Default 'spline'.
315
316	Returns
317	-------
318	command : list[str]
319	Alignment command-line.
320	outputs : tuple[File]
321	- aligned_image_file : File - Aligned input image file.
322	"""
323	basename = "sub-{sub}_ses-{ses}_run-{run}_mod-{mod}_applyaffine".format(	1✔
324	**entities)
325	aligned_image_file = output_dir / f"{basename}.nii.gz"	1✔
326
327	command = [	1✔
328	"flirt",
329	"-in", str(image_file),
330	"-ref", str(template_file),
331	"-init", str(transform_file),
332	"-interp", str(interpolation),
333	"-applyxfm",
334	"-out", str(aligned_image_file),
335	]
336
337	return command, (aligned_image_file, )	1✔

neurospin-deepinsight / brainprep / 19471672015

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous