doc: add resampling use case

examples/fmriprep-resample/README.md

@@ -0,0 +1,108 @@
+# Use case: resample a BOLD image onto a target space
+
+This example demonstrates how to run a simple Python [script](https://hub.datalad.org/mslw/fmriprep-resampling) to reproduce fMRIPrep's preprocessed BOLD image (projected onto a target space) from the raw image, ancillary fMRIPrep derivatives, and related metadata. All dependencies for the script are provided by an fMRIPrep singularity container. The singularity container used in this example is `bids-fmriprep--24.1.0` and comes from the [ReproNim containers collection](https://github.com/ReproNim/containers).
+
+The example comprises the following files:
+- `fmriprep-resample` template
+- `input.txt` input specification
+- `output.txt` output specification
+- `parameter.txt` parameters
+
+## Requirements
+
+This example requires Singularity.
+
+Please note, that there is no need to install fMRIPrep. The singularity container will be automatically retrieved from the ReproNim containers collection.
+
+## How to install
+
+Install `datalad-remake` extension, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#installation).
+
+## How to use
+
+It is assumed that you have a local copy of the `datalad-remake` project in your `$HOME` directory. If this not the case, adjust the path below:
+
+```
+EXAMPLE=$HOME/datalad-remake/examples/fmriprep-resample
+```
+
+### Clone example dataset
+
+To run the example, you'll need a raw BIDS dataset that has been minimally preprocessed with fMRIPrep. For a complete list of data dependencies, please refer to [this](https://github.com/datalad/datalad-remake/blob/main/examples/fmriprep-resample/input.txt) specification.
+
+For convenience, a ready-made dataset containing all inputs required for running the example can be obtained like so:
+
+```bash
+> cd $HOME
+> datalad clone https://hub.datalad.org/example my-project
+> cd my-project
+> datalad get -n data/ds001734
+> datalad get -n derivatives/ds001734
+```
+
+The dataset is organized in a modular way. It contains raw BIDS data (`data/ds001734`), as well as fMRIPrep derivative data (`derivatives/ds001734`). Also, it includes the `resample.py` script, as well as the software container that will be needed for running the script (`code/containers`).
+
+The resulting dataset structure is as follows:
+
+```
+my-project
+├── code
+│   ├── containers
+│   ├── make
+│   └── resample.py
+├── data
+│   └── ds001734
+└── derivatives
+    └── ds001734
+```
+
+### Configure (or enable) special remote
+
+Configure the dataset in which you want to collect the results of the (re)computation, in this case `derivatives/ds001734` subdataset.
+
+```bash
+> cd $HOME/my-project/derivatives/ds001734
+```
+
+If you're working with the ready-made example dataset, you are good to go. The `datalad-remake` special remote is already enabled. You can verify that by running:
+
+```bash
+> datalad siblings
+```
+
+If you're working with your own dataset, make sure to configure a `datalad-remake` special remote:
+
+```bash
+> git annex initremote datalad-remake type=external externaltype=datalad-remake \
+encryption=none allow-untrusted-execution=true autoenable=true
+```
+
+### Add template
+
+Place the `fmriprep-resample` template in the `.datalad/make/methods` of the root dataset:
+
+```bash
+> cd $HOME/my-project
+> cp $EXAMPLE/fmriprep-resample .datalad/make/methods/fmriprep-resample
+> datalad save -m "Add a make method"
+```
+
+Place the `input.txt`, `output.txt` and `parameter.txt` files in the root dataset. These files do not have to be tracked in git history, so no `datalad save` is required at this point.
+
+```bash
+> mkdir -p code/make/fmriprep-resample
+> cp $EXAMPLE/*.txt ./code/make/fmriprep-resample/
+```
+
+### Execute (re)computation
+
+To test the example, run:
+
+```bash
+> cd $HOME/my-project
+> datalad make \
+-I code/make/fmriprep-resample/input.txt \
+-O code/make/fmriprep-resample/output.txt \
+-P code/make/fmriprep-resample/parameter.txt \
+--allow-untrusted-execution fmriprep-resample
+```

examples/fmriprep-resample/fmriprep-resample

@@ -0,0 +1,24 @@
+# This example template runs a Python script to reproduce fMRIPrep's
+# preprocessed BOLD image (projected onto a target space) from the raw image,
+# ancillary fMRIPrep derivatives, and related metadata. All dependencies for
+# the script are provided by an fMRIPrep singularity container.
+#
+# The template takes the following inputs:
+# - container: the path to fMRIPrep singularity container image
+# - target_file: resampled file (fMRIPrep derivative) to reproduce
+# - raw_dataset: raw BIDS dataset location
+# - out_dir: base output path
+
+parameters = ['container', 'target_file', 'raw_dataset', 'out_dir']
+
+# Note: `{root_directory}` resolves to the directory of the dataset in which the
+# computation was started with `datalad make`.
+
+command = [
+    'singularity',
+    'exec', '{container}',
+    'python', 'code/resample.py',
+    '{target_file}',
+    '{root_directory}/{raw_dataset}',
+    '{root_directory}/{out_dir}'
+]

examples/fmriprep-resample/input.txt

@@ -0,0 +1,18 @@
+# Paths are relative to the dataset in which `datalad make` was executed
+derivatives/ds001734/dataset_description.json
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.json
+derivatives/ds001734/sub-001/fmap/sub-001_fmapid-auto00000_desc-preproc_fieldmap.json
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_desc-confounds_timeseries.tsv
+data/ds001734/task-MGT_bold.json
+data/ds001734/sub-001/func/sub-001_task-MGT_run-01_bold.nii.gz
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_from-orig_to-boldref_mode-image_desc-hmc_xfm.txt
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_from-boldref_to-auto00000_mode-image_xfm.txt
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt
+derivatives/ds001734/sub-001/anat/sub-001_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_space-MNI152NLin2009cAsym_boldref.nii.gz
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_space-MNI152NLin2009cAsym_desc-brain_mask.nii.gz
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_desc-hmc_boldref.nii.gz
+derivatives/ds001734/sub-001/fmap/sub-001_fmapid-auto00000_desc-magnitude_fieldmap.nii.gz
+derivatives/ds001734/sub-001/fmap/sub-001_fmapid-auto00000_desc-coeff_fieldmap.nii.gz
+code/containers/images/bids/bids-fmriprep--24.1.0.sing
+code/resample.py

examples/fmriprep-resample/output.txt

@@ -0,0 +1,2 @@
+# Paths are relative to the dataset in which `datalad make` was executed
+derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz

examples/fmriprep-resample/parameter.txt

@@ -0,0 +1,4 @@
+container=code/containers/images/bids/bids-fmriprep--24.1.0.sing
+target_file=derivatives/ds001734/sub-001/func/sub-001_task-MGT_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz
+raw_dataset=data/ds001734
+out_dir=derivatives/ds001734