Merge pull request #9 from alexpron/heudiconv

[ENH]: DICOM to NIFTI BIDS conversion with Heudiconv

README.md

@@ -29,14 +29,20 @@ conda install -c conda-forge -c https://conda.anaconda.org/simpleitk SimpleITK b
 ```
 ## Usage
 
-There are three scripts to download datasets:
- - `shanoir_downloader.py` simply downloads datasets from a id, a list of ids, or directly from a [shanoir search as on the shanoir solr search page](https://shanoir.irisa.fr/shanoir-ng/solr-search),
- - `shanoir_downloader_check.py` is a more complete tool ; it enables to download datasets (from a csv or excel file containing a list of dataset ids, or directly from a [shanoir search as on the shanoir solr search page](https://shanoir.irisa.fr/shanoir-ng/solr-search)), verify their content, anonymize them and / or encrypt them.
- - `shanoir2bids.py` uses `shanoir_downloader.py` to download Shanoir datasets and reorganises them into a BIDS data structure that is specified by the user with a `.json` configuration file. An example of configuration file is provided `s2b_example_config.json`. 
+## How to download Shanoir datasets ?
 
-`shanoir_downloader_check.py` creates two files in the output folder:
- - `downloaded_datasets.csv` records the successfully downloaded datasets,
- - `missing_datasets.csv` records the datasets which could not be downloaded.
+There are three scripts to download datasets from a Shanoir instance: 
+
+1.`shanoir_downloader.py`:  downloads datasets from a id, a list of ids, or directly from a [shanoir search as on the shanoir solr search page](https://shanoir.irisa.fr/shanoir-ng/solr-search),
+
+2.`shanoir_downloader_check.py`: a more complete tool ; it enables to download datasets (from a csv or excel file containing a list of dataset ids, or directly from a [shanoir search as on the shanoir solr search page](https://shanoir.irisa.fr/shanoir-ng/solr-search)), verify their content, anonymize them and / or encrypt them.
+
+3.`shanoir2bids.py`: Download datasets from Shanoir in DICOM format and convert them into datalad datasets in BIDS format. The conversion is parameterised by a configuration file in `.json` format. 
+
+### `shanoir_downloader_check.py`
+ - `shanoir_downloader_check.py` creates two files in the output folder:
+   - `downloaded_datasets.csv` records the successfully downloaded datasets,
+   - `missing_datasets.csv` records the datasets which could not be downloaded.
 
 With those two files, `shanoir_downloader_check.py` is able to resume a download session (the downloading can be interrupted any time, the tool will not redownload datasets which have already been downloaded).
 
@@ -50,7 +56,11 @@ See `python shanoir_downloader_check.py --help` for more information.
 
 You might want to skip the anonymization process and the encryption process with the `--skip_anonymization` and `--skip_encryption` arguments respectively (or `-sa` and `-se`).
 
-For `shanoir2bids.py`, a configuration file must be provided to transform a Shanoir dataset into a BIDS dataset.
+
+### `shanoir2bids.py`
+
+A `.json` configuration file must be provided to transform a Shanoir dataset into a BIDS dataset.
+
 ```
 -----------------------------[.json configuration file information]-------------------------------
 This file will tell the script what Shanoir datasets should be downloaded and how the data will be organised.
@@ -61,31 +71,40 @@ The dictionary in the json file must have four keys :
 "data_to_bids": list of dict, each dictionary specifies datasets to download and BIDS format with the following keys :
     -> "datasetName": str, Shanoir name for the sequence to search
     -> "bidsDir"    : str, BIDS subdirectory sequence name (eg : "anat", "func" or "dwi", ...)
-    -> "bidsName"   : str, BIDS sequence name (eg: "t1w-mprage", "t2-hr", "cusp66-ap-b0", ...)
+
+    -> "bidsName"   : str, BIDS sequence name (eg: "t1w", "acq-b0_dir-AP", ...)
 ```
+Please refer to the [BIDS starter kit](https://bids-standard.github.io/bids-starter-kit/folders_and_files/files.html) 
+for exhaustive templates of filenames. A BIDS compatible example is provided in the file `s2b_example_config.json`.
 
-An example is provided in the file `s2b_example_config.json`.
 
 To download longitudinal data, a key `session` and a new entry `bidsSession` in `data_to_bids` dictionaries should be defined in the JSON configuration files. Of note, only one session can be downloaded at once. Then, the key `session` is just a string, not a list as for subjects.
 
 
-### Example usage
+
+### Download Examples 
+#### Raw download 
 
 To download datasets, verify the content of them, anonymize them and / or encrypt them you can use a command like:
 
 `python shanoir_downloader_check.py -u username -d shanoir.irisa.fr -ids path/to/datasets_to_download.csv -of path/to/output/folder/ -se -lf path/to/downloads.log`
 
 The `example_input_check.csv` file in this repository is an example input file (the format of the `datasets_to_download.csv` file should be the same).
 
+
+#### Solr search download
+
 You can also download datasets from a [SolR search](https://shanoir.irisa.fr/shanoir-ng/solr-search) as on the website:
 
 `python shanoir_downloader.py -u amasson -d shanoir.irisa.fr -of /data/amasson/test/shanoir_test4 --search_text "FLAIR" -p 1 -s 2 `
 
 where `--search_text` is the string you would use on [the SolR search page](https://shanoir.irisa.fr/shanoir-ng/solr-search) (for example `(subjectName:(CT* OR demo*) AND studyName:etude test) OR datasetName:*flair*`). More information on the info box of the SolR search page.
 
-`python shanoir2bids.py -c s2b_example_config.json -d my_download_dir` will download Shanoir files identified in the configuration file and saves them as a BIDS data structure into `my_download_dir`
+#### BIDS download
+`python shanoir2bids.py -j s2b_example_config.json -of my_download_dir --outformat nifti` will download Shanoir datasets identified in the configuration file  saves them as DICOM and convert them  into a BIDS datalad dataset into `my_download_dir`.
+
+## About Solr Search 
 
-### Search usage
 
 The `--search_text` and `--expert_mode` arguments work as on the [Shanoir search page](https://shanoir.irisa.fr/shanoir-ng/solr-search).
 

pyproject.toml

@@ -23,7 +23,13 @@ readme = "README.md"
 license = {file = "LICENSE"}
 keywords = ["Shanoir", "DICOM", "NIFTI", "BIDS"]
 classifiers = [
-  "Programming Language :: Python"
+
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10"
+
 ]
 
 [project.urls]

s2b_example_config.json

@@ -1,19 +1,29 @@
 {
-  "study_name": "Aneravimm",
-  "subjects": ["VS_Aneravimm_010", "VS_Aneravimm_011"],
-  "data_to_bids":
-  [
-    {"datasetName": "t1_mprage_sag_p2_iso", "bidsDir": "anat", "bidsName": "acq-mprage_T1w"},
+    "study_name": "Aneravimm",
+    "subjects": ["VS_Aneravimm_010", "VS_Aneravimm_011"],
+    "data_to_bids": [
+            {"datasetName": "t1_mprage_sag_p2_iso", "bidsDir": "anat", "bidsName": "acq-mprage_T1w"},
     {"datasetName": "t2_tse_HR_cor_MTL", "bidsDir": "anat", "bidsName": "acq-hr_T2w"},
-    {"datasetName": "Resting State_bold AP 1.6mm HIPP", "bidsDir": "func", "bidsName": "task-restingState_acq-hipp_dir-AP_bold"},
+    {"datasetName": "Resting State_bold AP 1.6mm HIPP", "bidsDir": "func", "bidsName": "task-restingState_dir-AP_bold"},
     {"datasetName": "Diff cusp66 b3000 AP 1.5mm", "bidsDir": "dwi", "bidsName": "acq-b3000_dir-AP_dwi"},
+    {"datasetName": "Diff cusp66 b0 PA 1.5mm", "bidsDir": "dwi", "bidsName": "acq-b0_dir-AP_dwi"},
     {"datasetName": "Diff cusp66 b0 PA 1.5mm", "bidsDir": "dwi", "bidsName": "acq-b0_dir-PA_dwi"}
   ],
-  "dcm2niix":"/home/qduche/Software/dcm2niix_lnx/dcm2niix",
-  "dcm2niix_options": "-v 0 -z y",
-  "find_and_replace_subject":
-  [
-    {"find":"VS_Aneravimm_", "replace": "VS"},
-    {"find":"Vs_Aneravimm_", "replace": "VS"}
-  ]
+    "dcm2niix": "/home/alpron/softs/miniconda3/envs/test-env/bin/dcm2niix",
+    "dcm2niix_options_comment": "dcm2niix configuration options in the nipype format (see https://nipype.readthedocs.io/en/latest/api/generated/nipype.interfaces.dcm2nii.html)",
+    "dcm2niix_options": {
+        "bids_format": true,
+        "anon_bids": true,
+        "compress": "y",
+        "compression": 5,
+        "crop": false,
+        "has_private": false,
+        "ignore_deriv": false,
+        "single_file": false,
+        "verbose": false
+    },
+    "find_and_replace_subject": [
+        {"find": "VS_Aneravimm_", "replace": "VS"},
+        {"find": "Vs_Aneravimm_", "replace": "VS"}
+    ]
 }