Programs · AFNI

3dTshift

3dTshift corrects slice timing: it aligns every slice of a 4D series to one time origin.

Original
AFNI 26.3.05
Command line
larmorx afni 3dTshift
Python
lx.afni.tshift
Ports
  • replica larmorx Apache-2.0 AND CC-BY-4.0 validated
  • clean room larmorx Apache-2.0 validated
Evidence
every comparison with AFNI
Source
made from docs/api/afni-tshift.md and the code

What it does

Each voxel’s time series is detrended (a least-squares line), shifted in time so that its slice refers to tzero, clipped to its own range, and given its trend back. The output at time point n estimates the signal at n·TR + tzero.

Command line

text
larmorx afni 3dTshift [options] dataset

Everything after larmorx afni 3dTshift is the original’s command line: the arguments of AFNI 26.3.05’s 3dTshift, as AFNI takes them. LARMORX’s own options stand between larmorx and the family afni, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        afni 3dTshift ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

3dTshift's usage text, as the clean room prints it
text
Usage: 3dTshift [options] dataset   (larmorx, clean-room re-implementation of AFNI 3dTshift)

Shifts voxel time series so that all slices are aligned to the same temporal origin:
detrend -> interpolate -> retrend. The dataset is a 4D NIfTI file.

Options (they must come before the dataset):
  -verbose        print progress messages
  -TR ddd         use ddd as the TR (suffix s or ms; ms switches every time to milliseconds)
  -tzero zzz      align each slice to time offset zzz (default: the mean slice offset)
  -slice nnn      align each slice to the offset of slice nnn (wins over -tzero)
  -prefix ppp     output file name: must end in .nii or .nii.gz; an existing file is an error
                  unless -overwrite or AFNI_DECONFLICT says otherwise
  -ignore ii      leave the first ii time points out of the detrending and shifting
  -rlt            do not add the trend back after shifting
  -rlt+           add back only the intercept of the trend
  -no_detrend     remove (and restore) only the mean; needs a non-Fourier method before it
  -Fourier -linear -cubic -quintic -heptic -wsinc5 -wsinc9
                  interpolation method (default -Fourier)
  -tpattern ttt   slice timing: alt+z altplus alt+z2 alt-z altminus alt-z2 seq+z seqplus
                  seq-z seqminus zero simult, or @file / '@1D: ...' with one offset per slice
                  (default: the slice timing in the NIfTI header)

AFNI's global options may stand anywhere: -overwrite, -Dname=value (sets one of AFNI's
environment variables for this run), -ok_1D_text, -skip_afnirc.

Python

python
lx.afni.tshift(
    image: Any,
    *,
    slice_times: Sequence[float] | str,
    tr: float | None = None,
    tzero: float | None = None,
    slice: int | None = None,
    ignore: int = 0,
    method: Method = "fourier",
    restore: RestoreName = "trend",
    detrend: bool = True,
    n_threads: int = 1,
    implementation: ImplementationName = "auto",
    upstream_defects: UpstreamDefectsName = "fix",
    afni_settings: Mapping[str, str] | None = None,
) -> Image

Where Method is one of "fourier", "linear", "cubic", "quintic", "heptic", "wsinc5", "wsinc9"; RestoreName is one of "trend", "none", "intercept"; ImplementationName is one of "auto", "replica", "clean-room", "original" (0.1.0rc1’s spelling of "clean-room"); UpstreamDefectsName is one of "fix", "reproduce".

Align every slice of a 4D image to one time origin (AFNI’s 3dTshift).

Returns an lx.Image with the header 3dTshift writes: pixdim[4] = TR (seconds), toffset = tzero, no slice timing, millimetres and seconds. Data keep AFNI’s storage type (uint8, int16 or float32); when the output has a brick factor (scl_slope), the data are the scaled values, as lx.load returns them. img.implementation says which port computed it.

Files and in-memory images. Paths are read with AFNI’s rules (How AFNI reads and writes NIfTI), which is what makes the result match AFNI. In-memory images (lx.Image, nibabel images, (array, affine)) keep uint8, int16 and float32 data and convert other types to float32; tr is required when they have no NIfTI header.

lx.afni.fmriprep_slice_timing(slice_timing, slice_encoding_direction) gives the slice times and tzero fMRIPrep passes: SliceTiming reversed when the direction ends in -, and round(min + 0.5·(max − min), 3).

python
import json
import larmorx as lx

# As fMRIPrep calls 3dTshift: SliceTiming from the BIDS sidecar, tzero mid-acquisition.
meta = json.load(open("sub-01_task-rest_bold.json"))
times, t0 = lx.afni.fmriprep_slice_timing(meta["SliceTiming"], meta.get("SliceEncodingDirection"))
stc = lx.afni.tshift(
    "sub-01_task-rest_bold.nii.gz",
    slice_times=times,
    tzero=t0,
    tr=meta["RepetitionTime"],
    n_threads=8,
)
stc.save("sub-01_task-rest_desc-stc_bold.nii.gz")

# A named pattern and another method
img = lx.afni.tshift("bold.nii.gz", slice_times="alt+z", method="heptic")

Its result, Image, holds a voxel array placed in world space by an affine.

Field Type What it holds
data np.ndarray
affine np.ndarray
header NiftiHeader | None
implementation Implementation | None

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options 3dTshift accepts (crates/larmorx-afni/src/cli/tshift.rs) and the arguments of lx.afni.tshift (python/larmorx/afni/tshift.py), whose defaults and descriptions are taken from it. Under each option, in grey, its line of the usage text the clean room prints, in the clean room’s own words.

AFNI option Python Default Notes
the last word (dataset) image the input: a 4D NIfTI path, or in Python an lx.Image, a nibabel image or (array, affine)
-prefix ppp the result the returned image (its .save(path) writes it); the command line needs .nii or .nii.gz and refuses an existing fileThe clean room’s usage: “output file name: must end in .nii or .nii.gz; an existing file is an error unless -overwrite or AFNI_DECONFLICT says otherwise”
-tpattern alt+z (and altplus, alt+z2, alt-z, altminus, alt-z2, seq+z, seqplus, seq-z, seqminus, zero, simult) slice_times="alt+z" case-sensitive, except zero and simultThe clean room’s usage: “slice timing: alt+z altplus alt+z2 alt-z altminus alt-z2 seq+z seqplus seq-z seqminus zero simult, or @file / ‘@1D: …’ with one offset per slice (default: the slice timing in the NIfTI header)”
-tpattern @file, -tpattern '@1D: ...' slice_times=[...] (seconds) values must lie in [0, TR]; the file is AFNI 1D text (Behaviour found by black-box runs)The clean room’s usage: “slice timing: alt+z altplus alt+z2 alt-z altminus alt-z2 seq+z seqplus seq-z seqminus zero simult, or @file / ‘@1D: …’ with one offset per slice (default: the slice timing in the NIfTI header)”
(no -tpattern) – the command line uses the header’s slice timing, or copies the input when there is none
-TR 2s, -TR 2000ms tr=2.0 None default: the header’s TR (ms and µs converted), 1 s if not positiveThe clean room’s usage: “use ddd as the TR (suffix s or ms; ms switches every time to milliseconds)”
-tzero z tzero=z None default: the mean slice time; must be ≥ 0The clean room’s usage: “align each slice to time offset zzz (default: the mean slice offset)”
-slice k slice=k None wins over tzeroThe clean room’s usage: “align each slice to the offset of slice nnn (wins over -tzero)”
-ignore n ignore=n 0 at most nt − 5The clean room’s usage: “leave the first ii time points out of the detrending and shifting”
-Fourier -linear -cubic -quintic -heptic -wsinc5 -wsinc9 method="fourier" (default), "linear", … "fourier" the command line compares 4 characters (-cub), 7 for -wsinc5/9 (any case)The clean room’s usage: “interpolation method (default -Fourier)”
-rlt / -rlt+ restore="none" / "intercept" "trend" -rlt+ adds back the fitted intercept, not the meanThe clean room’s usage: “do not add the trend back after shifting”The clean room’s usage: “add back only the intercept of the trend”
-no_detrend detrend=False True every voxel’s mean removed and restored, in both modes, as AFNI 26.3.05 does (AFNI 25.2.09’s voxel pairs: AFNI-05, in Upstream defects)The clean room’s usage: “remove (and restore) only the mean; needs a non-Fourier method before it”
-verbose – progress on standard error; its first line names the port that runsThe clean room’s usage: “print progress messages”
-voxshift dset – not supported
-Dname=value; AFNI’s environment variables afni_settings={"AFNI_NIFTI_PRIORITY": "Q"} None the command line reads the process environment, as AFNI does, and -D sets a variable for the run; Python never reads the environment (AFNI’s settings in Python)
-overwrite, -ok_1D_text, -skip_afnirc – AFNI’s global options, anywhere on the command line; the Python API writes no output file and its own slice-time file
OMP_NUM_THREADS n_threads=1 (0 = all CPUs) 1 AFNI is single-threaded; the result does not depend on the thread count
LARMORX_UPSTREAM_DEFECTS upstream_defects="fix" "fix" AFNI’s defects corrected (default) or reproduced (reproduce; Upstream defects, upstream-defects.md)
LARMORX_IMPLEMENTATION implementation="auto" "auto" auto, replica or clean-room (--implementation before the family)

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and afni on the command line (larmorx --n-threads 4 afni 3dTshift ...) and are arguments of lx.afni.tshift. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Worker threads (0 = all). The result does not depend on it. Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
implementation="auto"
"auto" (default) and "replica": the bit-exact replica (part of larmorx, run in this process on temporary NIfTI files, with the arguments AFNI’s program takes); "clean-room" ("original", 0.1.0rc1’s spelling, still works): the clean room. The two differ only in the last bits of some values (docs/validation/afni-tshift.md). The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
"fix" (default) corrects AFNI’s defects (AFNI-01, -02, -07, -16, and with afni_settings AFNI-23); "reproduce" gives AFNI’s output. A UpstreamDefectWarning names each defect that changed the result (or, reproduced, would have been corrected). The replica receives the choice as LARMORX_UPSTREAM_DEFECTS. The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: bold.nii.gz (a synthetic series of 8 heads of 40 × 48 × 40 voxels of 4 mm), slice_timing.1D (the times of 40 slices acquired interleaved within 2 s, on one line, as fMRIPrep writes them). The command lines run as python -m larmorx.

python
import larmorx as lx

# As fMRIPrep calls 3dTshift: the run's SliceTiming, tzero in the middle of the acquisition.
slice_timing = [float(t) for t in open("slice_timing.1D").read().split()]
times, t0 = lx.afni.fmriprep_slice_timing(slice_timing)
t0  # -> 0.975
stc = lx.afni.tshift("bold.nii.gz", slice_times=times, tzero=t0, tr=2.0)
stc.data.shape  # -> (40, 48, 40, 8)
bash
larmorx afni 3dTshift -ignore 0 -tzero 0.975 -TR 2.0s -tpattern @slice_timing.1D -prefix bold_stc.nii.gz bold.nii.gz

Ports

3dTshift has two ports: a replica and a clean room.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 AND CC-BY-4.0 validated afni-tshift-replica
clean room larmorx Apache-2.0 validated afni-tshift

Both are validated against AFNI 26.3.05 itself (the clean room against AFNI 25.2.09 until 2026-10-29), on the same 317 cases of the standard tier: every file of larmorx-testdata’s synthetic/tshift/ (every FFT length class, every data type AFNI reads, edge content); every method, option and -tpattern form, slice timing from NIfTI headers, the copies of the input, AFNI’s defects (D13) and 21 error cases; 20 runs on real BOLD data (ds000210 multi-echo, ds001600, ds003345, ds005454 multiband with 96 slices, ds006010, ds006736), called as fMRIPrep calls 3dTshift; and 60 cases of AFNI’s global options and environment variables. In both records 282 cases pass, 32 are rejected by both alike and 3 are expected divergences (AFNI’s own output format and -voxshift, which larmorx does not support, and a dataset of one row, which AFNI writes as a text file with a random identifier, AFNI-20).

  • The replica (its record, 2026-11-13): all 282 compared cases are AFNI’s output data bit for bit (the Fourier method’s 147 and the other methods’ and copies’ 135); in the 63 cases of AFNI’s global options, variables and failed writes, the exit status and both output streams are AFNI’s byte for byte too (AFNI’s version banner and larmorx’s own lines set aside).
  • The clean room (its record, 2026-11-04): 180 of the 282 compared cases are AFNI’s output data bit for bit. The Lagrange and weighted-sinc methods and the copies give the same bytes as AFNI in 133 of 135; the Fourier method (the default) in 47 of 147, because AFNI’s FFT is float32 and the clean room’s is double. The outputs that differ do so in the last float32 bits, by at most 3.7e-7 of AFNI’s largest value (5.6e-8 on the real runs); integer outputs by at most 1. In every compared case the header fields are AFNI’s and the geometry agrees to 1e-6 mm; in the 63 cases of AFNI’s global options, variables and failed writes, the exit status and both output streams are AFNI’s byte for byte (AFNI’s version banner and larmorx’s own lines set aside). The known last-bit differences are listed in Known last-bit differences.

In both records the Python call gives the command line’s output bit for bit (data and header) on the 194 passing cases it can express, 149 of 149 from an image in memory, and on the 28 cases of AFNI’s variables and global options it can express, with afni_settings.

3dTshift has two ports, both in pip install larmorx:

  • The replica is bit-exact, translated from AFNI’s own source (crates/larmorx-afni-replica; Apache-2.0, with CC BY 4.0’s attribution for the code of the Medical College of Wisconsin, which AFNI 26.3.05 releases under CC BY 4.0 (NOTICE, licensing); until 2026-10-29 the separate GPL program larmorx-gpl), with AFNI’s float32 FFT and glibc 2.35’s sinf/cosf translated from Arm’s Optimized Routines (MIT), proved equal to glibc’s on every input. With LARMORX_UPSTREAM_DEFECTS=reproduce it gives AFNI’s output bytes on every compared parity case.
  • The clean room (crates/larmorx-afni, Apache-2.0) is built for speed. AFNI’s 3dTshift was GPL-2 code until AFNI 26.3.05, so larmorx wrote it without AFNI’s source code: from the behaviour spec specs/3dTshift.md, AFNI’s help text and black-box runs of the AFNI binary (PROVENANCE).

Both take the same arguments, follow the same conventions (NIfTI output only, an existing output is an error) and correct the same AFNI defects by default (Upstream defects). implementation="auto" (the default, and larmorx afni 3dTshift) runs the replica, in the same process; implementation="replica" or "clean-room" ("original", 0.1.0rc1’s spelling, still works) (--implementation before the family, or LARMORX_IMPLEMENTATION) forces one. Each image’s implementation names the one that ran.

Evidence

How each of 3dTshift’s ports was measured against AFNI, case by case: its evidence.

More in the repository

The API page docs/api/afni-tshift.md holds what 3dTshift shares with the page’s other programs: