From 0e8c576e8ddad02a4acec0f7ea14666ca724d433 Mon Sep 17 00:00:00 2001 From: "arnaud.bore" Date: Thu, 6 Jul 2023 11:02:10 -0400 Subject: [PATCH] revert doc --- docs/get-started/install.md | 13 +- docs/how-to/create-config-file.md | 79 ++++------- docs/how-to/use-advanced-commands.md | 189 +++------------------------ docs/tutorial/first-steps.md | 62 ++++----- 4 files changed, 80 insertions(+), 263 deletions(-) diff --git a/docs/get-started/install.md b/docs/get-started/install.md index 993d207f..0043f170 100644 --- a/docs/get-started/install.md +++ b/docs/get-started/install.md @@ -189,7 +189,7 @@ name: dcm2bids channels: - conda-forge dependencies: - - python>=3.8 + - python>=3.7 - dcm2niix - dcm2bids ``` @@ -277,7 +277,7 @@ usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure -dcm2bids 3.0.0 +dcm2bids 2.1.7 options: -h, --help show this help message and exit @@ -292,14 +292,13 @@ options: -o OUTPUT_DIR, --output_dir OUTPUT_DIR Output BIDS directory, Default: current directory (/home/sam/dcm2bids-proj) - --auto_extract_entities If set, it will automatically try to extract entity information [task, dir, echo] - depending on the suffix and datatype. [False] - --bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False] - bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists --clobber Overwrite output if it exists -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} Set logging level + -a, --anonymizer This option no longer exists from the script in this + release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m + aster/README.md#defaceTpl Documentation at https://github.com/unfmontreal/Dcm2Bids ``` @@ -342,7 +341,7 @@ containers: channels: - conda-forge dependencies: - - python>=3.8 + - python>=3.7 - dcm2niix - dcm2bids diff --git a/docs/how-to/create-config-file.md b/docs/how-to/create-config-file.md index d9ada266..005e9899 100644 --- a/docs/how-to/create-config-file.md +++ b/docs/how-to/create-config-file.md @@ -6,54 +6,52 @@ { "descriptions": [ { - "datatype": "anat", - "suffix": "T2w", + "dataType": "anat", + "modalityLabel": "T2w", "criteria": { "SeriesDescription": "*T2*", "EchoTime": 0.1 }, - "sidecar_changes": { + "sidecarChanges": { "ProtocolName": "T2" } }, { - "id": "task-rest", - "datatype": "func", - "suffix": "bold", - "custom_entities": "task-rest", + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", "criteria": { "ProtocolName": "func_task-*", "ImageType": ["ORIG*", "PRIMARY", "M", "MB", "ND", "MOSAIC"] } }, { - "datatype": "fmap", - "suffix": "fmap", - "intendedFor": "task_rest", + "dataType": "fmap", + "modalityLabel": "fmap", + "intendedFor": 1, "criteria": { "ProtocolName": "*field_mapping*" } }, { - "id": "id_task_learning", - "datatype": "func", - "suffix": "bold", - "custom_entities": "task-learning", + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-learning", "criteria": { "SeriesDescription": "bold_task-learning" }, - "sidecar_changes": { + "sidecarChanges": { "TaskName": "learning" } }, { - "datatype": "fmap", - "suffix": "epi", + "dataType": "fmap", + "modalityLabel": "epi", "criteria": { "SeriesDescription": "fmap_task-learning" }, - "IntendedFor": "id_task_learning", - "sidecar_changes": { + "IntendedFor": 2, + "sidecarChanges": { "TaskName": "learning" } } @@ -100,7 +98,7 @@ subject to change depending on the dcm2niix version in use. You can enter several criteria. **All criteria must match** for a description to be linked to a sidecar. -## datatype +## dataType It is a mandatory field. Here is a definition from `bids v1.2.0` : @@ -110,12 +108,12 @@ It is a mandatory field. Here is a definition from `bids v1.2.0` : > field maps), anat (structural imaging such as T1, T2, etc.), meg > (magnetoencephalography), beh (behavioral). -## suffix +## modalityLabel It is a mandatory field. It describes the modality of the acquisition like `T1w`, `T2w` or `dwi`, `bold`. -## custom_entities +## customLabels It is an optional field. For some acquisitions, you need to add information in the file name. For resting state fMRI, it is usually `task-rest`. @@ -126,40 +124,19 @@ specifications][bids-spec]. For a longer example of a Dcm2Bids config json, see [here](https://github.com/unfmontreal/Dcm2Bids/blob/master/example/config.json). -Note that the different bids labels must come in a very specific order to be bids valid filenames. -If the custom_entities fields that are entered that are in the wrong order, -then dcm2bids will reorder them for you. - -For example if you entered: - -```json -"custom_entities": "run-01_task-rest" -``` - -when running dcm2bids, you will get the following warning: - -```bash -WARNING:dcm2bids.structure:✅ Filename was reordered according to BIDS entity table order: - from: sub-ID01_run-01_task-rest_bold - to: sub-ID01_task-rest_run-01_bold -``` - -custom_entities could also be combined with extractors. -See [custom_entities combined with extractors](./use-advanced-commands.md#custom_entities-combined-with-extractors) - - -## sidecar_changes +## sidecarChanges Optional field to change or add information in a sidecar. -## id and intendedFor +## intendedFor -Optional field to add an `IntendedFor` entry in the sidecar of a fieldmap. -You will need to set an id to the corresponding description and put the same id in the `IntendedFor` field. +Optional field to add an `IntendedFor` entry in the sidecar of a fieldmap. Just +put the index or a list of indices of the description(s) that's intended for. -Fo example, **`task_rest`** means it is intended for `task-rest_bold` -and **`id_task_learning`** is intended for `task-learning` which will be -renamed to only `learning` because of the `"sidecar_changes": { "TaskName": "learning" }` field. +Python index begins at `0` so in the example, **`1`** means it is intended for +`task-rest_bold` and **`2`** is intended for `task-learning` which will be +renamed to only `learning` because of the +`"sidecarChanges": { "TaskName": "learning" }` field. ## Multiple config files diff --git a/docs/how-to/use-advanced-commands.md b/docs/how-to/use-advanced-commands.md index f7e23a93..a8185c83 100644 --- a/docs/how-to/use-advanced-commands.md +++ b/docs/how-to/use-advanced-commands.md @@ -1,89 +1,46 @@ -# How to use advanced configuration +# How to use advanced commands and configuration These optional configurations could be insert in the configuration file at the same level as the `"descriptions"` entry. ``` { - "extractors": {"SeriesDescription": ["run-(?P[0-9]+)", "task-(?P[0-9]+)"], - "BodyPartExamined": ["(?P[a-zA-Z]+)"]}, - "search_method": "fnmatch", - "case_sensitive": true, - "post_op": [{"cmd": "pydeface --outfile dstFile srcFile", - "datatype": "anat", - "suffix": ["T1w", "MP2RAGE"]}], + "searchMethod": "fnmatch", + "caseSensitive": true, + "defaceTpl": ["pydeface", "--outfile", "dstFile", "srcFile"], "description": [ - { - "datatype": "anat", - "suffix": "T2w", - "custom_entities": ["acq-highres", "bodypart", "run", "task"], - } + ... ] - ... } ``` -## custom_entities combined with extractors +## searchMethod -default: None - -extractors will allow you to extract information embeded into sidecar files. -In the example above, it will try to match 2 different regex expressions (keys: task, run) within the -SeriesDescription field and bodypart in BodyPartExamined field. - -By using the same keys in custom_entities and if found, it will add this new entities directly into the final filename. -custom_entities can be a list that combined extractor keys and regular entities. -If key is `task` it will automatically add the field "TaskName" inside the sidecase file. - -## search_method - -default: `"search_method": "fnmatch"` +default: `"searchMethod": "fnmatch"` fnmatch is the behaviour (See criteria) by default and the fall back if this option is set incorrectly. `re` is the other choice if you want more flexibility to match criteria. -## case_sensitive +## caseSensitive -default: `"case_sensitive": "true"` +default: `"caseSensitive": "true"` If false, comparisons between strings/lists will be not case sensitive. It's -only disabled when used with `"search_method": "fnmatch"`. +only disabled when used with `"searchMethod": "fnmatch"`. -## post_op +## defaceTpl -default: `"post_op": []` +default: `"defaceTpl": None` -post_op key allows you to run any post-processing analyses just before being moved -to there respective folders. - -For example, if you want to deface your T1w images you could use pydeface by adding: -``` - "post_op": [{"cmd": "pydeface --outfile dstFile srcFile", - "datatype": "anat", - "suffix": ["T1w", "MP2RAGE"]}], -``` +!!! danger The anonymizer option no longer exists from `v2.0.0`. It is still +possible to deface the anatomical nifti images. -It will specifically run the corresponding `cmd` to any image that follow the combinations -datatype/suffix: `(anat, T1w) or (anat, MP2RAGE)`. +For example, if you use the last version of pydeface, add: -!!! warning "Multiple post_op commands" +`"defaceTpl": "pydeface --outfile {dstFile} {srcFile}"` - Although you can add multiple commands, the combination datatype/suffix on which you want to run the command has to be unique. - You cannot run multiple commands on a specific combination datatype/suffix. - -``` - "post_op": [{"cmd": "pydeface --outfile dstFile srcFile", - "datatype": "anat", - "suffix": ["T1w", "MP2RAGE"]}, - {"cmd": "my_new_script --input srcFile --output dstFile ", - "datatype": "fmap", - "suffix": ["any"]}], -``` - -In this example the second command "my_new_script" will be running on any image which datatype is fmap. - -Finally, this is a template string and dcm2bids will replace srcFile and dstFile by the +It is a template string and dcm2bids will replace {srcFile} and {dstFile} by the source file (input) and the destination file (output). ## dcm2niixOptions @@ -99,115 +56,3 @@ default: `"compKeys": ["SeriesNumber", "AcquisitionTime", "SidecarFilename"]` Acquisitions are sorted using the sidecar data. The default behaviour is to sort by `SeriesNumber` then by `AcquisitionTime` then by the `SidecarFilename`. You can change this behaviour setting this key inside the configuration file. - - -# How to use advanced commands - -## dcm2bids advanced options - -By now, you should be used to getting the `--help` information before running a -command. - -=== "Command" - - ```sh - dcm2bids --help - ``` - -=== "Output" - - ```sh hl_lines="2-3" - (dcm2bids) sam:~/dcm2bids-tutorial/bids_project$ dcm2bids --help - usage: dcm2bids [-h] -d DICOM_DIR [DICOM_DIR ...] -p PARTICIPANT [-s SESSION] -c CONFIG [-o OUTPUT_DIR] [--forceDcm2niix] [--clobber] - [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] - - Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure - dcm2bids 3.0.0 - - options: - -h, --help show this help message and exit - -d DICOM_DIR [DICOM_DIR ...], --dicom_dir DICOM_DIR [DICOM_DIR ...] - DICOM directory(ies) - -p PARTICIPANT, --participant PARTICIPANT - Participant ID - -s SESSION, --session SESSION - Session ID - -c CONFIG, --config CONFIG - JSON configuration file (see example/config.json) - -o OUTPUT_DIR, --output_dir OUTPUT_DIR - Output BIDS directory, Default: current directory (/home/sam/dcm2bids-tutorial/bids_project) - --auto_extract_entities If set, it will automatically try to extract entity information [task, dir, echo] - depending on the suffix and datatype. [False] - --bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False] - bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart - --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists - --clobber Overwrite output if it exists - -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} - Set logging level - - Documentation at https://github.com/unfmontreal/Dcm2Bids - - ``` - -## --auto_extract_entities - -This option will automatically try to find 3 entities (task, dir and echo) for specific datatype/suffix. - -* `task` in the SeriesDescription field - - Regex expression `task-(?P[a-zA-Z0-9]+)` - -* `dir` in the PhaseEncodedDirection field - - Regex expression `(?P-?j|i)` - -* `echo` in the EchoNumber field - - Regex expression `(?P[0-9])` - -If found, it will try to feed the filename with this entity if they are mandatory. - -For example, a "pepolar" fieldmap data requires the entity `dir` (See [BIDS specification](https://bids-specification.readthedocs.io/en/stable/04-modality-specific-files/01-magnetic-resonance-imaging-data.html#case-4-multiple-phase-encoded-directions-pepolar)). -If you set this parameter, it will automatically try to find this entity and add it to the filename. - -So far and accordingly to the BIDS specification 5 datatype/suffix automatically look for this 3 entities. - -| datatype | suffix | Entities | -|:--------:|:----------:|:--------:| -| anat | MEGRE | echo | -| anat | MESE | echo | -| func | cbv | task | -| func | bold | task | -| func | sbref | task | -| fmap | epi | dir | - -Using the `--auto_extract_entitie`, if you want another combination of datatype/suffix to be able to -extract one or more of these 3 entities you need to add the key of the entities needed using the field custom_entities like this within your description: - -``` -"custom_entities": ["echo", "dir"] -``` - -:warning: If task is found, it will automatically add the field `TaskName` into the sidecar file. -It means you don't have to add the field in the config file like this. - - - -``` -{ - "sidecar_changes": { - "TaskName": "learning" - } -} -``` - - - -:radioactive: You can find more detailed information by looking at the file `dcm2bids/utils/utils.py` and -more specifically auto_extractors and auto_entities variables. - - -## --bids_validate - -By default, Dcm2bids will not validate your final BIDS structure. -If needed, you can install [bids-validator](https://github.com/bids-standard/bids-validator#quickstart) and activate this option. diff --git a/docs/tutorial/first-steps.md b/docs/tutorial/first-steps.md index ba74d303..f8519e64 100644 --- a/docs/tutorial/first-steps.md +++ b/docs/tutorial/first-steps.md @@ -83,7 +83,7 @@ You can test it with any command but a safe way is to use the `--help` command. [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure - dcm2bids 3.0.0 + dcm2bids 2.1.7 options: -h, --help show this help message and exit @@ -98,16 +98,16 @@ You can test it with any command but a safe way is to use the `--help` command. -o OUTPUT_DIR, --output_dir OUTPUT_DIR Output BIDS directory, Default: current directory (/home/sam) - --auto_extract_entities If set, it will automatically try to extract entity information [task, dir, echo] - depending on the suffix and datatype. [False] - --bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False] - bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists --clobber Overwrite output if it exists -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} Set logging level + -a, --anonymizer This option no longer exists from the script in this + release. See:https://github.com/unfmontreal/Dcm2Bids/blob/m + aster/README.md#defaceTpl Documentation at https://github.com/unfmontreal/Dcm2Bids + ``` ??? bug "What you can do if you did not get this output" @@ -669,7 +669,7 @@ good unique identifier. === "Command" ```sh - cat tmp_dcm2bids/helper/004_In_DCM2NIIX_regression_test_20180918114023.json + cat code/dcm2bids_config.json ``` === "Output" @@ -801,15 +801,15 @@ task name: { "descriptions": [ { - "datatype": "func", - "suffix": "bold", - "custom_entities": "task-rest", + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", "criteria": { "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)*" - }, - "sidecar_changes": { + "sidecarChanges": { "TaskName": "rest" } + } } ] } @@ -829,13 +829,13 @@ task name: { "descriptions": [ { - "datatype": "func", - "suffix": "bold", - "custom_entities": "task-rest", + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", "criteria": { "SeriesDescription": "*Axial EPI-FMRI (Interleaved I to S)*" }, - "sidecar_changes": { + "sidecarChanges": { "TaskName": "rest" } } @@ -885,34 +885,33 @@ file with the appropriate info. { "descriptions": [ { - "id": "id_task-rest", - "datatype": "func", - "suffix": "bold", - "custom_entities": "task-rest", + "dataType": "func", + "modalityLabel": "bold", + "customLabels": "task-rest", "criteria": { "SeriesDescription": "Axial EPI-FMRI (Interleaved I to S)*" }, - "sidecar_changes": { + "sidecarChanges": { "TaskName": "rest" } }, { - "datatype": "fmap", - "suffix": "epi", - "custom_entities": "dir-AP", + "dataType": "fmap", + "modalityLabel": "epi", + "customLabels": "dir-AP", "criteria": { "SeriesDescription": "EPI PE=AP*" }, - "intendedFor": "id_task-rest" + "intendedFor": 0 }, { - "datatype": "fmap", - "suffix": "epi", - "custom_entities": "dir-PA", + "dataType": "fmap", + "modalityLabel": "epi", + "customLabels": "dir-PA", "criteria": { "SeriesDescription": "EPI PE=PA*" }, - "intendedFor": "id_task-rest" + "intendedFor": 0 } ] } @@ -952,7 +951,7 @@ command. [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-a] Reorganising NIfTI files from dcm2niix into the Brain Imaging Data Structure - dcm2bids 3.0.0 + dcm2bids 2.1.7 options: -h, --help show this help message and exit @@ -966,14 +965,11 @@ command. JSON configuration file (see example/config.json) -o OUTPUT_DIR, --output_dir OUTPUT_DIR Output BIDS directory, Default: current directory (/home/sam/dcm2bids-tutorial/bids_project) - --auto_extract_entities If set, it will automatically try to extract entity information [task, dir, echo] - depending on the suffix and datatype. [False] - --bids_validate If set, once your conversion is done it will check if your output folder is BIDS valid. [False] - bids-validator needs to be installed check: https://github.com/bids-standard/bids-validator#quickstart --forceDcm2niix Overwrite previous temporary dcm2niix output if it exists --clobber Overwrite output if it exists -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log_level {DEBUG,INFO,WARNING,ERROR,CRITICAL} Set logging level + -a, --anonymizer This option no longer exists from the script in this release. See:https://github.com/unfmontreal/Dcm2Bids/blob/master/README.md#defaceTpl Documentation at https://github.com/unfmontreal/Dcm2Bids