Skip to main content

Configuration Files

Introduction​

Several preprocessing steps require configuration files that describe your acquisition protocol or analysis parameters. These files tell tools like TOPUP, EDDY, and pyAFQ how your data was acquired and how it should be processed. This page explains each configuration file, what it contains, and how to create one for your specific data.

Most of these files only need to be created once per study, since all subjects typically share the same acquisition protocol. Store them in a central location and reference them in your scripts.

acqp.txt (Acquisition Parameters)​

Used By​

  • TOPUP (Step 6) — to estimate the susceptibility-induced off-resonance field
  • EDDY (Step 8) — to correct for eddy currents and subject motion

Format​

A plain-text file where each row describes one acquisition scheme. Each row contains 4 columns separated by spaces:

ColumnDescription
Columns 1-3Phase encoding direction vector
Column 4Total readout time (in seconds)

Phase Encoding Direction Vectors​

The first three columns specify the direction of phase encoding in image coordinates:

VectorDirectionDescription
0 -1 0Anterior-to-Posterior (AP)Phase encoding along the j-axis, negative direction
0 1 0Posterior-to-Anterior (PA)Phase encoding along the j-axis, positive direction
1 0 0Left-to-Right (LR)Phase encoding along the i-axis, positive direction
-1 0 0Right-to-Left (RL)Phase encoding along the i-axis, negative direction

Example​

0 -1 0 0.0321302
0  1 0 0.0321302

This file describes two acquisitions: the first with AP phase encoding and the second with PA phase encoding, both with a total readout time of approximately 0.032 seconds. This is the standard configuration for a typical AP/PA fieldmap pair.

Determining Your Values​

Phase Encoding Direction​

Check the JSON sidecar file generated by dcm2niix alongside your NIfTI data. Look for the PhaseEncodingDirection field:

JSON Valueacqp.txt VectorDirection
j-0 -1 0Anterior-to-Posterior
j0 1 0Posterior-to-Anterior
i1 0 0Left-to-Right
i--1 0 0Right-to-Left
# Extract the phase encoding direction from a JSON sidecar
cat "$json_sidecar" | python3 -c "import sys, json; print(json.load(sys.stdin)['PhaseEncodingDirection'])"

Total Readout Time​

Check the JSON sidecar for the TotalReadoutTime field:

cat "$json_sidecar" | python3 -c "import sys, json; print(json.load(sys.stdin)['TotalReadoutTime'])"

If TotalReadoutTime is not present in the JSON, you can calculate it from other fields:

TotalReadoutTime = EffectiveEchoSpacing * (ReconMatrixPE - 1)

Where:

  • EffectiveEchoSpacing is the time between the acquisition of consecutive phase-encode lines (in seconds)
  • ReconMatrixPE is the size of the reconstruction matrix in the phase-encode direction

Do not confuse TotalReadoutTime with EchoTime (TE) or DwellTime. These are different parameters. Using the wrong value will result in incorrect distortion correction.

Reference​

index.txt (Volume Index)​

Used By​

  • EDDY (Step 8) — to map each DWI volume to the correct row in acqp.txt

Purpose​

The index file tells eddy which acquisition parameters (from acqp.txt) apply to each volume in your 4D DWI data. Each number in the file corresponds to a row number in acqp.txt.

Format​

A single line of space-separated integers, one per DWI volume. Each integer points to the corresponding row in acqp.txt.

Standard Case: Single Phase-Encoding Direction​

For the most common case where all DWI volumes were acquired with the same phase-encoding direction (e.g., AP), every volume maps to the same row in acqp.txt:

1 1 1 1 1 1 1 1 1 1 ... 1

If your DWI data has 145 volumes, the file should contain 145 ones.

Creating the File​

# Determine the number of volumes in your DWI data
n_vols=$(fslnvols "$dwi_file")

# Create the index file with one entry per volume
printf '1 %.0s' $(seq 1 $n_vols) > index.txt

After Shell Removal​

If you removed specific shells from your data (e.g., a very low shell removed during shell extraction), make sure the number of entries in index.txt matches the number of volumes in the data you pass to eddy. If eddy is run before shell extraction (which is the typical pipeline order), no adjustment is needed.

If your acquisition used alternating phase-encoding directions across volumes (less common), the index file would contain alternating values (e.g., 1 2 1 2 1 2 ...). Consult your acquisition protocol documentation.

afq_config.toml (pyAFQ Configuration)​

Used By​

  • pyAFQ — for automated fiber quantification and tractography

Format​

A TOML format configuration file that specifies all parameters for a pyAFQ run.

Example Configuration​

[files]
bids_path = "/path/to/bids/derivatives"

[bundles]
bundle_info = ["ARC_L", "ARC_R", "CST_L", "CST_R", "CGC_L", "CGC_R", "IFO_L", "IFO_R", "ILF_L", "ILF_R", "SLF_L", "SLF_R", "UNC_L", "UNC_R", "ATR_L", "ATR_R", "FP", "FA"]

[tractography]
n_seeds = 1000

[parallel]
engine = "joblib"
backend = "loky"
n_jobs = -1

Field Explanations​

[files] Section​

FieldDescription
bids_pathAbsolute path to your BIDS derivatives directory containing preprocessed DWI data. pyAFQ expects the data to follow BIDS naming conventions.

[bundles] Section​

FieldDescription
bundle_infoA list of tract bundle abbreviations to segment. Each abbreviation corresponds to a known white matter bundle (e.g., ARC_L = left Arcuate Fasciculus, CST_R = right Corticospinal Tract). The full list of available bundles is in the pyAFQ documentation.

[tractography] Section​

FieldDescription
n_seedsNumber of seed points per voxel used for tractography. Higher values produce denser streamlines but increase computation time. A value of 1000 is a reasonable starting point.

[parallel] Section​

FieldDescription
engineThe parallelization engine. "joblib" is the default and recommended option.
backendThe joblib backend to use. "loky" provides process-based parallelism with better memory management.
n_jobsNumber of parallel jobs. -1 uses all available CPU cores. Set to a positive integer to limit CPU usage (e.g., 4 for four cores).

Reference​