Command Line Download

daris-download is a command line utility included in daris-clients package can be used to download data from DaRIS.

Know Issues

23-Aug-2024:

We've discovered that this tool can sometimes terminate before it completes downloading all files. This issue is linked to a known defect in the Mediaflux AARv3 archive extraction API.

To clarify, all DICOM series in DaRIS are stored as archive files in the Arcitecta Archive format (AAR). When you download data using the daris-download command, it reads the archive file stream and extracts the DICOM files on the fly. However, there's a defect in the Mediaflux AAR Java API that causes the process to sometimes terminate unexpectedly when extracting files concurrently with multiple threads, without throwing an error.

We've reported this issue to Arcitecta (the vendor of Mediaflux software) and are awaiting the fix.

In the meantime, you can work around this issue by downloading the DICOM study without extracting the AAR archives first. Once all the AAR files have been downloaded, you can use the daris-archive command to extract them. Here’s how to do it: Download data as AAR archives

Install daris-clients

daris-clients need to be installed on your local computer. See this page for more details.

After daris-clients is installed, you can find daris-download command in daris-clients-<version>/bin directory.

Usage of daris-download

Usage of daris-download

USAGE:
  daris-download [OPTIONS] ID...

PARAMETERS:
      ID...              The identifiers of the DaRIS objects to download.

OPTIONS:
      --mf.config <mflux.cfg>
                         Mediaflux/DaRIS server configuration file. Defaults to
                           $HOME/.Arcitecta/mflux.cfg
      --output-dir <output-dir>
                         The output directory. If not specified, defaults to
                           current working directory.
      --unarchive <aar|all|none>
                         Unpack archive files. aar: unpack only archive in AAR
                           format; all: unpack all supported archive formats;
                           none: do not unpack. Defaults to aar.
      --parts <content|metadata|all>
                         Specifies which parts of the assets to download.
                           Defaults to content.
      --transcode FROM:TO[,FROM:TO...]...
                         Transcode data set format from one to another.
      --filter <query>   A query to filter/select the datasets.
      --nb-workers <n>   Number of worker threads.
      --step <n>         Query result page size.
      --dataset-only     Download datasets only.
      --no-attachments   Exclude attachments.
      --overwrite        Overwrite if exists.
  -h, --help             output usage information

Examples

Download all images from subject 1.5.1.3
- ```
daris-download 1.5.1.3
```
Download all images from project 1.5.1
- ```
daris-download 1.5.1
```
Download all images from subject 1.5.1.3 and convert dicom files to nifti format
- ```
daris-download --transcode dicom/series:nifti/series 1.5.1.3
```

Specify the config file path

daris-download --mf.config /tmp/mflux2.cfg 1.5.1.2

Specify a query/filter to select data

--filter option can be used to search/select data sets by specifying a query predicate in AQL (Asset Query Language). To compose of the query string, we need to know the meta data structure of the DaRIS datasets.

Asset Query Language documentation: The Asset Query Language.pdf

The examples below show how to specify --filter option to search/select data sets and download them:

Download all DICOM data sets within subject 1.5.1.3:

daris-download 1.5.1.3 --filter "mf-dicom-series has value"

Download all MR DICOM data sets within subject 1.5.1.3:

daris-download 1.5.1.3 --filter "xpath(mf-dicom-series/modality)='MR'"

Download those DICOM data sets, whose description element (0008,103E) contains word 'FLAIR'

daris-download 1.5.1 --filter "xpath(mf-dicom-series/description) contains 'FLAIR'"

Download raw PET/CT data sets in subject 1.5.1.3:

daris-download 1.5.1.3 --filter "daris:siemens-raw-petct-series has value"

Download raw PET/CT data sets whose protocol starts with word 'tbi_'

daris-download 1.5.1.3 --filter "xpath(daris:siemens-raw-petct-series/protocol) starts with 'tbi_'"

Download DICOM study as .AAR archive files

daris-download --nb-workers 8 --unarchive none 1.2.178.527

Once all the AAR files have been downloaded, you can use the daris-archive command to extract them:

find ./1.2.178/1.2.178.527 -type f -name "*.aar" | while read f; do dir=`dirname "$f"`/`basename "$f" .aar`; mkdir -p "$dir"; daris-archive extract "$f" "$dir"; rm "$f"; done