The registration article in this series starts with a motion-corrected BOLD time series. Here, we focus on saving a FEAT configuration, running it from a Linux terminal, and inspecting the resulting images and processing records.
The initial configuration and visual checks require a graphical desktop session.
Scope: The example runs motion correction and brain masking in native functional space, with smoothing and temporal filtering disabled. It teaches FEAT configuration and output inspection; it does not define a complete preprocessing pipeline. The commands follow official documentation but have not been tested end to end on imaging data.
1. Establish what the input contains
Use a single-echo, 4D human BOLD NIfTI image with whole-brain coverage. For this example, the run should not already have undergone motion correction, spatial smoothing, or temporal filtering. Keep the original file unchanged.
Before processing, establish:
- The repetition time (TR) and number of stored volumes.
- Whether initial non-steady-state volumes are still present or were already discarded.
- What corrections, if any, were applied during reconstruction or earlier processing.
- Which acquisition metadata and fieldmap images are available for distortion correction.
Use the acquisition records and accompanying metadata to resolve these questions. A filename such as bold.nii.gz does not describe the processing history.
FSL must already be installed and configured in the terminal. See Installing FSL and FIX on Linux for setup. FIX and ANTs are not required for this article.
Create a fresh working directory for this trial and replace the example input path. The mktemp command creates a uniquely named directory under fsl-feat-tutorial; keep it with your processing records. Run the following blocks in the same Bash session:
mkdir -p "$HOME/fsl-feat-tutorial" WORK="$(mktemp -d "$HOME/fsl-feat-tutorial/run01_trial_XXXXXX")" cd "$WORK" WORK="$(pwd -P)" BOLD="/absolute/path/to/sub-001_task-rest_bold.nii.gz" OUT="$WORK/preproc.feat" export FSLOUTPUTTYPE=NIFTI_GZ for cmd in feat Feat fslinfo fslhd fslval fslmaths fsleyes; do command -v "$cmd" >/dev/null || printf 'Missing command: %s\n' "$cmd" >&2 done test -r "$BOLD" || printf 'ERROR: Cannot read %s\n' "$BOLD" >&2 cat "$FSLDIR/etc/fslversion" fslinfo "$BOLD" fslhd "$BOLD" > "$WORK/input_header.txt" cat "$FSLDIR/etc/fslversion" > "$WORK/fsl_version.txt" printf 'Input: %s\nOutput: %s\nSave setup as: %s\n' \ "$BOLD" "$OUT" "$WORK/design.fsf" If you see Missing command or ERROR, resolve the problem before continuing. These interactive blocks report problems but do not automatically stop the shell.
Inspect the header and compare the volume count and TR with the acquisition metadata. Check the temporal units when interpreting pixdim4; FEAT's TR field uses seconds. Investigate discrepancies rather than editing the header simply to make values agree. The FSL utilities documentation describes the inspection tools used here.
Also inspect the input images before processing:
fsleyes "$BOLD" Check brain coverage, orientation labels, and obvious artifacts across time. This gives you a baseline for comparison with the processed images. The example assumes that the default reference—the middle volume of the retained run—is usable. If it is severely corrupted, review the reference choice before running FEAT; the FSL FEAT practical explains the alternative reference option.
2. Save a complete FEAT configuration
Start the FEAT GUI on a Linux desktop:
Feat & Select First-level analysis and Preprocessing. In this mode, registration can still run, so its settings must also be reviewed.
In the Data tab, select one 4D input and use the full input and output paths printed above. Paste the actual paths into the GUI, not the shell variable names $BOLD and $OUT.
Check Total volumes and TR. Set Delete volumes to the number of initial volumes that still need removal. Use 0 if the intended initial volumes were already discarded. There is no universal number to delete. If you later fit a task model, its event times must refer to the retained time series.
Settings for this example
Use the following settings for the configuration exercise. For research data, choose acquisition-specific corrections and downstream processing as part of the study's analysis plan before running the pipeline.
| Area | Setting |
|---|---|
| Pre-stats: motion correction | MCFLIRT |
| Alternative reference image | Off; use the default middle-volume reference |
| BET brain extraction | On |
| Spatial smoothing FWHM | 0 mm |
| Intensity normalization | Off |
| Temporal filtering | Highpass off; Lowpass off if exposed |
| Perfusion subtraction | Off |
| MELODIC ICA | Off |
| B0 unwarping | Off for this limited example; see below |
| Slice timing correction | None for this example; see below |
| Registration | Disable initial high-resolution, main structural, and standard-space registration |
FEAT's BET option creates a functional brain mask. It does not replace extracting the T1w brain for the registration article. MCFLIRT estimates rigid-body motion between volumes; see its official documentation.
With Intensity normalization off, FEAT still applies one common intensity-scaling factor to the entire 4D run. This differs from normalizing each volume separately, as explained in the FSL FEAT practical. Consequently, output intensities should not be expected to equal input intensities.
Three choices need particular care:
- Distortion correction: Plan any required susceptibility-distortion correction before running the study pipeline. This example leaves EPI distortion uncorrected. Enabling FEAT's fieldmap-based B0 unwarping also changes the required inputs and registration settings, so revise the configuration accordingly. See FUGUE and the registration practical.
- Slice timing: Do not infer acquisition order from the number of slices. Decide whether to apply correction using the sequence metadata and planned analysis. The setting above records its omission; it does not establish that correction is unnecessary.
- Smoothing and temporal filtering: Select these together with the denoising and statistical analysis plan. Both are disabled in this example.
In Misc, optionally disable the progress watcher if you prefer to open the report yourself. Use Save to write the complete configuration to the printed design.fsf path, then close the GUI without pressing Go. The next step runs the saved configuration from the terminal.
The FEAT user guide documents these controls and the saved setup format. If reusing a setup from an older FSL version, load it into the current GUI, review it, and save it again, as advised in the FEAT FAQ.
3. Run the saved setup from the terminal
Confirm that the output path in design.fsf matches $OUT. The file, rather than the shell variable, determines where FEAT writes its results.
less "$WORK/design.fsf" Then launch the job:
if [ ! -s "$WORK/design.fsf" ]; then printf 'ERROR: Save the FEAT setup first.\n' >&2 elif [ -e "$OUT" ]; then printf 'ERROR: %s already exists; use a fresh working directory and save a new FEAT setup.\n' "$OUT" >&2 else feat "$WORK/design.fsf" > "$WORK/feat_launch.log" 2>&1 fi For each new trial, repeat the working-directory setup in Section 1 and save the FEAT configuration with the corresponding paths. A separate working directory keeps each trial's configuration, launch log, metadata, and QC images together. FEAT can append + to an existing output directory name; the guard above helps avoid checking an older run by mistake.
Read feat_launch.log if the launch fails. During processing, use the FEAT report and its linked logs to follow progress. On a system using a job scheduler, a returned shell prompt may only indicate submission; wait for the processing jobs to finish before inspecting final outputs.
On a desktop, open the report once it exists:
xdg-open "$OUT/report.html" For a remote server without a desktop, view the report and images on a graphical machine. Keep the report's associated files together.
4. Check files and dimensions
After processing finishes, inspect these outputs. The image names below assume the NIFTI_GZ output setting used above.
| Output | What to inspect |
|---|---|
filtered_func_data.nii.gz | Processed 4D BOLD run |
mask.nii.gz | Functional brain mask |
example_func.nii.gz | Reference image used by FEAT |
mc/prefiltered_func_data_mcf.par | Motion estimates, one row per retained volume |
design.fsf | Configuration recorded inside the output directory |
report.html | Processing report and links to logs |
The name filtered_func_data does not prove that a particular filter was enabled. Interpret it alongside design.fsf and the processing report. See the FEAT output reference.
fslinfo "$OUT/filtered_func_data.nii.gz" printf 'Input volumes: ' fslval "$BOLD" dim4 printf 'Output volumes: ' fslval "$OUT/filtered_func_data.nii.gz" dim4 printf 'Motion-parameter rows: ' awk 'END { print NR }' "$OUT/mc/prefiltered_func_data_mcf.par" If the input contains N volumes and you requested deletion of D, expect N - D output volumes and the same number of motion-parameter rows. A mismatch needs investigation before any downstream work.
Check that the report reflects the intended settings and that its logs contain no unresolved failures. File presence and a plausible volume count are necessary checks, but they do not establish acceptable image quality.
5. Inspect the images and motion estimates
Create a temporal mean for inspection. Check the brain mask against FEAT's reference image, which retains tissue outside the mask:
mkdir -p "$WORK/qc" fslmaths "$OUT/filtered_func_data.nii.gz" -Tmean "$WORK/qc/mean_bold.nii.gz" fsleyes "$OUT/example_func.nii.gz" "$OUT/mask.nii.gz" In FSLeyes, display the mask as a colored overlay and adjust its opacity. Inspect axial, coronal, and sagittal views. Look for missing cortex or cerebellum and substantial inclusion of non-brain tissue.
Open qc/mean_bold.nii.gz to assess signal within the retained mask. Check apparent signal loss against the original BOLD data, the reference image, and the mask; zeros introduced by masking do not by themselves demonstrate acquisition-related dropout.
Then inspect the time series itself:
fsleyes "$OUT/filtered_func_data.nii.gz" Move through time or use movie playback. Look for abrupt shifts, disappearing coverage, slice artifacts, or isolated corrupted volumes. A temporal mean can hide problems confined to a few frames.
Review the motion plots in the FEAT report. In the MCFLIRT parameter file, the first three columns are rotations in radians and the final three are translations in millimeters in FSL's coordinate convention. These six parameters are not framewise displacement.
Motion correction cannot remove every motion-related signal artifact. Large movements and signal outliers may require additional handling or exclusion under a study's predefined QC criteria. FSL's motion outliers documentation explains why realignment alone is insufficient. No universal pass/fail threshold is assumed here.
Record the QC decision and its reason for each run, including any rerun with revised settings.
6. Connect the output to the next stage
The output remains in functional space. It does not automatically meet the input requirements of the FSL and ANTs registration tutorial. Verify those requirements, including whether any required distortion correction has been performed, before using filtered_func_data.nii.gz as that article's bold_preproc.nii.gz. Create the registration reference from the same BOLD time series to which you will apply the transforms.
For ICA denoising, retain the full FEAT directory and its processing history. This example has ICA and registration disabled, so it does not create a complete FIX input. The FIX documentation requires additional ICA and registration outputs, including structural-image information. Adding an ICA decomposition alone does not satisfy that requirement.
Before processing more participants, resolve the remaining acquisition-specific choices and inspect a representative run. Keep the input identity, FSL version, saved configuration, report, and QC notes together so that the processing can be reviewed and repeated.
AI disclosure: An LLM was used to help draft, organize, and edit the English text and command examples. I remain responsible for the article's technical accuracy.

