ME-ICA 4 AFNI Runtime Builder

Build scripts for creating the distributed AFNI runtime used by ME-ICA 4 (https://github.com/ME-ICA/me-ica).

This repository builds a self-contained Linux x86_64 runtime environment containing the AFNI command-line tools, selected template assets, autoboxed alignment targets, and curated utilities needed by the ME-ICA 4 processing workflow. The resulting runtime is intended to be packaged as a tarball and distributed with ME-ICA, allowing ME-ICA analyses to run against a known AFNI toolchain without requiring users to install or manage AFNI themselves.

Purpose

ME-ICA 4 uses AFNI extensively for preprocessing, spatial alignment, masking, despiking, detrending, and related image operations. In ordinary neuroimaging workflows, users often rely on a system AFNI installation, a conda AFNI package, or a cluster-provided module. Those approaches are powerful but can introduce version drift, dependency conflicts, missing system libraries, and inconsistent behavior across Linux workstations, WSL2 systems, and institutional clusters.

This builder creates a narrow, distributed runtime for ME-ICA 4. The runtime is designed to be invoked internally by meica.py and by generated _meica_*.sh execution scripts. It is not intended to replace the user’s normal AFNI installation or interfere with AFNI GUI use.

The central design goal is:

ME-ICA runs with its own known AFNI runtime.
The user’s shell and system AFNI remain unaffected.

Why distribute an AFNI runtime?

A reasonable question is why ME-ICA should distribute an AFNI runtime at all, rather than simply expecting users to install AFNI locally.

AFNI is a mature and widely used neuroimaging toolkit, and many experienced users already maintain working AFNI installations. However, even a minimal AFNI installation often requires a small set of system-level dependencies, environment configuration steps, shell setup changes, and package-manager operations. These steps are not conceptually large, but they commonly require administrator privileges or institutional IT support, especially on shared workstations, managed laptops, clusters, and Windows systems using WSL2.

There are also multiple valid AFNI installation routes, including system packages, AFNI-provided binary installers, local builds, conda-based approaches, cluster modules, and custom lab environments. This flexibility is powerful, but it can also be confusing even for expert users. Small differences in install route, AFNI version, OpenMP runtime, X11/Mesa/Motif libraries, template availability, or shell environment can produce confusing failures or inconsistent behavior.

ME-ICA 4 depends on AFNI for a focused set of command-line operations. The distributed runtime removes the need for users to solve the broader AFNI installation problem before they can begin working with ME-fMRI. It provides the AFNI tools, runtime libraries, templates, and selected utilities needed by ME-ICA in a controlled, reproducible package.

This lowers the barrier to entry for ME-fMRI and ME-ICA. In combination with the ME-ICA installer, the distributed runtime makes it possible for new users to get started with multi-echo fMRI processing without first becoming experts in AFNI installation, Linux system libraries, OpenMP runtime behavior, X11/Mesa dependencies, or template asset management.

This approach also helps make ME-ICA outputs more accessible to downstream analysis environments such as FSL, SPM, CONN, Python-based workflows, R-based workflows, and other neuroimaging pipelines. By making the AFNI dependency transparent to the user, ME-ICA 4 can function more like a self-contained preprocessing and decomposition step whose outputs are then available for a broad range of connectivity, functional activation, precision mapping, and longitudinal studies. In that sense, the distributed runtime can make ME-fMRI analysis as accessible as conventional single-echo workflows built around FSL, SPM, or CONN, and potentially more accessible for users who want artifact-resolved multi-echo outputs without first managing AFNI-specific system dependencies.

The intent is not to replace AFNI as a general-purpose user tool. Users who already have AFNI installed can continue to use their own AFNI environment normally. The ME-ICA runtime is scoped to ME-ICA execution so that ME-ICA analyses use a known toolchain while the user’s local AFNI installation remains untouched.

Runtime design

The generated runtime has the approximate layout:

meica-afni-runtime/
  activate_meica_afni
  bin/
    3dinfo
    3dDespike
    3dSkullStrip
    3dSeg
    3dAllineate
    3dNwarpApply
    3dAutobox
    ...
    TT_N27+tlrc.HEAD
    TT_N27+tlrc.BRIK.gz
    TT_N27_ab.nii.gz
    MNI_caez_N27+tlrc.HEAD
    MNI_caez_N27+tlrc.BRIK.gz
    MNI_caez_N27_ab.nii.gz
    MNI152_2009_template.nii.gz
    MNI152_2009_template_ab.nii.gz
  lib/
    bundled non-core runtime libraries
    dri/
      swrast_dri.so
  utils/
    dcm2niix
  audit/
    build logs
    dependency audits
    template manifests
    checksums

The bin/ directory is the internal ME-ICA AFNI runtime. It is meant to be exposed only to meica.py and ME-ICA-generated execution scripts.

The utils/ directory contains selected user-facing utilities shipped with the runtime, such as dcm2niix. The ME-ICA installer may place this directory on the user’s PATH, allowing direct access to a small curated set of tools without exposing the full AFNI runtime globally.

Build strategy

The runtime builder emphasizes portability and reproducibility.

It currently targets Linux x86_64 using a manylinux2014-compatible base image. The builder uses Docker to provide a controlled, reproducible build environment. By default, it runs inside a manylinux2014_x86_64 container, builds AFNI and supporting dependencies there, and writes the resulting runtime tarball back to the host filesystem. Docker is used only for building the runtime; the generated ME-ICA AFNI runtime itself does not require Docker to run.

The build strategy:

• builds required static numerical/image dependencies;
• builds selected AFNI command-line tools from source;
• builds required SUMA-linked command-line tools such as 3dSkullStrip and 3dSeg;
• statically links sensitive compiler/runtime dependencies where practical, including OpenMP/libgomp;
• bundles non-core runtime libraries required by AFNI/SUMA tools;
• leaves the host system responsible for the core Linux/glibc ABI;
• uses RPATH-based library resolution instead of global LD_LIBRARY_PATH;
• bundles only the Mesa software rasterizer needed for headless GL-linked tools;
• downloads and packages selected AFNI standard-space templates;
• generates autoboxed template targets for more compact EPI alignment spaces;
• builds and packages a standalone dcm2niix utility.

Expected runtime compatibility

The generated runtime is designed for Linux x86_64 systems with a sufficiently compatible glibc userspace. Because the runtime is built against a manylinux2014-compatible environment and bundles its non-core AFNI/SUMA/X11/Mesa/Motif dependencies, it is expected to run on many common modern Linux distributions without requiring a system AFNI installation.

Expected compatible environments include:

• Ubuntu 20.04, 22.04, 24.04, and newer
• Debian 11, Debian 12, and newer
• Linux Mint releases based on Ubuntu 20.04 or newer
• Fedora 36 and newer
• Rocky Linux 8/9 and newer
• AlmaLinux 8/9 and newer
• RHEL 8/9 and compatible enterprise Linux distributions
• CentOS Stream 8/9 and newer
• openSUSE Leap 15.x and newer
• Arch Linux and other rolling distributions with current glibc
• WSL2 Ubuntu on Windows

The runtime is not expected to support very old Linux distributions with glibc versions older than the manylinux2014 baseline. It is also not intended for native macOS or native Windows execution. On Windows, the intended compatibility path is WSL2. On macOS, a native macOS AFNI runtime will require a separate build.

Why not expose the full runtime globally?

The runtime contains a bundled AFNI/SUMA/X11/Mesa/Motif dependency closure. Exposing this entire environment globally could shadow a user’s existing AFNI installation or interfere with GUI-oriented AFNI use.

Instead, the ME-ICA install flow should generally work as follows:

source ~/activate_meica
  activates the ME-ICA Python environment
  exposes meica.py
  exposes selected runtime/utils tools such as dcm2niix
  does not globally expose runtime/bin

meica.py
  internally activates the distributed AFNI runtime for its own process
  performs dependency checks against the distributed runtime
  writes _meica_*.sh scripts that explicitly source activate_meica_afni

_meica_*.sh
  explicitly uses the distributed AFNI runtime

This keeps the user-facing environment clean while making ME-ICA runs reproducible.

Templates included

The runtime packages selected AFNI template assets into bin/, including:

TT_N27+tlrc
MNI_caez_N27+tlrc
MNI152_2009_template.nii.gz

The builder also creates autoboxed variants:

TT_N27_ab.nii.gz
MNI_caez_N27_ab.nii.gz
MNI152_2009_template_ab.nii.gz

These autoboxed templates are intended to serve as more compact spatial targets for EPI resampling/alignment, reducing unnecessary empty space in functional-data target grids.

dcm2niix utility

The builder compiles dcm2niix from source and installs it into:

meica-afni-runtime/utils/dcm2niix

This location is intentionally separate from the internal AFNI runtime bin/. The ME-ICA installer can expose utils/ to the user environment while keeping the full AFNI runtime private to ME-ICA execution.

Usage

A typical build is:

chmod +x meica4-afni-build.sh
./meica4-afni-build.sh

The output is:

meica-afni-build/runtime/meica-afni-runtime/
meica-afni-build/meica-afni-runtime.tar.gz

A fresh rebuild can be forced with:

rm -rf meica-afni-build
./meica4-afni-build.sh

Individual stages use marker files under:

meica-afni-build/.done/

so parts of the build can be rerun by removing selected marker files.

Important audit outputs

The builder writes audit files into:

meica-afni-runtime/audit/

Important audit outputs include:

ldd_all_post_bundle.txt
runtime_resolution_all.txt
runtime_resolution_failures.txt
dynamic_libgomp_users.txt
template_manifest.txt
template_sha256sums.txt
dcm2niix_help.txt
dcm2niix_sha256sum.txt
smoke_tests.txt
smoke_failures.txt
loader_smoke_all.txt
loader_smoke_failures.txt

The build should fail if:

• required runtime assets are missing;
• forbidden core glibc ABI libraries are bundled;
• dynamic libgomp dependencies remain in packaged binaries;
• required explicit smoke tests fail;
• non-core libraries resolve to host system paths instead of bundled paths.

Platform status

Current target:

Linux x86_64
WSL2 Ubuntu

Planned or future targets:

macOS Apple Silicon
macOS Intel
Linux AppImage
.deb / .rpm packages
Windows launcher invoking WSL2

The current macOS strategy is not to use this Linux runtime. Until native macOS runtimes are built, the ME-ICA installer should require a user/system AFNI installation on macOS.

Relationship to ME-ICA

This repository builds the runtime support package for ME-ICA 4. It is not the main ME-ICA analysis repository.

The runtime tarball produced here is intended to be downloaded by the ME-ICA installer and placed within the ME-ICA source tree, for example:

install_dir/
  me-ica/
    meica-afni-runtime/
  micromamba/

meica.py should then activate the distributed runtime internally for dependency checks and processing execution.

Citation

Please cite:

MEICA4: Quantitative Precision Functional Mapping: Stable high-dimensional fMRI decomposition and artifact-resolved denoising
of multi-echo fMRI

Prantik Kundu & R. Nathan Spreng
Whitepaper: 10.17605/OSF.IO/DN9BM

Copyright

Copyright © 2026 EyeThree, Inc.

Developer: Prantik Kundu, PhD

Notes

This runtime builder is intended to support reproducible ME-ICA execution and simplify installation for users who do not want to manage AFNI, OpenMP, Mesa, Motif, X11, template assets, or DICOM conversion utilities manually.

It is intentionally conservative about what is exposed to the user’s shell. The full AFNI runtime should remain scoped to ME-ICA execution unless a user explicitly enters a debugging/runtime mode.