QSIPrep

https://qsiprep.readthedocs.io/en/latest/
Admin
QSIPrep is a pipeline configuration and preprocessing tool for diffusion-weighted MRI (dMRI) data...
Tokens:58,064
Snippets:501
Trust Score:9.6
Update:2 months ago
Show doc for...
Tokens:
Raw
### Fetch example data

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.bids.html

Initializes the environment with BIDS example data for testing purposes.

```python
>>> import os
>>> from niworkflows import data
>>> data_root = data.get_bids_examples(variant='BIDS-examples-1-enh-ds054')
>>> os.chdir(data_root)
```

--------------------------------

### Install QSIPrep via pip

Source: https://qsiprep.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs the QSIPrep Python library. Note that this method does not include required non-Python dependencies.

```bash
$ pip install --user --upgrade qsiprep
```

--------------------------------

### Example file representation of QSIPrep settings

Source: https://qsiprep.readthedocs.io/en/latest/api.html

A sample ToML configuration file used to store and pass QSIPrep settings across processes.

```toml
[environment]
cpu_count = 1
exec_env = "docker"
free_mem = 52.2
overcommit_policy = "heuristic"
overcommit_limit = "50%"
nipype_version = "1.9.1"
templateflow_version = "23.1.0"
version = "1.0.0rc2.dev29+gdee1425.d20250113"

[execution]
bids_dir = "/tmp/src/qsiprep/.circleci/data/forrest_gump"
bids_database_dir = "/tmp/src/qsiprep/.circleci/work/forrest_gump/20250113-154517_1f7046f7-c5b1-4151-84ca-755a96dfbb55/bids_db"
bids_description_hash = "86891931159357fa937a6724ac27013f79ca56859100547ed9793245866312cd"
boilerplate_only = false
sloppy = true
debug = []
layout = "BIDS Layout: ...ep/.circleci/data/forrest_gump | Subjects: 1 | Sessions: 1 | Runs: 0"
log_dir = "/tmp/src/qsiprep/.circleci/out/forrest_gump/logs"
log_level = 15
low_mem = false
notrack = true
output_dir = "/tmp/src/qsiprep/.circleci/out/forrest_gump"
reports_only = false
run_uuid = "20250113-154517_1f7046f7-c5b1-4151-84ca-755a96dfbb55"
participant_label = [ "01",]
processing_list = [ "01:forrestgump",]
skip_anat_based_spatial_normalization = false
templateflow_home = "/home/qsiprep/.cache/templateflow"
work_dir = "/tmp/src/qsiprep/.circleci/work/forrest_gump"
write_graph = true

[workflow]
anat_modality = "T1w"
anat_only = false
anatomical_template = "MNI152NLin2009cAsym"
b0_threshold = 100
b0_motion_corr_to = "iterative"
b0_to_t1w_transform = "Rigid"
b1_biascorrect_stage = "none"
denoise_after_combining = false
denoise_method = "none"
distortion_group_merge = "none"
dwi_denoise_window = "auto"
dwi_no_biascorr = false
dwi_only = false
fmap_bspline = false
force_syn = false
hmc_model = "eddy"
hmc_transform = "Affine"
ignore = []
infant = false
intramodal_template_iters = 0
intramodal_template_transform = "BSplineSyN"
subject_anatomical_reference = "first-lex"
longitudinal = false
no_b0_harmonization = false
output_resolution = 5.0
pepolar_method = "TOPUP"
separate_all_dwis = false
shoreline_iters = 2
use_syn_sdc = false
spaces = "MNI152NLin2009cAsym"

[nipype]
crashfile_format = "txt"
get_linked_libs = false
nprocs = 4
omp_nthreads = 4
plugin = "MultiProc"
remove_unnecessary_outputs = true
resource_monitor = false
stop_on_first_crash = true

[seeds]
master = 20506
ants = 2720
numpy = 32806

[execution.derivatives]

[execution.dataset_links]
raw = "/tmp/src/qsiprep/.circleci/data/forrest_gump"
templateflow = "/home/qsiprep/.cache/templateflow"

[nipype.plugin_args]
maxtasksperchild = 1
raise_insufficient = false

[execution.bids_filters.t1w]
reconstruction = "autobox"

[execution.bids_filters.t2w]
reconstruction = "autobox"
```

--------------------------------

### Install apt packages in Dockerfile

Source: https://qsiprep.readthedocs.io/en/latest/contributors.html

Use this command within the Dockerfile to install system-level dependencies via apt-get.

```dockerfile
RUN apt-get update && \
    apt-get install -y <PACKAGE>

```

--------------------------------

### Filtering by session and run

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example of a BIDS filter file selecting specific sessions and runs.

```json
{
    "t1w": { "session": "MR1" },
    "dwi": { "session": "MR1", "run": "1" }
}
```

--------------------------------

### Generate TOPUP selection report

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.reports.html

Examples demonstrating how to generate a text summary of image selections for TOPUP distortion correction.

```python
>>> selected_indices = [0, 15, 30, 45]
>>> original_files = ["sub-1_dir-AP_dwi.nii.gz"] * 30 + ["sub-1_dir-PA_dwi.nii.gz"] * 30
>>> spec_lookup = {"sub-1_dir-AP_dwi.nii.gz": "0 1 0 0.087",
...                "sub-1_dir-PA_dwi.nii.gz": "0 -1 0 0.087"}
>>> print(topup_selection_to_report(selected_indices, original_files, spec_lookup))
A total of 2 distortion groups was included in the combined dwi data. Distortion group '0 1 0 0.087' was represented by images 0, 15 from sub-1_dir-AP_dwi.nii.gz. Distortion group '0 -1 0 0.087' was represented by images 0, 15 from sub-1_dir-PA_dwi.nii.gz. 
```

```python
>>> selected_indices = [0, 15, 30, 45]
>>> original_files = ["sub-1_dir-AP_run-1_dwi.nii.gz"] * 15 + [
...                   "sub-1_dir-AP_run-2_dwi.nii.gz"] * 15 + [
...                   "sub-1_dir-PA_dwi.nii.gz"] * 30
>>> spec_lookup = {"sub-1_dir-AP_run-1_dwi.nii.gz": "0 1 0 0.087",
...                "sub-1_dir-AP_run-2_dwi.nii.gz": "0 1 0 0.087",
...                "sub-1_dir-PA_dwi.nii.gz": "0 -1 0 0.087"}
>>> print(topup_selection_to_report(selected_indices, original_files, spec_lookup))
A total of 2 distortion groups was included in the combined dwi data. Distortion group '0 1 0 0.087' was represented by image 0 from sub-1_dir-AP_run-1_dwi.nii.gz and image 0 from sub-1_dir-AP_run-2_dwi.nii.gz. Distortion group '0 -1 0 0.087' was represented by images 0, 15 from sub-1_dir-PA_dwi.nii.gz.
```

--------------------------------

### AddTSVHeader usage example

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.utils.html

Demonstrates how to use AddTSVHeader to prepend column headers to an existing TSV file.

```python
>>> import os
>>> import pandas as pd
>>> import numpy as np
>>> from tempfile import TemporaryDirectory
>>> tmpdir = TemporaryDirectory()
>>> os.chdir(tmpdir.name)
```

```python
>>> np.savetxt('data.tsv', np.arange(30).reshape((6, 5)), delimiter='       ')
```

```python
>>> from qsiprep.interfaces import AddTSVHeader
>>> addheader = AddTSVHeader()
>>> addheader.inputs.in_file = 'data.tsv'
>>> addheader.inputs.columns = ['a', 'b', 'c', 'd', 'e']
>>> res = addheader.run()
>>> pd.read_csv(res.outputs.out_file, sep='\s+', index_col=None,
...             engine='python')  
      a     b     c     d     e
0   0.0   1.0   2.0   3.0   4.0
1   5.0   6.0   7.0   8.0   9.0
2  10.0  11.0  12.0  13.0  14.0
3  15.0  16.0  17.0  18.0  19.0
4  20.0  21.0  22.0  23.0  24.0
5  25.0  26.0  27.0  28.0  29.0
```

```python
>>> tmpdir.cleanup()
```

--------------------------------

### Install apt dependencies in Dockerfile

Source: https://qsiprep.readthedocs.io/en/latest/_sources/contributors.rst.txt

Add non-Python system dependencies using the RUN command in the Dockerfile.

```dockerfile
RUN apt-get update && \
    apt-get install -y <PACKAGE>
```

--------------------------------

### Interpret QSIPrep verbose terminal output

Source: https://qsiprep.readthedocs.io/en/latest/quickstart.html

Example of the log output showing active nodes and resource utilization during workflow execution.

```text
[Node] Setting-up "qsiprep_wf.single_subject_PNC_wf.dwi_finalize_acq_realistic_wf.transform_dwis_t1.final_b0_ref.b0ref_reportlet" in "/scratch/qsiprep_wf/single_subject_PNC_wf/dwi_finalize_acq_realistic_wf/transform_dwis_t1/final_b0_ref/b0ref_reportlet".
  201229-21:33:46,213 nipype.workflow INFO:
    [Node] Running "b0ref_reportlet" ("niworkflows.interfaces.registration.SimpleBeforeAfterRPT")
  201229-21:33:48,51 nipype.workflow INFO:
    [MultiProc] Running 2 tasks, and 3 jobs ready. Free memory (GB): 3.70/4.00, Free processors: 0/2.
                      Currently running:
                        * qsiprep_wf.single_subject_PNC_wf.dwi_finalize_acq_realistic_wf.transform_dwis_t1.final_b0_ref.b0ref_reportlet
                        * qsiprep_wf.single_subject_PNC_wf.anat_preproc_wf.mni_mask
```

--------------------------------

### Example BIDS input file structure

Source: https://qsiprep.readthedocs.io/en/latest/_sources/quickstart.rst.txt

A representation of the expected file hierarchy for DWI and fieldmap data in a BIDS-compliant directory.

```text
sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-01_dwi.nii.gz
sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-01_dwi.nii.gz
sub-1/ses-1/dwi/sub-1_ses-1_acq-multishell_run-03_dwi.nii.gz
sub-1/ses-1/fmap/sub-1_ses-1_dir-PA_epi.nii.gz
```

--------------------------------

### Model Diffusion Signal with SHORE Basis

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.brainsuite_shore.html

Example demonstrating how to model the diffusion signal using the SHORE basis and compute the analytical ODF.

```python
from dipy.data import get_data,get_sphere sphere = get_sphere(‘symmetric724’) fimg, fbvals, fbvecs = get_data(‘ISBI_testing_2shells_table’) bvals, bvecs = read_bvals_bvecs(fbvals, fbvecs) gtab = gradient_table(bvals, bvecs) from dipy.sims.voxel import SticksAndBall data, golden_directions = SticksAndBall(
> gtab, d=0.0015, S0=1., angles=[(0, 0), (90, 0)], fractions=[50, 50], snr=None)
from dipy.reconst.canal import ShoreModel radial_order = 4 zeta = 700 asm = ShoreModel(gtab, radial_order=radial_order, zeta=zeta,
> lambdaN=1e-8, lambdaL=1e-8)
asmfit = asm.fit(data) odf= asmfit.odf(sphere) 
```

--------------------------------

### Build and Run QSIPrep with Apptainer

Source: https://qsiprep.readthedocs.io/en/latest/_sources/installation.rst.txt

Commands to build an Apptainer image and execute it with necessary bindings for data and licenses.

```bash
$ apptainer build qsiprep-<version>.sif docker://pennlinc/qsiprep:<version>
```

```bash
$ apptainer run --containall --writable-tmpfs \
    -B $HOME/fullds005,$HOME/dockerout,${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
    qsiprep-<version>.sif \
    $HOME/fullds005 $HOME/dockerout participant \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2
```

--------------------------------

### QSIPrep Command-Line Help

Source: https://qsiprep.readthedocs.io/en/latest/usage.html

Full list of available command-line arguments and flags for QSIPrep.

```bash
usage: qsiprep [-h] [--skip-bids-validation]
               [--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
               [--session-id SESSION_ID [SESSION_ID ...]]
               [--bids-filter-file FILE] [--bids-database-dir PATH]
               [--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
               [--mem MEMORY_MB] [--low-mem] [--use-plugin FILE] [--sloppy]
               [--anat-only] [--dwi-only] [--boilerplate-only]
               [--reports-only]
               [--ignore {fieldmaps,t2w,phase} [{fieldmaps,t2w,phase} ...]]
               [--infant] [--longitudinal]
               [--subject-anatomical-reference {first-lex,unbiased,sessionwise,first-alphabetically}]
               [--skip-anat-based-spatial-normalization]
               [--anat-modality {T1w,T2w,none}] [--b0-threshold B0_THRESHOLD]
               [--dwi-denoise-window DWI_DENOISE_WINDOW]
               [--denoise-method {dwidenoise,patch2self,none}]
               [--unringing-method {none,mrdegibbs,rpg}] [--dwi-no-biascorr]
               [--b1-biascorrect-stage {final,none,legacy}]
               [--no-b0-harmonization] [--denoise-after-combining]
               [--separate-all-dwis]
               [--distortion-group-merge {concat,average,none}]
               [--anatomical-template {MNI152NLin2009cAsym}]
               --output-resolution OUTPUT_RESOLUTION
               [--b0-to-t1w-transform {Rigid,Affine}]
               [--intramodal-template-iters INTRAMODAL_TEMPLATE_ITERS]
               [--intramodal-template-transform {Rigid,Affine,BSplineSyN,SyN}]
               [--fs-license-file PATH]
               [--b0-motion-corr-to {iterative,first}]
               [--hmc-transform {Affine,Rigid}]
               [--hmc-model {none,3dSHORE,eddy,tensor}]
               [--eddy-config EDDY_CONFIG] [--shoreline-iters SHORELINE_ITERS]
               [--pepolar-method {TOPUP,DRBUDDI,TOPUP+DRBUDDI}]
               [--fmap-bspline] [--fmap-no-demean]
               [--use-syn-sdc [{warn,error}]] [--force-syn] [--version] [-v]
               [-w WORK_DIR] [--resource-monitor] [--config-file FILE]
               [--write-graph] [--stop-on-first-crash] [--notrack]
               [--debug {fieldmaps,pdb,all} [{fieldmaps,pdb,all} ...]]
               bids_dir output_dir {participant}
```

--------------------------------

### DWI Transform File Structure

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example directory structure for DWI transform files.

```text
sub-<label>/
  ses-<label>/
    dwi/
      sub-<label>_ses-<label>_from-orig_to-dwiref_mode-image_desc-eddy_xfm.h5
```

```text
sub-<label>/
  ses-<label>/
    dwi/
      sub-<label>_ses-<label>_from-dwiref_to-ACPC_mode-image_xfm.h5
      sub-<label>_ses-<label>_from-ACPC_to-dwiref_mode-image_xfm.h5
```

--------------------------------

### Managing QSIPrep Configuration

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Demonstrates how to export the current configuration to a TOML file, run a workflow in a subprocess, and reload the configuration.

```python
from qsiprep import config
config_file = config.execution.work_dir / '.qsiprep.toml'
config.to_filename(config_file)
# Call build_workflow(config_file, retval) in a subprocess
with Manager() as mgr:
    from .workflow import build_workflow
    retval = mgr.dict()
    p = Process(target=build_workflow, args=(str(config_file), retval))
    p.start()
    p.join()
config.load(config_file)
# Access configs from any code section as:
value = config.section.setting
```

--------------------------------

### Confound Timeseries TSV Format

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example of the tab-separated values file generated for DWI confounds.

```tsv
framewise_displacement	trans_x	trans_y	trans_z	rot_x	rot_y	rot_z	hmc_r2	hmc_xcorr	original_file	grad_x	grad_y	grad_z	bval

n/a    -0.705	-0.002	0.133	0.119	0.350	0.711	0.941	0.943	sub-abcd_dwi.nii.gz	0.000	0.000	0.000	0.000
16.343	-0.711	-0.075	0.220	0.067	0.405	0.495	0.945	0.946	sub-abcd_dwi.nii.gz	0.000	0.000	0.000	0.000
35.173	-0.672	-0.415	0.725	0.004	0.468	1.055	0.756	0.766	sub-abcd_dwi.nii.gz	-0.356	0.656	0.665	3000.000
45.131	0.021	-0.498	1.046	0.403	0.331	1.400	0.771	0.778	sub-abcd_dwi.nii.gz	-0.935	0.272	0.229	3000.000
37.506	-0.184	0.117	0.723	0.305	0.138	0.964	0.895	0.896	sub-abcd_dwi.nii.gz	-0.187	-0.957	-0.223	2000.000
16.388	-0.447	0.020	0.847	0.217	0.129	0.743	0.792	0.800	sub-abcd_dwi.nii.gz	-0.111	-0.119	0.987	3000.000
```

--------------------------------

### init_synthstrip_wf(do_padding=False, unfatsat=False, name='synthstrip_wf')

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.workflows.anatomical.volume.html

Initializes the SynthStrip workflow.

```APIDOC
## init_synthstrip_wf(do_padding=False, unfatsat=False, name='synthstrip_wf')

### Description
Initializes the SynthStrip workflow.
```

--------------------------------

### qsiprep.config.init_spaces()

Source: https://qsiprep.readthedocs.io/en/latest/api.html

Initializes the spaces setting.

```APIDOC
## qsiprep.config.init_spaces(checkpoint=True)

### Description
Initialize the spaces setting.
```

--------------------------------

### Using regular expressions in filters

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example of using regex to filter T1w scans by acquisition type.

```json
{
    "t1w": { "acquisition": "(?i)mprage", "regex_search": "true" },
}
```

--------------------------------

### Run QSIPrep with Apptainer

Source: https://qsiprep.readthedocs.io/en/latest/installation.html

Execute the container with required directory bindings and Freesurfer license configuration.

```bash
$ apptainer run --containall --writable-tmpfs \
    -B $HOME/fullds005,$HOME/dockerout,${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
    qsiprep-<version>.sif \
    $HOME/fullds005 $HOME/dockerout participant \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2
```

--------------------------------

### Selecting multiple runs

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example of using an array to select multiple run numbers in a BIDS filter.

```json
{
    "dwi": { "run": [2,3] }
}
```

--------------------------------

### Define EPI fieldmap file list

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.fmap.html

Example of defining a list of EPI fieldmap file paths.

```python
>>> epi_fmaps = ["/data/sub-1/fmap/sub-1_dir-AP_epi.nii.gz",
...              "/data/sub-1/fmap/sub-1_dir-PA_epi.nii.gz"]
```

--------------------------------

### qsiprep.config.loggers.init

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Initializes the logging system for QSIPrep.

```APIDOC
## qsiprep.config.loggers.init()

### Description
Configures log levels, initializes sub-loggers (cli, nipype interfaces), and adds custom logging levels (IMPORTANT, VERBOSE).
```

--------------------------------

### Build QSIPrep Apptainer Image

Source: https://qsiprep.readthedocs.io/en/latest/installation.html

Download and build the QSIPrep image from the Docker registry.

```bash
$ apptainer build qsiprep-<version>.sif docker://pennlinc/qsiprep:<version>
```

--------------------------------

### Run QSIPrep with mounted source code

Source: https://qsiprep.readthedocs.io/en/latest/_sources/contributors.rst.txt

Execute the container while mounting local code for testing without rebuilding the image.

```bash
$ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \
    -v $HOME/projects/qsiprep/qsiprep:/usr/local/miniconda/lib/python3.10/site-packages/qsiprep:ro \
    pennlinc/qsiprep:latest /data /out/out participant \
    -w /out/work/
```

--------------------------------

### Group DWI scans for eddy

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.grouping.html

Example of grouping DWI series with phasediff fieldmap information for the eddy tool.

```python
dwi_groups = [ … {‘dwi_series’: [’…/phasediff/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’, … ‘…/phasediff/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz’], … ‘fieldmap_info’: {‘phasediff’: ‘…/phasediff/sub-1/fmap/sub-1_phasediff.nii.gz’, … ‘magnitude1’: ‘…/magnitude1/sub-1/fmap/sub-1_magnitude1.nii.gz’, … ‘suffix’: ‘phasediff’}, … ‘dwi_series_pedir’: ‘j’, … ‘concatenated_bids_name’: ‘sub-1_dir-AP’}] >>> pprint(group_for_eddy(dwi_groups)) # doctest: +NORMALIZE_WHITESPACE ([{‘concatenated_bids_name’: ‘sub-1_dir-AP’,
```

--------------------------------

### qsiprep.config.load

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Loads configuration settings from a TOML file.

```APIDOC
## qsiprep.config.load(filename, skip=None, init=True)

### Description
Load settings from a specified TOML file.

### Parameters
- **filename** (os.PathLike) - Required - TOML file containing QSIPrep configuration.
- **skip** (dict or None) - Optional - Sets of values to ignore during load, keyed by section name
- **init** (bool or Container) - Optional - Initialize all, none, or a subset of configurations.
```

--------------------------------

### qsiprep.config.load

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Loads configuration settings from a specified TOML file.

```APIDOC
## qsiprep.config.load(config_file)

### Description
Reads and applies configuration settings from a TOML file into the active session.

### Parameters
- **config_file** (Path) - Required - The source file path to load configuration from.
```

--------------------------------

### Calculate Total Readout Time (TRT)

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.fmap.html

Examples for calculating TRT using different BIDS metadata fields.

```python
>>> meta = {'TotalReadoutTime': 0.02596}
>>> get_trt(meta)
0.02596
```

```python
>>> meta = {'EffectiveEchoSpacing': 0.00059,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_trt(meta, in_file='epi.nii.gz')
0.02596
```

```python
>>> meta = {'WaterFatShift': 8.129,
...         'MagneticFieldStrength': 3,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_trt(meta, in_file='epi.nii.gz')
0.018721183563864822
```

--------------------------------

### Generate random integers using numpy.random.randint

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.shm.html

Examples of generating random integers with specified sizes and bounds using numpy.random.randint.

```python
>>> np.random.randint(2, size=10)
array([1, 0, 0, 0, 1, 1, 0, 0, 1, 0]) # random
>>> np.random.randint(1, size=10)
array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
```

```python
>>> np.random.randint(5, size=(2, 4))
array([[4, 0, 2, 1], # random
       [3, 2, 2, 0]])
```

```python
>>> np.random.randint(1, [3, 5, 10])
array([2, 2, 9]) # random
```

--------------------------------

### init_dl_prep_wf(name='dl_prep_wf')

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.workflows.anatomical.volume.html

Prepares images for use in the FreeSurfer deep learning functions.

```APIDOC
## init_dl_prep_wf(name='dl_prep_wf')

### Description
Prepare images for use in the FreeSurfer deep learning functions.
```

--------------------------------

### Calculate effective echo spacing

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.fmap.html

Examples of calculating effective echo spacing using different BIDS metadata configurations.

```python
>>> meta = {'EffectiveEchoSpacing': 0.00059,
...         'PhaseEncodingDirection': 'j-'}
>>> get_ees(meta)
0.00059
```

```python
>>> meta = {'TotalReadoutTime': 0.02596,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_ees(meta, in_file='epi.nii.gz')
0.00059
```

```python
>>> meta = {'WaterFatShift': 8.129,
...         'MagneticFieldStrength': 3,
...         'PhaseEncodingDirection': 'j-',
...         'ParallelReductionFactorInPlane': 2}
>>> get_ees(meta, in_file='epi.nii.gz')
0.00041602630141921826
```

--------------------------------

### Initialize QSIPrep HMC and SDC Workflow

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Configures the combined head motion and susceptibility distortion correction workflow using the SHORELine method.

```python
from qsiprep.workflows.dwi.hmc_sdc import init_qsiprep_hmcsdc_wf

wf = init_qsiprep_hmcsdc_wf(
    {
        'dwi_series':['dwi1.nii', 'dwi2.nii'],
        'fieldmap_info': {'suffix': None},
        'dwi_series_pedir': 'j',
    },
    source_file='/data/sub-1/dwi/sub-1_dwi.nii.gz',
    b0_threshold=100,
    hmc_transform='Affine',
    hmc_model='3dSHORE',
    hmc_align_to='iterative',
    template='MNI152NLin2009cAsym',
    shoreline_iters=1,
    impute_slice_threshold=0,
    omp_nthreads=1,
    fmap_bspline=False,
    fmap_demean=False,
    use_syn=True,
    force_syn=False,
    name='qsiprep_hmcsdc_wf',
    dwi_metadata={},
)
```

--------------------------------

### Initialize and configure StructuralReference

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.freesurfer.html

Demonstrates how to instantiate the StructuralReference interface and configure input files and sensitivity settings.

```python
>>> from qsiprep.utils.bids import collect_data
>>> t1w = collect_data('ds114', '01')[0]['t1w']
>>> template = StructuralReference()
>>> template.inputs.in_files = t1w
>>> template.inputs.auto_detect_sensitivity = True
>>> template.cmdline  
'mri_robust_template --satit --mov .../sub-01_ses-retest_T1w.nii.gz
    .../sub-01_ses-test_T1w.nii.gz --template mri_robust_template_out.mgz'
```

--------------------------------

### qsiprep.utils.debug.setup_exceptionhook(ipython=False)

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.debug.html

Configures a custom exception hook to handle post-mortem debugging.

```APIDOC
## setup_exceptionhook(ipython=False)

### Description
Overloads the default sys.excepthook. If the session is interactive, it invokes pdb.post_mortem upon an exception; otherwise, it falls back to the default handler.

### Parameters
- **_ipython** (bool) - Optional - Whether to use IPython-specific handling. Defaults to False.
```

--------------------------------

### Group DWI scans for eddy correction

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.grouping.html

Examples demonstrating how to group various DWI acquisition scenarios for eddy current correction.

```python
from pprint import pprint
dwi_groups = [ 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘dwi’, 
    ‘dwi’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-PA_run-2_dwi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j’, 
    ‘concatenated_bids_name’: ‘sub-1_dir-AP_run-1’}, 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-PA_run-2_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘dwi’, 
    ‘dwi’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j-‘, 
    ‘concatenated_bids_name’: ‘sub-1_dir-PA_run-2’}]
pprint(group_for_eddy(dwi_groups))
```

```python
dwi_groups = [ 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘epi’, 
    ‘epi’: [’…/mixed_fmaps/sub-1/fmap/sub-1_dir-PA_run-1_epi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j’, 
    ‘concatenated_bids_name’: ‘sub-1_dir-AP_run-1’}, 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-PA_run-2_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘epi’, 
    ‘epi’: [’…/mixed_fmaps/sub-1/fmap/sub-1_dir-PA_run-2_epi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j-‘, 
    ‘concatenated_bids_name’: ‘sub-1_dir-PA_run-2’}]
pprint(group_for_eddy(dwi_groups))
```

```python
dwi_groups = [ 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘epi’, 
    ‘epi’: [’…/mixed_fmaps/sub-1/fmap/sub-1_dir-PA_run-1_epi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j’, 
    ‘concatenated_bids_name’: ‘sub-1_dir-AP_run-1’}, 
    {‘dwi_series’: [’…/mixed_fmaps/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘epi’, 
    ‘epi’: [’…/mixed_fmaps/sub-1/fmap/sub-1_dir-PA_run-2_epi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j’, 
    ‘concatenated_bids_name’: ‘sub-1_dir-AP_run-2’}]
pprint(group_for_eddy(dwi_groups))
```

```python
dwi_groups = [ 
    {‘dwi_series’: [’…/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’, 
    ‘…/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘dwi’, 
    ‘dwi’: [’…/sub-1/dwi/sub-1_dir-PA_run-1_dwi.nii.gz’, 
    ‘…/sub-1/dwi/sub-1_dir-PA_run-2_dwi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j’, 
    ‘concatenated_bids_name’: ‘sub-1_dir-AP’}, 
    {‘dwi_series’: [’…/sub-1/dwi/sub-1_dir-PA_run-1_dwi.nii.gz’, 
    ‘…/sub-1/dwi/sub-1_dir-PA_run-2_dwi.nii.gz’], 
    ‘fieldmap_info’: {‘suffix’: ‘dwi’, 
    ‘dwi’: [’…/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz’, 
    ‘…/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz’]}, 
    ‘dwi_series_pedir’: ‘j-‘, 
    ‘concatenated_bids_name’: ‘sub-1_dir-PA’}]
pprint(group_for_eddy(dwi_groups))
```

--------------------------------

### init_qsiprep_wf()

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.workflows.base.html

Organizes the execution of the QSIPrep pipeline, creating a sub-workflow for each subject.

```APIDOC
## init_qsiprep_wf()

### Description
Organize the execution of qsiprep, with a sub-workflow for each subject.
```

--------------------------------

### Build local Docker image

Source: https://qsiprep.readthedocs.io/en/latest/contributors.html

Execute this command from the root of the repository to build a local version of the QSIPrep image.

```bash
~/projects/qsiprep$ docker build -t qsiprep .

```

--------------------------------

### Run QSIPrep Command

Source: https://qsiprep.readthedocs.io/en/latest/_sources/usage.rst.txt

Basic command-line execution for the QSIPrep workflow.

```bash
qsiprep data/bids_root/ out/ participant -w work/ --output-resolution 2
```

--------------------------------

### Generate datain file with EPI fieldmaps

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.fmap.html

Example content for a --datain file when incorporating an external EPI fieldmap series.

```text
0 -1 0 0.087
0 -1 0 0.087
0 -1 0 0.087
0 1 0 0.087
0 1 0 0.087
```

--------------------------------

### Confounds Timeseries TSV Format

Source: https://qsiprep.readthedocs.io/en/latest/preprocessing.html

Example of the TSV file format used for confound timeseries, containing motion parameters and gradient information.

```tsv
framewise_displacement        trans_x trans_y trans_z rot_x   rot_y   rot_z   hmc_r2  hmc_xcorr       original_file   grad_x  grad_y  grad_z  bval

n/a    -0.705 -0.002  0.133   0.119   0.350   0.711   0.941   0.943   sub-abcd_dwi.nii.gz     0.000   0.000   0.000   0.000
16.343        -0.711  -0.075  0.220   0.067   0.405   0.495   0.945   0.946   sub-abcd_dwi.nii.gz     0.000   0.000   0.000   0.000
35.173        -0.672  -0.415  0.725   0.004   0.468   1.055   0.756   0.766   sub-abcd_dwi.nii.gz     -0.356  0.656   0.665   3000.000
45.131        0.021   -0.498  1.046   0.403   0.331   1.400   0.771   0.778   sub-abcd_dwi.nii.gz     -0.935  0.272   0.229   3000.000
37.506        -0.184  0.117   0.723   0.305   0.138   0.964   0.895   0.896   sub-abcd_dwi.nii.gz     -0.187  -0.957  -0.223  2000.000
16.388        -0.447  0.020   0.847   0.217   0.129   0.743   0.792   0.800   sub-abcd_dwi.nii.gz     -0.111  -0.119  0.987   3000.000
```

--------------------------------

### Basic QSIPrep execution command

Source: https://qsiprep.readthedocs.io/en/latest/_sources/quickstart.rst.txt

The standard command structure for running QSIPrep, requiring input/output paths and a FreeSurfer license file.

```bash
qsiprep \
  /path/to/inputs /path/to/outputs participant \
  --output-resolution X \
  --fs-license-file /path/to/license.txt
```

--------------------------------

### qsiprep.config.get()

Source: https://qsiprep.readthedocs.io/en/latest/api.html

Retrieves the current configuration as a dictionary.

```APIDOC
## qsiprep.config.get(flat=False)

### Description
Get config as a dict.
```

--------------------------------

### Generate random integer arrays with NumPy

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.shm.html

Examples of generating random integer arrays using NumPy's randint function with different bounds and broadcasting.

```python
>>> np.random.randint([1, 5, 7], 10)
array([9, 8, 7]) # random
```

```python
>>> np.random.randint([1, 3, 5, 7], [[10], [20]], dtype=np.uint8)
array([[ 8,  6,  9,  7], # random
       [ 1, 16,  9, 12]], dtype=uint8)
```

--------------------------------

### qsiprep.config.dumps

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Formats the current configuration into a TOML string.

```APIDOC
## qsiprep.config.dumps()

### Description
Returns the current configuration as a formatted TOML string.
```

--------------------------------

### Anatomical Derivative Directory Structure

Source: https://qsiprep.readthedocs.io/en/latest/_sources/preprocessing.rst.txt

Example of the anatomical file structure including brain masks, tissue-probability maps, and bias-corrected T1w images in both AC-PC and MNI152NLin2009cAsym spaces.

```text
sub-<label>/[ses-<label>/]
  anat/
    # Brain mask derived from SynthStrip
    <source_entities>_space-ACPC_desc-brain_mask.nii.gz

    # Tissue-probability maps
    <source_entities>_space-ACPC_label-CSF_probseg.nii.gz
    <source_entities>_space-ACPC_label-GM_probseg.nii.gz
    <source_entities>_space-ACPC_label-WM_probseg.nii.gz

    # Tissue class map derived SynthSeg
    <source_entities>_space-ACPC_dseg.nii.gz

    # Bias field corrected T1w file, using ANTS' N4BiasFieldCorrection
    <source_entities>_space-ACPC_desc-preproc_T1w.nii.gz

    # The same files as above, but in the selected output space.
    <source_entities>_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz
    <source_entities>_space-MNI152NLin2009cAsym_label-CSF_probseg.nii.gz
    <source_entities>_space-MNI152NLin2009cAsym_label-GM_probseg.nii.gz
    <source_entities>_space-MNI152NLin2009cAsym_label-WM_probseg.nii.gz
    <source_entities>_space-MNI152NLin2009cAsym_dseg.nii.gz
    <source_entities>_space-MNI152NLin2009cAsym_desc-preproc_T1w.nii.gz
```

--------------------------------

### Rebuild Docker image

Source: https://qsiprep.readthedocs.io/en/latest/_sources/contributors.rst.txt

Build a local image named qsiprep from the current directory.

```bash
~/projects/qsiprep$ docker build -t qsiprep .
```

--------------------------------

### Generate datain file for opposing PE directions

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.interfaces.fmap.html

Example content for a --datain file when using two opposing phase encoding direction DWI series.

```text
0 -1 0 0.087
0 -1 0 0.087
0 -1 0 0.087
0 1 0 0.087
0 1 0 0.087
0 1 0 0.087
```

--------------------------------

### Set up testing environment

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.utils.grouping.html

Initializes the test data environment by changing the working directory to the location of the grouping test data.

```python
>>> import os >>> from qsiprep.utils.testing import get_grouping_test_data >>> data_root = get_grouping_test_data() >>> os.chdir(data_root)
```

--------------------------------

### qsiprep.config.to_filename

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Exports the current configuration settings to a specified TOML file path.

```APIDOC
## qsiprep.config.to_filename(config_file)

### Description
Serializes the current configuration state into a TOML file at the provided path.

### Parameters
- **config_file** (Path) - Required - The destination file path for the TOML configuration.
```

--------------------------------

### Run QSIPrep with Docker

Source: https://qsiprep.readthedocs.io/en/latest/_sources/installation.rst.txt

Executes QSIPrep using a Docker container. Ensure the Freesurfer license is mounted and sufficient memory is allocated to Docker Desktop.

```bash
$ docker run -ti --rm \
    -v /filepath/to/data/dir \
    -v /filepath/to/output/dir \
    -v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
    pennlinc/qsiprep:latest \
    /filepath/to/data/dir /filepath/to/output/dir participant \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2
```

```bash
$ docker run -ti --rm \
    -v $HOME/fullds005 \
    -v $HOME/dockerout \
    -v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
    pennlinc/qsiprep:latest \
    $HOME/fullds005 $HOME/dockerout participant \
    --ignore fieldmaps \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2
```

```bash
$ docker run -ti --rm \
    -v $HOME/fullds005 \
    -v $HOME/dockerout \
    -v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
    pennlinc/qsiprep:latest \
    $HOME/fullds005 -v $HOME/dockerout participant \
    --fs-license-file /opt/freesurfer/license.txt \
    --output-resolution 2
```

--------------------------------

### qsiprep.config.from_dict

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Reads settings from a flat dictionary to apply to the configuration.

```APIDOC
## qsiprep.config.from_dict(settings, init=True, ignore=None)

### Description
Read settings from a flat dictionary and apply them to the configuration.

### Parameters
- **settings** (dict) - Required - Settings to apply to any configuration
- **init** (bool or Container) - Optional - Initialize all, none, or a subset of configurations.
- **ignore** (Container) - Optional - Collection of keys in settings to ignore
```

--------------------------------

### init_dwi_derivatives_wf(source_file)

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.workflows.dwi.derivatives.html

Initializes a workflow to set up a battery of datasinks for storing DWI derivatives in the appropriate locations.

```APIDOC
## init_dwi_derivatives_wf(source_file)

### Description
Sets up a battery of datasinks to store derivatives in the correct location based on the provided source file.

### Parameters
- **source_file** (str) - Required - The path to the source file used to determine the output location for derivatives.

### Returns
- **LiterateWorkflow** - A workflow object configured with the necessary datasinks.
```

--------------------------------

### init_synthstrip_wf

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.workflows.anatomical.html

Initializes the SynthStrip workflow for skull-stripping.

```APIDOC
## init_synthstrip_wf(do_padding=False, unfatsat=False, name='synthstrip_wf')

### Description
Initializes the SynthStrip workflow for skull-stripping.

### Parameters
- **do_padding** (bool) - Optional - Whether to apply padding.
- **unfatsat** (bool) - Optional - Whether to perform unfatsat.
- **name** (str) - Optional - Workflow name, defaults to 'synthstrip_wf'.
```

--------------------------------

### qsiprep.config.to_filename

Source: https://qsiprep.readthedocs.io/en/latest/api/qsiprep.config.html

Writes current configuration settings to a file.

```APIDOC
## qsiprep.config.to_filename(filename)

### Description
Write current settings to a file.

### Parameters
- **filename** (str) - Required - The path to the file where settings will be saved.
```
Tokens:
Raw