diff --git a/examples/fmriprep-docker/README.md b/examples/fmriprep-docker/README.md index 72a5893..44c7b46 100644 --- a/examples/fmriprep-docker/README.md +++ b/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 `` 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 +``` + ### Execute (re)computation To test the example, run: diff --git a/examples/fmriprep-resample/README.md b/examples/fmriprep-resample/README.md new file mode 100644 index 0000000..f7f9ffe --- /dev/null +++ b/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 `` 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 +``` + +### 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 +``` diff --git a/examples/fmriprep-resample/fmriprep-resample b/examples/fmriprep-resample/fmriprep-resample new file mode 100644 index 0000000..ecfcced --- /dev/null +++ b/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}' +] diff --git a/examples/fmriprep-resample/input.txt b/examples/fmriprep-resample/input.txt new file mode 100644 index 0000000..ab5ab69 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/examples/fmriprep-resample/output.txt b/examples/fmriprep-resample/output.txt new file mode 100644 index 0000000..cc743b4 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/examples/fmriprep-resample/parameter.txt b/examples/fmriprep-resample/parameter.txt new file mode 100644 index 0000000..59dd034 --- /dev/null +++ b/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 diff --git a/examples/fmriprep-singularity/README.md b/examples/fmriprep-singularity/README.md index f11faa5..a57fff5 100644 --- a/examples/fmriprep-singularity/README.md +++ b/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 `` 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 +``` + ### Execute (re)computation To test the example, run: