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

89.66

/brainprep/workflow/dmriprep.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.
##########################################################################


"""
Diffusion MRI pre-processing.
"""

import shutil

import brainprep.interfaces as interfaces

from ..reporting import (
    log_runtime,
    save_runtime,
)
from ..typing import (
    Directory,
    File,
)
from ..utils import (
    Bunch,
    bids,
    coerceparams,
    parse_bids_keys,
    print_info,
)


@coerceparams
@bids(
    process="dmriprep",
    bids_file="t1_file",
    add_subjects=True,
    container="neurospin/brainprep-dmriprep")
@log_runtime(
    title="Subject Level Diffusion Pre-Processing")
@save_runtime
def brainprep_dmriprep(
        t1_file: File,
        dwi_file: File,
        bvec_file: File,
        bval_file: File,
        output_dir: Directory,
        keep_intermediate: bool = False) -> Bunch:
    """
    Diffusion MRI pre-processing.

    Applies the pre-processing described in :footcite:p:`cai2021prequal`.
    This includes:

    1) Gradient direction sanity check.
    2) MP-PCA denoising.
    3) Gibbs unringing.
    4) N4 B1 bias field correction.
    5) Head Motion Correction (shelled schemes).
    6) Fieldmapless Distortion Correction: Synb0.
    7) HTML Report.

    Parameters
    ----------
    t1_file : File
        Path to the t1 image (used during Synb0 - synthesized b0 for diffusion
        distortion correction).
    dwi_file : File
        Path to the diffusion weighted image.
    bvec_file : File
        Path to the bvec file.
    bval_file : File
        Path to the bval file.
    output_dir : Directory
        Path to the output directory.
    keep_intermediate : bool
        If True, retains intermediate results (i.e., the workspace); useful
        for debugging. Default False.

    Returns
    -------
    Bunch
        A dictionary-like object containing:

        - dwi_file: File - path to the NIIGZ pre-processed diffusion weighted
          image.
        - bvec_file: File - path to the TXT pre-processed bvec file.
        - bval_file: File - path to the TXT pre-processed bval file.
        - qc_file: File - path to the PDF visual report.

    Raises
    ------
    ValueError
        If the T1w file do not follow BIDS convension.

    Notes
    -----
    - For the Synb0 feature to work you must bind your FreeSurfer license in
      the '/APPS/freesurfer/license.txt' location.

    References
    ----------

    .. footbibliography::
    """
    workspace_dir = output_dir / "workspace"
    workspace_dir.mkdir(parents=True, exist_ok=True)

    entities = parse_bids_keys(t1_file)
    if len(entities) == 0:
        raise ValueError(
            f"The T1w file '{t1_file}' is not BIDS-compliant."
        )

    dwi_file, bvec_file, bval_file, qc_file = interfaces.prequal_wf(
        t1_file,
        dwi_file,
        bvec_file,
        bval_file,
        workspace_dir,
        output_dir,
        entities,
    )

    if not keep_intermediate:
        print_info(f"cleaning workspace directory: {workspace_dir}")
        shutil.rmtree(workspace_dir)

    return Bunch(
        dwi_file=dwi_file,
        bvec_file=bvec_file,
        bval_file=bval_file,
        qc_file=qc_file,
    )


@coerceparams
@bids(
    process="dmriprep",
    container="neurospin/brainprep-dmriprep")
@log_runtime(
    title="Group Level Diffusion Pre-Processing")
@save_runtime
def brainprep_group_dmriprep(
        output_dir: Directory,
        lower_fa_threshold: float = 0.3,
        upper_fa_threshold: float = 0.75,
        keep_intermediate: bool = False) -> Bunch:
    """
    Group level diffusion MRI pre-processing.

    Parameters
    ----------
    output_dir : Directory
        Working directory containing all the subjects.
    lower_fa_threshold : float
        Quality control lower threshold on the fractional anisotropy (FA).
        Default 0.3
    upper_fa_threshold : float
        Quality control upper threshold on the fractional anisotropy (FA).
        Default 0.75
    keep_intermediate : bool
        If True, retains intermediate results (i.e., the workspace); useful
        for debugging. Default False

    Returns
    -------
    Bunch
        A dictionary-like object containing:

        - group_stats_file : File - a TSV file containing summary information
          on fiber bunbles and displacements.
        - histogram_files : list[File] - PNG files containing histograms of
          selected important information.
    """
    bundles = (
        "Genu_of_corpus_callosum_med_fa",
        "Body_of_corpus_callosum_med_fa",
        "Splenium_of_corpus_callosum_med_fa",
        "Corticospinal_tract_L_med_fa",
        "Corticospinal_tract_R_med_fa",
    )

    group_stats_file = interfaces.prequal_stats(
        output_dir / "qc",
        bundles,
        lower_fa_threshold,
        upper_fa_threshold,
    )

    histogram_files = [
        interfaces.plot_histogram(
            group_stats_file,
            "eddy_avg_abs_displacement",
            output_dir / "qc",
        ),
        *[
            interfaces.plot_histogram(
                group_stats_file,
                fa_bundle,
                output_dir / "qc",
                bar_coords=[lower_fa_threshold, upper_fa_threshold],
            ) for fa_bundle in bundles
        ],
    ]

    return Bunch(
        group_stats_file=group_stats_file,
        histogram_files=histogram_files,
    )

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	Diffusion MRI pre-processing.
12	"""
13
14	import shutil	1✔
15
16	import brainprep.interfaces as interfaces	1✔
17
18	from ..reporting import (	1✔
19	log_runtime,
20	save_runtime,
21	)
22	from ..typing import (	1✔
23	Directory,
24	File,
25	)
26	from ..utils import (	1✔
27	Bunch,
28	bids,
29	coerceparams,
30	parse_bids_keys,
31	print_info,
32	)
33
34
35	@coerceparams	1✔
36	@bids(	1✔
37	process="dmriprep",
38	bids_file="t1_file",
39	add_subjects=True,
40	container="neurospin/brainprep-dmriprep")
41	@log_runtime(	1✔
42	title="Subject Level Diffusion Pre-Processing")
43	@save_runtime	1✔
44	def brainprep_dmriprep(	1✔
45	t1_file: File,
46	dwi_file: File,
47	bvec_file: File,
48	bval_file: File,
49	output_dir: Directory,
50	keep_intermediate: bool = False) -> Bunch:
51	"""
52	Diffusion MRI pre-processing.
53
54	Applies the pre-processing described in :footcite:p:`cai2021prequal`.
55	This includes:
56
57	1) Gradient direction sanity check.
58	2) MP-PCA denoising.
59	3) Gibbs unringing.
60	4) N4 B1 bias field correction.
61	5) Head Motion Correction (shelled schemes).
62	6) Fieldmapless Distortion Correction: Synb0.
63	7) HTML Report.
64
65	Parameters
66	----------
67	t1_file : File
68	Path to the t1 image (used during Synb0 - synthesized b0 for diffusion
69	distortion correction).
70	dwi_file : File
71	Path to the diffusion weighted image.
72	bvec_file : File
73	Path to the bvec file.
74	bval_file : File
75	Path to the bval file.
76	output_dir : Directory
77	Path to the output directory.
78	keep_intermediate : bool
79	If True, retains intermediate results (i.e., the workspace); useful
80	for debugging. Default False.
81
82	Returns
83	-------
84	Bunch
85	A dictionary-like object containing:
86
87	- dwi_file: File - path to the NIIGZ pre-processed diffusion weighted
88	image.
89	- bvec_file: File - path to the TXT pre-processed bvec file.
90	- bval_file: File - path to the TXT pre-processed bval file.
91	- qc_file: File - path to the PDF visual report.
92
93	Raises
94	------
95	ValueError
96	If the T1w file do not follow BIDS convension.
97
98	Notes
99	-----
100	- For the Synb0 feature to work you must bind your FreeSurfer license in
101	the '/APPS/freesurfer/license.txt' location.
102
103	References
104	----------
105
106	.. footbibliography::
107	"""
108	workspace_dir = output_dir / "workspace"	1✔
109	workspace_dir.mkdir(parents=True, exist_ok=True)	1✔
110
111	entities = parse_bids_keys(t1_file)	1✔
112	if len(entities) == 0:	1✔
113	raise ValueError(	×
114	f"The T1w file '{t1_file}' is not BIDS-compliant."
115	)
116
117	dwi_file, bvec_file, bval_file, qc_file = interfaces.prequal_wf(	1✔
118	t1_file,
119	dwi_file,
120	bvec_file,
121	bval_file,
122	workspace_dir,
123	output_dir,
124	entities,
125	)
126
127	if not keep_intermediate:	1✔
128	print_info(f"cleaning workspace directory: {workspace_dir}")	×
129	shutil.rmtree(workspace_dir)	×
130
131	return Bunch(	1✔
132	dwi_file=dwi_file,
133	bvec_file=bvec_file,
134	bval_file=bval_file,
135	qc_file=qc_file,
136	)
137
138
139	@coerceparams	1✔
140	@bids(	1✔
141	process="dmriprep",
142	container="neurospin/brainprep-dmriprep")
143	@log_runtime(	1✔
144	title="Group Level Diffusion Pre-Processing")
145	@save_runtime	1✔
146	def brainprep_group_dmriprep(	1✔
147	output_dir: Directory,
148	lower_fa_threshold: float = 0.3,
149	upper_fa_threshold: float = 0.75,
150	keep_intermediate: bool = False) -> Bunch:
151	"""
152	Group level diffusion MRI pre-processing.
153
154	Parameters
155	----------
156	output_dir : Directory
157	Working directory containing all the subjects.
158	lower_fa_threshold : float
159	Quality control lower threshold on the fractional anisotropy (FA).
160	Default 0.3
161	upper_fa_threshold : float
162	Quality control upper threshold on the fractional anisotropy (FA).
163	Default 0.75
164	keep_intermediate : bool
165	If True, retains intermediate results (i.e., the workspace); useful
166	for debugging. Default False
167
168	Returns
169	-------
170	Bunch
171	A dictionary-like object containing:
172
173	- group_stats_file : File - a TSV file containing summary information
174	on fiber bunbles and displacements.
175	- histogram_files : list[File] - PNG files containing histograms of
176	selected important information.
177	"""
178	bundles = (	1✔
179	"Genu_of_corpus_callosum_med_fa",
180	"Body_of_corpus_callosum_med_fa",
181	"Splenium_of_corpus_callosum_med_fa",
182	"Corticospinal_tract_L_med_fa",
183	"Corticospinal_tract_R_med_fa",
184	)
185
186	group_stats_file = interfaces.prequal_stats(	1✔
187	output_dir / "qc",
188	bundles,
189	lower_fa_threshold,
190	upper_fa_threshold,
191	)
192
193	histogram_files = [	1✔
194	interfaces.plot_histogram(
195	group_stats_file,
196	"eddy_avg_abs_displacement",
197	output_dir / "qc",
198	),
199	*[
200	interfaces.plot_histogram(
201	group_stats_file,
202	fa_bundle,
203	output_dir / "qc",
204	bar_coords=[lower_fa_threshold, upper_fa_threshold],
205	) for fa_bundle in bundles
206	],
207	]
208
209	return Bunch(	1✔
210	group_stats_file=group_stats_file,
211	histogram_files=histogram_files,
212	)

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