Update examples

examples/fmriprep-docker/README.md

@@ -18,7 +18,7 @@ It is assumed that the license file is located in `/tmp`. Make sure to copy it t
 
 ## How to install
 
-Install `datalad-remake` extension, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#installation).
+Install `datalad-remake` extension, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#installation). Make sure that you have a valid GPG key and that you have successfully configured Git for commit signing, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#requirements).
 
 ## How to use
 
@@ -52,20 +52,6 @@ my-project
     └── ds001734
 ```
 
-### Configure 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
-```
-
-Add a `datalad-remake` special remote:
-
-```bash
-> git annex initremote datalad-remake type=external externaltype=datalad-remake encryption=none allow-untrusted-execution=true
-```
-
 ### Add template
 
 Place the `fmriprep-docker` template in the `.datalad/make/methods` of the root dataset:
@@ -84,6 +70,14 @@ Place the `input.txt`, `output.txt` and `parameter.txt` files in the root datase
 > cp $EXAMPLE/*.txt ./code/make/fmriprep-docker/
 ```
 
+### Configure trusted keys
+
+Configure trusted keys, by executing the command below. Replace `<key-id>` with a GPG key that you have used for signing commits. For more details, please go [here](https://github.com/datalad/datalad-remake#trusted-keys).
+
+```bash
+> git config --global --add datalad.make.trusted-keys <key-id>
+```
+
 ### Execute (re)computation
 
 To test the example, run:

examples/fmriprep-resample/README.md

@@ -0,0 +1,95 @@
+# 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). Make sure that you have a valid GPG key and that you have successfully configured Git for commit signing, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#requirements).
+
+## 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
+```
+
+### 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/
+```
+
+### Configure trusted keys
+
+Configure trusted keys, by executing the command below. Replace `<key-id>` with a GPG key that you have used for signing commits. For more details, please go [here](https://github.com/datalad/datalad-remake#trusted-keys).
+
+```bash
+> git config --global --add datalad.make.trusted-keys <key-id>
+```
+
+### 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

examples/fmriprep-singularity/README.md

@@ -18,7 +18,7 @@ It is assumed that the license file is located in `/tmp`. Make sure to copy it t
 
 ## How to install
 
-Install `datalad-remake` extension, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#installation).
+Install `datalad-remake` extension, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#installation). Make sure that you have a valid GPG key and that you have successfully configured Git for commit signing, as described [here](https://github.com/datalad/datalad-remake/tree/main?tab=readme-ov-file#requirements).
 
 ## How to use
 
@@ -55,20 +55,6 @@ my-project
     └── ds001734
 ```
 
-### Configure 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
-```
-
-Add a `datalad-remake` special remote:
-
-```bash
-> git annex initremote datalad-remake type=external externaltype=datalad-remake encryption=none allow-untrusted-execution=true
-```
-
 ### Add template
 
 Place the `fmriprep-singularity` template in the `.datalad/make/methods` of the root dataset:
@@ -87,6 +73,14 @@ Place the `input.txt`, `output.txt` and `parameter.txt` files in the root datase
 > cp $EXAMPLE/*.txt ./code/make/fmriprep-singularity/
 ```
 
+### Configure trusted keys
+
+Configure trusted keys, by executing the command below. Replace `<key-id>` with a GPG key that you have used for signing commits. For more details, please go [here](https://github.com/datalad/datalad-remake#trusted-keys).
+
+```bash
+> git config --global --add datalad.make.trusted-keys <key-id>
+```
+
 ### Execute (re)computation
 
 To test the example, run: