Documentation
Getting started
LARMORX installs with pip on Linux, macOS and Windows, with nothing else to install. This page shows how to install it and run its first programs on public data, and lists its three packages, what a computer needs, the standalone programs and the container images.
The first release, 0.1.0rc1, is a release candidate: a pre-release, published to check that the packages install and work on every platform before 0.1.0. The programs on the Programs page are complete and compared case by case with their originals (how); the preprocessing pipeline larmorprepx is not ready yet (only its field-map stages exist), and FreeSurfer’s programs are still to come (roadmap). What the release holds, program by program: the changelog.
Nothing else is needed: no ANTs, AFNI, FSL or tedana installation, no compiler and no administrator rights.
With pip
pip install larmorxinstalls the library and the commands larmorx and lx. Two extras add more:
pip install "larmorx[prep]"adds whatlarmorprepxwill need (not ready yet);pip install "larmorx[all]"adds[prep],larmorx-ncandlarmorx-gpl.
pip installs a pre-release by itself only while no final release exists; pip install "larmorx==0.1.0rc1" (or pip install --pre larmorx) asks for it by name. [all] installs the three packages at the same version. The quotation marks keep the square brackets from being read by the shell.
A virtual environment keeps LARMORX and the packages it needs apart from the rest of your Python. On Linux and macOS:
python3 -m venv larmorx-env
source larmorx-env/bin/activate
pip install larmorx
larmorx --versionThe last line prints 0.1.0rc1.
On Windows, in the Command Prompt:
python -m venv larmorx-env
larmorx-env\Scripts\activate
pip install larmorx
larmorx --versionIn Python, import larmorx as lx gives the same programs (lx.__version__ is the version). With [all], larmorx-nc --version and larmorx-gpl --version print the same version. Examples of both ways of calling a program are on the home page; each program’s command, Python function and options are in the repository’s API pages.
First steps
Where pip puts the commands. pip installs larmorx, lx and larmorprepx into the Python environment’s folder of programs: bin on Linux and macOS, Scripts on Windows. For the virtual environment above that is larmorx-env/bin or larmorx-env\Scripts, and activating the environment puts it on the PATH, so the commands work by their names. Without a virtual environment, pip names the folder in a warning when it is not on the PATH; this prints it (in PowerShell, with python for python3):
python3 -c "import sysconfig; print(sysconfig.get_path('scripts'))"After pip install --user, the folder is sysconfig.get_path('scripts', sysconfig.get_preferred_scheme('user')) instead. python3 -m larmorx (python -m larmorx on Windows), followed by the same arguments, runs the same command without the folder on the PATH.
Three settings for every program. In 0.1.0rc1 the command line takes them from environment variables, and Python takes the same values as arguments of its functions (implementation where a program has two ports; Concepts says what each does):
- Threads:
OMP_NUM_THREADS(ANTs’ programs:ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS, orNSLOTS); in Pythonn_threads. The number of threads; without the variable the command line uses every logical CPU (Python’s default is 1). - Port:
LARMORX_IMPLEMENTATION; in Pythonimplementation.auto(the default) runs a program’s replica when it is built in or installed, otherwise its clean room;replicathe replica;originalthe clean room (clean-roomfrom the next release). - Upstream defects:
LARMORX_UPSTREAM_DEFECTS; in Pythonupstream_defects.fix(the default) corrects the original program’s known defects, each with a notice (below);reproducegives the original program’s result.
In bash and zsh, NAME=value before a command sets a variable for that command only, and export NAME=value for the rest of the session; in PowerShell, $env:NAME = "value" sets it for the session and Remove-Item Env:NAME removes it.
Coming with the next release (already in the repository’s main, First steps in its README): the same three settings as options between larmorx and the family, with the Python arguments’ names, larmorx --n-threads 4 --implementation clean-room --upstream-defects reproduce <family> <program> ..., each winning over its variable; and clean-room as the name of the clean room, where 0.1.0rc1 says original (which keeps working). The replica programs larmorx-nc and larmorx-gpl take --n-threads and --upstream-defects the same way.
An example, start to end, on one participant of the public OpenNeuro dataset ds000005 (public domain, PDDL; 21 MB): a new virtual environment, the two images downloaded, then ANTs’ bias-field correction on four threads, FSL’s brain extraction, head-motion correction and registration, and AFNI’s brain mask computed by the replica (the default) and by the clean room. FSL’s programs need FSLOUTPUTTYPE, as FSL’s own do (NIFTI_GZ: they write .nii.gz files). The last command gives the original N4’s result instead of the corrected one. On Linux and macOS (bash or zsh), with Python 3.12 or newer as python3 (macOS’s own python3 is older: install one from python.org or Homebrew):
python3 -m venv larmorx-env
source larmorx-env/bin/activate
pip install larmorx
mkdir larmorx-demo
cd larmorx-demo
curl -L -o t1w.nii.gz https://s3.amazonaws.com/openneuro.org/ds000005/sub-01/anat/sub-01_T1w.nii.gz
curl -L -o bold.nii.gz https://s3.amazonaws.com/openneuro.org/ds000005/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.nii.gz
export FSLOUTPUTTYPE=NIFTI_GZ
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS=4 larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o t1w_n4.nii.gz
larmorx fsl bet t1w_n4.nii.gz t1w_brain -R -m
larmorx fsl mcflirt -in bold.nii.gz -out bold_mcf -plots
larmorx fsl fslmaths bold_mcf -Tmean bold_mean
larmorx afni 3dAutomask -prefix bold_mask.nii.gz bold_mean.nii.gz
LARMORX_IMPLEMENTATION=original larmorx afni 3dAutomask -prefix bold_mask_clean_room.nii.gz bold_mean.nii.gz
larmorx fsl fslmaths bold_mean -mas bold_mask bold_brain
larmorx fsl flirt -in bold_brain -ref t1w_brain -dof 6 -omat bold2t1w.mat -out bold2t1w
LARMORX_UPSTREAM_DEFECTS=reproduce larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o t1w_n4_ants.nii.gzOn Windows, in PowerShell, with Python 3.12 or newer as python (python.org’s installer puts it on the PATH when “Add python.exe to PATH” is ticked; otherwise write py for python in the first line):
python -m venv larmorx-env
larmorx-env\Scripts\Activate.ps1
pip install larmorx
mkdir larmorx-demo
cd larmorx-demo
curl.exe -L -o t1w.nii.gz https://s3.amazonaws.com/openneuro.org/ds000005/sub-01/anat/sub-01_T1w.nii.gz
curl.exe -L -o bold.nii.gz https://s3.amazonaws.com/openneuro.org/ds000005/sub-01/func/sub-01_task-mixedgamblestask_run-01_bold.nii.gz
$env:FSLOUTPUTTYPE = "NIFTI_GZ"
$env:ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS = "4"
larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o t1w_n4.nii.gz
larmorx fsl bet t1w_n4.nii.gz t1w_brain -R -m
larmorx fsl mcflirt -in bold.nii.gz -out bold_mcf -plots
larmorx fsl fslmaths bold_mcf -Tmean bold_mean
larmorx afni 3dAutomask -prefix bold_mask.nii.gz bold_mean.nii.gz
$env:LARMORX_IMPLEMENTATION = "original"
larmorx afni 3dAutomask -prefix bold_mask_clean_room.nii.gz bold_mean.nii.gz
Remove-Item Env:LARMORX_IMPLEMENTATION
larmorx fsl fslmaths bold_mean -mas bold_mask bold_brain
larmorx fsl flirt -in bold_brain -ref t1w_brain -dof 6 -omat bold2t1w.mat -out bold2t1w
$env:LARMORX_UPSTREAM_DEFECTS = "reproduce"
larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o t1w_n4_ants.nii.gz
Remove-Item Env:LARMORX_UPSTREAM_DEFECTSIf PowerShell refuses Activate.ps1 because running scripts is disabled on the computer, Set-ExecutionPolicy -Scope Process RemoteSigned allows it in that window only. Each command writes its results into larmorx-demo; deactivate leaves the virtual environment.
What the upstream defect ... corrected lines mean. Some commands print a notice such as
larmorx: upstream defect ANTS-40 (N4BiasFieldCorrection) corrected: 6208 of the 92160 voxels N4 uses have no logarithm (6208 are 0, 0 negative or NaN): they are left out of the histogram and the fit; ITK keeps them in its log image as they are (0 is the log of 1) [LARMORX_UPSTREAM_DEFECTS=reproduce gives N4BiasFieldCorrection's result]It is not an error (the command still ends with exit status 0). It says that a known defect of the original program (here ANTs’ N4) would have changed this result, and that LARMORX computed the corrected result, as it does by default. The code (ANTS-40) is the defect’s entry in the repository’s register; the upstream defects page explains the rules. To get the original program’s result, bit for bit, set LARMORX_UPSTREAM_DEFECTS=reproduce, as the notice says (upstream_defects="reproduce" in Python); the notice then says reproduced. The replica programs’ notices start with larmorx-nc: or larmorx-gpl:, and AFNI’s programs print theirs as AFNI’s warnings (*+ WARNING: upstream defect AFNI-99 (3dvolreg) corrected: ...).
The three packages and their licences
LARMORX is published as three packages, one for each family of licences, so that each licence stays with the code it covers (in full on Concepts):
larmorx: every program on the Programs page but FSL’s and tedana’s replicas; Apache-2.0, any use, commercial use included. Its NOTICE lists the works it includes.larmorx-nc: the replicas of FSL’s programs; the FSL Licence, non-commercial use only.larmorx-gpl: the replica of tedana’st2smap; the GNU GPL version 3.
The two replica packages are installed only when you ask for them by name (pip install larmorx-nc) or through [all]. Every work LARMORX includes and its licence: the repository’s licensing notes.
What your computer needs
The packages on PyPI are built in advance for six platforms (as wheels), so pip only downloads and unpacks them:
- Python 3.12 or newer (CPython; one wheel serves every version from 3.12 on; tested on 3.12 on every platform, and on 3.13 and 3.14 on Linux). The free-threaded builds of Python are not supported.
- Linux, x86-64 and aarch64, with glibc 2.28 or newer (
manylinux_2_28: for example RHEL 8, Debian 10, Ubuntu 20.04 and later). There are no wheels for musl-based systems such as Alpine Linux: use a container image there. - macOS 11 or newer, Intel and Apple silicon. On Apple silicon,
[prep]and[all]need macOS 12, as SciPy’s and scikit-learn’s wheels do. - Windows 10 and 11, x64 and arm64. Visual C++'s runtime is built in: nothing to install.
Where no wheel fits, or with pip install --no-binary larmorx larmorx, pip builds LARMORX from its source distribution. That needs a C compiler (gcc or clang; Microsoft’s C++ build tools on Windows) and Rust 1.99 or newer, which maturin downloads by itself when none is installed.
Standalone programs
Each release on GitHub also has the command-line programs as archives that need no Python: larmorx (with its short name lx), larmorx-nc and larmorx-gpl, for each platform, each with its licences (larmorx-nc’s with FSL’s original and amended source, as its licence requires). The two programs written in Python, larmorx sdcflows and larmorprepx, need the Python package.
| Your computer | The archive |
|---|---|
| Linux, x86-64 | larmorx-0.1.0rc1-x86_64-unknown-linux-gnu.tar.gz |
| Linux, aarch64 | larmorx-0.1.0rc1-aarch64-unknown-linux-gnu.tar.gz |
| macOS, Apple silicon | larmorx-0.1.0rc1-aarch64-apple-darwin.tar.gz |
| macOS, Intel | larmorx-0.1.0rc1-x86_64-apple-darwin.tar.gz |
| Windows, x64 | larmorx-0.1.0rc1-x86_64-pc-windows-msvc.zip |
| Windows, arm64 | larmorx-0.1.0rc1-aarch64-pc-windows-msvc.zip |
The archives of larmorx-nc and larmorx-gpl are named the same way (larmorx-nc-0.1.0rc1-…, larmorx-gpl-0.1.0rc1-…). Each unpacks into a folder of its own name, with the program in bin/, its licences beside it and a README.txt. On Linux and macOS, with t set to your computer’s ending from the table (here Linux on x86-64):
v=0.1.0rc1
t=x86_64-unknown-linux-gnu
curl -LO https://github.com/karellopez/larmorx/releases/download/v$v/larmorx-$v-$t.tar.gz
tar -xzf larmorx-$v-$t.tar.gz
larmorx-$v-$t/bin/larmorx --versionOn Windows, in PowerShell, after downloading the archive:
Expand-Archive larmorx-0.1.0rc1-x86_64-pc-windows-msvc.zip -DestinationPath .
.\larmorx-0.1.0rc1-x86_64-pc-windows-msvc\bin\larmorx.exe --versionTo call the program by its name from anywhere, add its bin folder to your PATH. The programs are not signed by Apple or Microsoft, so macOS or Windows may refuse to start one that a web browser downloaded; after checking the file, removing the download mark lets it run (on macOS xattr -d com.apple.quarantine <archive> before unpacking; on Windows Unblock-File <archive> in PowerShell). A file downloaded with curl carries no such mark.
Container images
For Linux machines and computing clusters, each release also has two container images, for linux/amd64 and linux/arm64, usable by Apptainer, Docker and Podman:
ghcr.io/karellopez/larmorx:0.1.0rc1:larmorxwith[prep], without the replica packages; commercial use allowed.ghcr.io/karellopez/larmorx:0.1.0rc1-all: alsolarmorx-gplandlarmorx-nc; non-commercial use only (the FSL Licence).
latest and latest-all name the newest final release (never a release candidate such as 0.1.0rc1). With Apptainer:
apptainer pull docker://ghcr.io/karellopez/larmorx:0.1.0rc1
apptainer exec larmorx_0.1.0rc1.sif larmorx --versionWith Docker (Podman takes the same arguments), the current folder mounted as /data:
docker run --rm -v "$PWD:/data" -w /data ghcr.io/karellopez/larmorx:0.1.0rc1 \
larmorx ants N4BiasFieldCorrection -d 3 -i t1w.nii.gz -o t1w_n4.nii.gzUnder Apptainer the image runs as you, with your home directory, where TemplateFlow keeps the templates it downloads on first use ($HOME/.cache/templateflow). Docker runs it as root, so mount a volume at /root/.cache/templateflow (or set TEMPLATEFLOW_HOME to a mounted folder) to keep them. /opt/larmorx/README.txt in the image says what it holds and where its licences and sources are.
Check a download
pip checks every file it downloads from PyPI against PyPI’s own SHA-256 by itself. For the files of a GitHub release, the release’s SHA256SUMS holds the SHA-256 of every file. Download it into the folder that holds your files; then, on Linux:
sha256sum -c --ignore-missing SHA256SUMSon macOS:
shasum -a 256 -c --ignore-missing SHA256SUMSEach file you have is listed with OK; a different word means that the file is damaged or is not the release’s file. On Windows, in PowerShell, for one file (True when it is the release’s file):
$f = "larmorx-0.1.0rc1-x86_64-pc-windows-msvc.zip"
$sum = (Select-String -Path SHA256SUMS -SimpleMatch " $f").Line.Split(" ")[0]
(Get-FileHash $f).Hash -eq $sumEvery file and both images also carry GitHub’s record of the build that made them (an attestation), which GitHub’s command-line program gh checks, for a file and for an image:
gh attestation verify <file> --repo karellopez/larmorx
gh attestation verify oci://ghcr.io/karellopez/larmorx:0.1.0rc1 --repo karellopez/larmorxPyPI shows its own attestations on each file’s page.
Updating and removing
pip install --upgrade larmorx (or pip install --upgrade "larmorx[all]", which keeps the three packages at one version) takes the newest release. pip uninstall larmorx larmorx-nc larmorx-gpl, or deleting the virtual environment’s folder, removes the packages; the standalone programs go with their folder, an image with its .sif file or docker image rm. Files a program downloaded on first use, such as TemplateFlow’s templates, stay in their cache folder.