diff --git a/docs/source/user/datalad-access.rst b/docs/source/user/datalad-access.rst index 46cd7cc..2072185 100644 --- a/docs/source/user/datalad-access.rst +++ b/docs/source/user/datalad-access.rst @@ -8,23 +8,11 @@ datasets which have already been created and made available, most likely on local infrastructure. Dataset generation is described in the previous section, :ref:`dl-generate`. -Requirements -^^^^^^^^^^^^ - -Cloning datasets generated with the ICF tooling and accessing the ICF -store requires `DataLad`_ with `Datalad-Next`_ extension installed. -You can find instructions for installing DataLad on your operating -system in the `DataLad Handbook`_. `Datalad-Next`_ can be installed -with `pip`_ [1]_. - -.. _datalad: https://www.datalad.org/ -.. _datalad-next: https://docs.datalad.org/projects/next -.. _datalad handbook: https://handbook.datalad.org/intro/installation.html -.. _pip: https://pip.pypa.io/en/stable/ - -Obtaining data hosted in the ICF store requires access credentials for -a given study, issued by the ICF. DataLad acts only as a client -software. See :ref:`dl-credentials` for details. +This workflow uses DataLad with DataLad-Next extension (see +:ref:`dl-requirements`). DataLad datasets index data in their original +(ICF) location. Obtaining data hosted in the ICF store requires access +credentials for a given study, issued by the ICF. DataLad acts only as +a client software. See :ref:`dl-credentials` for details. Clone & get ^^^^^^^^^^^ @@ -34,7 +22,7 @@ location, it can be cloned with DataLad from a URL containing the following components: * a set of configuration parameters, always constant -* store base URL (e.g., ``file:///data/group/groupname/local_dicom_store``) [2]_ +* store base URL (e.g., ``file:///data/group/groupname/local_dicom_store``) [1]_ * study ID (e.g., ``my-study``) * visit ID (e.g., ``P000123``) * a file name suffix / template, ``_annex{{annex_key}}`` (verbatim), always constant @@ -70,12 +58,7 @@ convenience features DataLad adds on top of this. .. rubric:: Footnotes -.. [1] To install software with pip, run a call such as the one below - in your favourite `virtual environment `_:: - - python -m pip install datalad-next - -.. [2] Examples use ``file://`` URLs, given that the datasets are most +.. [1] Examples use ``file://`` URLs, given that the datasets are most likely to be generated on institute-local infrastructure. Other protocoles (e.g. ``https://`` or ``ssh://``) can be substituted depending on the particular setup, without affecting the URL diff --git a/docs/source/user/datalad-generate.rst b/docs/source/user/datalad-generate.rst index e1f7822..ae27e5d 100644 --- a/docs/source/user/datalad-generate.rst +++ b/docs/source/user/datalad-generate.rst @@ -15,22 +15,11 @@ allow raw data versioning, integrate with existing workflows, and enable logical transformations of the DICOM folder structure - see :ref:`dl-advanced` for examples of the latter. -Software requirements -^^^^^^^^^^^^^^^^^^^^^ - -Accessing the ICF store requires `DataLad`_ with `Datalad-Next`_ -extension installed. You can find instructions for installing DataLad -on your operating system in the `DataLad Handbook`_. `Datalad-Next`_ -can be installed with `pip`_ [1]_. - -.. _datalad: https://www.datalad.org/ -.. _datalad-next: https://docs.datalad.org/projects/next -.. _datalad handbook: https://handbook.datalad.org/intro/installation.html -.. _pip: https://pip.pypa.io/en/stable/ - -Dataset generation workflow (all steps after the initial download) -uses the INM-ICF tools, which are packaged as a Singularity container; -see :ref:`container`. +The workflow described below uses DataLad with DataLad-Next extension +for initial DICOM download and the INM-ICF tools packaged as a +Singularity container for subsequent steps (see +:ref:`dl-requirements`). ICF access credentials are required (see +:ref:`dl-credentials`). Obtain the tarball ^^^^^^^^^^^^^^^^^^ @@ -140,10 +129,3 @@ representation in ``*XDLRA*`` files. The local store can be used as a DataLad entry point for obtaining the DICOM files from the ICF store (which would serve as the data source for dataset clones); see :ref:`dl-access`. - -.. rubric:: Footnotes - -.. [1] To install software with pip, run a call such as the one below - in your favourite `virtual environment `_:: - - python -m pip install datalad-next diff --git a/docs/source/user/datalad-requirements.rst b/docs/source/user/datalad-requirements.rst new file mode 100644 index 0000000..493ee1e --- /dev/null +++ b/docs/source/user/datalad-requirements.rst @@ -0,0 +1,35 @@ +.. _dl-requirements: + +DataLad requirements +-------------------- + +Accessing the ICF store contents and cloning datasets generated with +the ICF tooling requires `DataLad`_ with `Datalad-Next`_ extension +installed. You can find instructions for installing DataLad on your +operating system in the `DataLad Handbook`_. `Datalad-Next`_ can be +installed with `pip`_ [1]_. + +Generating DataLad datasets based on the DICOMS in the ICF store +additionally requires the INM-ICF tools, which are packaged as a +`Singularity`_ container; see :ref:`container`. The tools are not +required for accessing already existing DataLad datasets. + +Obtaining data hosted in the ICF store requires access credentials for +a given study, issued by the ICF. DataLad acts only as a client +software. See :ref:`dl-credentials` for details. + +.. rubric:: Footnotes + +.. [1] To install software with pip, run a call such as the one below + in your favourite `virtual environment`_: + + .. code-block:: bash + + python -m pip install datalad-next + +.. _datalad: https://www.datalad.org/ +.. _datalad-next: https://docs.datalad.org/projects/next +.. _datalad handbook: https://handbook.datalad.org/intro/installation.html +.. _pip: https://pip.pypa.io/en/stable/ +.. _virtual environment: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/ +.. _singularity: https://docs.sylabs.io/guides/main/user-guide/ diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst index 03b0a42..fadaf52 100644 --- a/docs/source/user/index.rst +++ b/docs/source/user/index.rst @@ -15,6 +15,7 @@ Please contact `ICF personnel`_ to get access and for any authentication-related :caption: Contents: browser + datalad-requirements datalad-credentials datalad-generate datalad-access