Installation¶

In general, there are two distinct ways to install and use ffrprep: either through virtualization/container technology, that is Docker or Singularity, or in a Bare metal version (Python 3.11+). Once you are ready to run ffrprep, see Usage for details.

Docker¶

In order to run `ffrprep` in a Docker container, Docker must be installed on your system. Once Docker is installed, you can get ffrprep through running one of the following commands in the terminal of your choice.

Option 1: pulling from the dockerhub registry :

docker pull sitek/ffrprep:version

Option 2: pulling from the github container registry :

docker pull ghcr.io/sitek/ffrprep:version

Where version is the specific version of ffrprep you would like to use. For example, if you want to employ the latest/most up to date version you can either run

docker pull ksitek/ffrprep:latest

docker pull ghcr.io/sitek/ffrprep:latest

or the same command without the :latest tag, as Docker searches for the latest tag by default. However, as the latest version is subject to changes and not necessarily in synch with the most recent numbered version, it is recommend to utilize the latter to ensure reproducibility. For example, if you want to employ ffrprep v0.0.1 the command would look as follows:

docker pull ksitek/ffrprep:v0.0.1

docker pull ghcr.io/sitek/ffrprep:v0.0.1

After the command finished (it may take a while depending on your internet connection), you can run ffrprep like this:

docker run -ti --rm \
    -v /path/to/bids_dataset:/data:rw \
    sitek/ffrprep:latest \
    /data /data/derivatives participant

Please have a look at the examples under Usage to get more information about and familiarize yourself with ffrprep’s functionality.

Singularity¶

For security reasons, many HPCs do not allow Docker containers, but support/allow Singularity containers. Depending on the Singularity version available to you, there are two options to get ffrprep as a Singularity image.

Preparing a Singularity image (Singularity version >= 2.5)¶

If the version of Singularity on your HPC is modern enough you can create a Singularity image directly on the HCP. This is as simple as:

$ singularity build /my_images/ffrprep-<version>.simg docker://ksitek/ffrprep:<version>

Where <version> should be replaced with the desired version of ffrprep that you want to download. For example, if you want to use ffrprep v0.0.4, the command would look as follows.

$ singularity build /my_images/ffrprep-v0.0.4.simg docker://ksitek/ffrprep:v0.0.4

Preparing a Singularity image (Singularity version < 2.5)¶

In this case, start with a machine (e.g., your personal computer) with Docker installed and the use docker2singularity to create a Singularity image. You will need an active internet connection and some time.

$ docker run --privileged -t --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /absolute/path/to/output/folder:/output \
    singularityware/docker2singularity \
    ksitek/ffrprep:<version>

Where <version> should be replaced with the desired version of `ffrprep` that you want to download and /absolute/path/to/output/folder with the absolute path where the created Singularity image should be stored. Sticking with the example of ffrprep v0.0.4 this would look as follows:

$ docker run --privileged -t --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /absolute/path/to/output/folder:/output \
    singularityware/docker2singularity \
    ksitek/ffrprep:v0.0.4

Beware of the back slashes, expected for Windows systems. The above command would translate to Windows systems as follows:

$ docker run --privileged -t --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v D:\host\path\where\to\output\singularity\image:/output \
    singularityware/docker2singularity \
    ksitek/ffrprep:<version>

You can then transfer the resulting Singularity image to the HPC, for example, using scp.

$ scp ksitek_ffrprep<version>.simg <user>@<hcpserver.edu>:/my_images

Where <version> should be replaced with the version of ffrprep that you used to create the Singularity image, <user> with your user name on the HPC and <hcpserver.edu> with the address of the HPC.

Running a Singularity Image¶

singularity run --cleanenv \
    -B /path/to/bids_dataset:/data \
    /my_images/ffrprep-<version>.simg \
    /data /data/derivatives participant

Note

Make sure to check the name of the created Singularity image as that might diverge based on the method you used. Here and going forward it is assumed that you used Singularity >= 2.5 and thus ffrprep-<version>.simg instead of ksitek_ffrprep<version>.simg.

Note

Singularity by default exposes all environment variables from the host inside the container. Because of this your host libraries (such as nipype) could be accidentally used instead of the ones inside the container - if they are included in PYTHONPATH. To avoid such situation we recommend using the --cleanenv singularity flag in production use. For example:

singularity run --cleanenv \
    -B /path/to/bids_dataset:/data \
    /my_images/ffrprep-<version>.simg \
    /data /data/derivatives participant

or, unset the PYTHONPATH variable before running:

unset PYTHONPATH; singularity run \
    -B /path/to/bids_dataset:/data \
    /my_images/ffrprep-<version>.simg \
    /data /data/derivatives participant

Note

Depending on how Singularity is configured on your cluster it might or might not automatically bind (mount or expose) host folders to the container. If this is not done automatically you will need to bind the necessary folders using the -B <host_folder>:<container_folder> Singularity argument. For example:

singularity run --cleanenv \
    -B /path/to/bids_dataset:/data \
    /my_images/ffrprep-<version>.simg \
    /data /data/derivatives participant

Bare metal version (Python 3.11+)¶

ffrprep requires Python 3.11 or above. Installation is managed with uv:

git clone https://github.com/sitek/ffrprep.git
cd ffrprep
uv sync

This creates a project-local .venv with every runtime dependency pinned by uv.lock. Activate it (source .venv/bin/activate) or prefix subsequent commands with uv run.

Check your installation with the --version argument:

uv run ffrprep --version