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
larmorxApache-2.0 AND CC-BY-4.0 validated - clean room
larmorxApache-2.0 validated
- replica
- 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
larmorx afni 3dTshift [options] datasetEverything 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):
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
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
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,
) -> ImageWhere 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).
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 Nn_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-roomimplementation="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|reproduceupstream_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.
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)larmorx afni 3dTshift -ignore 0 -tzero 0.975 -TR 2.0s -tpattern @slice_timing.1D -prefix bold_stc.nii.gz bold.nii.gzPorts
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 programlarmorx-gpl), with AFNI’s float32 FFT and glibc 2.35’ssinf/cosftranslated from Arm’s Optimized Routines (MIT), proved equal to glibc’s on every input. WithLARMORX_UPSTREAM_DEFECTS=reproduceit 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 specspecs/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: