[ENH] add Apptainer definition (#1254)

* add definition file for apptainer

* start updating doc

Author: Remi-Gau

.github/workflows/apptainer_build.yml

@@ -0,0 +1,25 @@
+---
+name: apptainer build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: eWaterCycle/setup-apptainer@v2
+      with:
+        apptainer-version: 1.3.0
+    - name: build sif image
+      run: apptainer build bidspm.sif bidspm.def

bidspm.def

@@ -0,0 +1,54 @@
+BootStrap: docker
+From: bids/base_validator
+
+%post
+    apt-get -qq update
+    DEBIAN_FRONTEND=noninteractive apt-get --yes --quiet install \
+        build-essential \
+        software-properties-common \
+        apt-utils \
+        ca-certificates \
+        git \
+        curl \
+        python3 \
+        python3-pip \
+        fonts-freefont-otf \
+        ghostscript \
+        gnuplot-x11 \
+        libcurl4-gnutls-dev \
+        octave \
+        liboctave-dev \
+        octave-common \
+        octave-io \
+        octave-image \
+        octave-signal \
+        octave-statistics && \
+    apt-get clean && \
+    rm -rf \
+        /tmp/hsperfdata* \
+        /var/*/apt/*/partial \
+        /var/lib/apt/lists/* \
+        /var/log/apt/term*
+
+    mkdir /opt/spm12
+    curl -fsSL --retry 5 https://github.com/spm/spm12/archive/r7771.tar.gz | tar -xzC /opt/spm12 --strip-components 1
+    curl -fsSL --retry 5 https://raw.githubusercontent.com/spm/spm-octave/main/spm12_r7771.patch | patch -p0
+    make -C /opt/spm12/src PLATFORM=octave distclean
+    make -C /opt/spm12/src PLATFORM=octave
+    make -C /opt/spm12/src PLATFORM=octave install
+    ln -s /opt/spm12/bin/spm12-octave /usr/local/bin/spm12
+
+    mkdir /opt/bidspm
+    git clone --recurse-submodules https://github.com/cpp-lln-lab/bidspm.git /opt/bidspm
+    pip install --no-cache-dir --upgrade pip && \
+    pip3 --no-cache-dir install /opt/bidspm && \
+    octave --no-gui --eval "addpath('/opt/spm12/'); savepath ('/usr/share/octave/site/m/startup/octaverc');" && \
+    octave --no-gui --eval "addpath('/opt/bidspm/'); savepath('/usr/share/octave/site/m/startup/octaverc'); bidspm(); path"
+
+%runscript
+    bidspm "$@"
+
+%help
+    This is a bidspm container.
+    Please see the documentation for more instructions:
+    https://bidspm.readthedocs.io/en/latest/

docs/source/conf.py

@@ -53,7 +53,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["examples", "defaults", "demo", "images/*.md", "lib/CPP_ROI"]
+exclude_patterns = ["examples", "defaults", "demo", "images/*.md", "lib/CPP_ROI/**"]
 
 suppress_warnings = ["myst.header", "myst.xref_missing"]
 
@@ -69,7 +69,7 @@
 source_suffix = ".rst"
 
 intersphinx_mapping = {
-    "bids-matlab": ("https://bids-matlab.readthedocs.io/en/latest", None)
+    "bids-matlab": ("https://bids-matlab.readthedocs.io/en/main", None)
 }
 
 coverage_show_missing_items = True

docs/source/containers.md

@@ -0,0 +1,84 @@
+# Docker / Apptainer
+
+## Docker
+
+### Get image from docker hub
+
+```bash
+docker pull cpplab/bidspm:latest
+```
+
+### Build the docker image locally
+
+If you want to build the docker image locally and not pull it from the docker hub:
+
+```bash
+docker build . -f docker/Dockerfile -t cpplab/bidspm:latest
+```
+
+This will create an image with the tag name `bidspm:latest`.
+
+Running `make build_image` will also build the `stable` version
+and a version tagged image.
+
+### Run the docker image
+
+The following command would pull from our
+[docker hub](https://hub.docker.com/repository/docker/cpplab/bidspm)
+and start the docker image::
+
+```bash
+docker run -it --rm cpplab/bidspm:latest
+```
+
+The following command would do do the same,
+but it would also map 2 folders from your computer
+and run preprocessing on your dataset
+(assuming there is a task called `auditory`):
+
+```bash
+bids_dir=fullpath_to_bids_dataset
+output_dir=fullpath_to_your_output_folder
+
+docker run -it --rm \
+    -v $bids_dir:/raw \
+    -v $output_dir:/derivatives \
+    cpplab/bidspm:latest \
+        /raw \
+        /derivatives \
+        subject \
+        --task auditory \
+        --action preprocess \
+        --fwhm 8
+```
+
+Similarly this would run the statistics provided you give a bids stats model file
+and the path to the preprocessed data.
+
+```bash
+bids_dir=fullpath_to_bids_dataset
+output_dir=fullpath_to_your_output_folder
+model=fullpath_to_your_bids_stats_model
+
+docker run -it --rm \
+    -v $bids_dir:/raw \
+    -v $output_dir:/derivatives \
+    -v $model:/models/smdl.json \
+    cpplab/bidspm:latest \
+        /raw \
+        /derivatives \
+        subject \
+        --action stats \
+        --preproc_dir /derivatives/bidspm-preproc \
+        --model_file /models/smdl.json \
+        --fwhm 8
+```
+
+## Apptainer
+
+If you are plaaning to use [Apptainer](https://apptainer.org/) (formerly Singularity) to run bidspm,
+a definition file is provided in the repository.
+
+```bash
+apptainer build bidspm.sif bidspm.def
+```

docs/source/docker.rst

@@ -26,7 +26,7 @@ Welcome to bidspm documentation!
    fieldmaps
    quality_analysis
    mancoreg
-   docker
+   containers
    CHANGELOG
    links_and_references
    CONTRIBUTING

docs/source/index.rst

@@ -71,6 +71,15 @@ You can also remove bidspm from the path with:
 Installation on a computing cluster
 ===================================
 
+.. warning::
+
+  If you are planning to use bidspm on a compute cluster,
+  it may be easier to use a containerized version of it.
+  The repository includes an Apptainer ``bidspm.def`` definition file
+  to help.
+
+  Please see the containers section of the documentation.
+
 ..
 
   For stand alone download