Skip to content

Commit

Permalink
Merge branch 'enh/derivatives' into enh/derivatives
Browse files Browse the repository at this point in the history
  • Loading branch information
@Lestropie
Lestropie authored Mar 7, 2019
2 parents ecbbe14 + 7540011 commit da97988
Show file tree
Hide file tree
Showing 5 changed files with 43 additions and 44 deletions.
7 changes: 1 addition & 6 deletions src/05-derivatives/01-introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,14 +106,13 @@ share the following (non-required) ones:
| ReferenceMap | REQUIRED when coordinate system is Aligned. Key indicates the reference atlas or map that the File is aligned to. See table below for list of common spaces. |
| NonstandardReference | REQUIRED when a non standard template or space is used. (e.g., a custom template in MNI305 space). A path to a file that was used as, or can be used as, a reference image for determining the coordinate space of this file. If Space is a list, Space reference must also be a list. |
| ReferenceIndex | REQUIRED when an index into a 4D (ReferenceMap or NonstandardReference) file is used. Used to index into a 4D spatial-reference file. |
| TransformFile | OPTIONAL. A path to the file used to transform the source into this file. |

### CoordinateSystem key allowed values

| **Value name** | **Description** |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| Device | The coordinate system of the device used to acquire the data. |
| Aligned | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc.,.). See the Space keyword for details of targets. |
| Aligned | The coordinate system is specified by a target space (e.g., Talairach88, MNI305, etc...). See the Space keyword for details of targets. |
| Custom | A custom coordinate system that is not in alignment (dimensions, axis orientation, unit) with any device coordinate system. |

### ReferenceMap key allowed values
Expand All @@ -134,7 +133,6 @@ is:

```JSON
{
"TransformFile": "/path/to/xfm",
"ReferenceMap": "MNI305"
}
```
Expand All @@ -144,7 +142,6 @@ used as standard space for the File. That can be written as follows:

```JSON
{
"TransformFile": "/path/to/xfm",
"NonstandardReference": "uri or path to file"
}
```
Expand All @@ -154,7 +151,6 @@ possibility is enabled by using lists of spaces and references:

```JSON
{
"TransformFile": "/path/to/xfm",
"ReferenceMap": ["MNI305", "fsLR32k"]
}
```
Expand All @@ -164,7 +160,6 @@ expressed as follows:

```JSON
{
"TransformFile": "/path/to/xfm",
"ReferenceMap": ["MNI152Lin", "fsLR164k"]
}
```
Expand Down
47 changes: 24 additions & 23 deletions src/05-derivatives/02-common-data-types.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,22 @@ data types in the specification. Examples:

- Motion-corrected DWI files.

The `space` keyword denotes reference atlas or map that the File is
aligned to - see [Introduction](01-introduction.md) for allowed values. The
The `space` keyword is recomended to distinguish files with different underlying
coordinate systems or registered to different reference maps. Its values are
restricted to the same vocabulary as `ReferenceMap` JSON field (see below). The
`desc` keyword is a general purpose field with freeform values. To distinguish
between multiple different versions of processing for the same input data the
`desc` keyword should be used. Note that even though `space` and `desc`
are optional at least one of them needs to be defined to avoid name conflict
with the raw file.
`desc` keyword should be used. Note that even though `space` and `desc` are
optional at least one of them needs to be defined to avoid name conflict with
the raw file.

Examples:

```Text
pipeline1/
sub-001/
func/
sub-001_task-rest_run-space-MNI305_bold.nii.gz
sub-001_task-rest_run-1_space-MNI305_bold.nii.gz
sub-001_task-rest_run-1_space-MNI305_bold.json
```

Expand All @@ -62,9 +63,9 @@ makes them invalid (e.g., if a source 4D image is averaged to create a single
static volume, a SamplingFrequency property would no longer be relevant). In
addition, all processed files include the following metadata JSON fields:

| **Key name** | **Description** |
| ------------- | -------------------------------------------------------------------------------------- |
| SkullStripped | REQUIRED. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |
| **Key name** | **Description** |
| ------------- | ----------------------------------------------------------------------------------------------- |
| SkullStripped | REQUIRED. Boolean. Whether the volume was skull stripped (non-brain voxels set to zero) or not. |

## Masks

Expand All @@ -74,12 +75,12 @@ Template:
<pipeline_name>/
sub-<participant_label>/
func|anat|dwi/
<source_keywords>[_space-<space>][_type-<type>][_desc-<label>]_mask.nii.gz
<source_keywords>[_space-<space>][_desc-<label>]_mask.nii.gz
```

A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`.
By default (i.e., if no transformation has taken place) the value of
`space` should be set to `orig`.
A binary (1 - inside, 0 - outside) mask in the space defined by `<space>`. By
default (i.e., if no transformation has taken place) the value of `space` should
be set to `orig`.

JSON metadata fields:

Expand Down Expand Up @@ -136,8 +137,8 @@ Example:
pipeline/
sub-001/
anat/
sub-001_space-ACPC_dseg.nii.gz
sub-001_space-ACPC_dseg.json
sub-001_space-orig_dseg.nii.gz
sub-001_space-orig_dseg.json
```

A segmentation could be a binary mask that functions as a discrete `label` for a
Expand All @@ -148,7 +149,7 @@ corresponding structure. For example:
pipeline/
sub-001/
anat/
sub-001_space-ACPC_label-GM_dseg.nii.gz
sub-001_space-orig_label-GM_dseg.nii.gz
```

See "Anatomical labels" for reserved key values for `label`.
Expand All @@ -175,8 +176,8 @@ Example:
pipeline/
sub-001/
anat/
sub-001_space-ACPC_label-BG_probseg.nii.gz
sub-001_space-ACPC_label-WM_probseg.nii.gz
sub-001_space-orig_label-BG_probseg.nii.gz
sub-001_space-orig_label-WM_probseg.nii.gz
```

See "Anatomical labels" for reserved key values for `label`.
Expand All @@ -188,8 +189,8 @@ tissue class, must provide a label mapping in its JSON sidecar. For example:
pipeline/
sub-001/
anat/
sub-001_space-ACPC_probseg.nii.gz
sub-001_space-ACPC_probseg.json
sub-001_space-orig_probseg.nii.gz
sub-001_space-orig_probseg.json
```

The JSON sidecar must include the label-map key that specifies a tissue label
Expand Down Expand Up @@ -274,8 +275,8 @@ Example:
pipeline/
sub-001/
anat/
sub-001_space-ACPC_dseg.nii.gz
sub-001_space-ACPC_dseg.tsv
sub-001_space-orig_dseg.nii.gz
sub-001_space-orig_dseg.tsv
```

Definitions can also be specified with a top-level dseg.tsv, which propagates to
Expand All @@ -288,7 +289,7 @@ pipeline/
dseg.tsv
sub-001/
anat/
sub-001_space-ACPC_dseg.nii.gz
sub-001_space-orig_dseg.nii.gz
```

These tsv lookup tables should contain the following columns:
Expand Down
14 changes: 8 additions & 6 deletions src/05-derivatives/04-functional-derivatives.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ applied to the original time series data:
| `_centered` | The time series has had its mean subtracted |

For example, `rot_z_shift_back_sq` means the square of the lagged version of the
Z rotation (see Motion-related regressors).
Z rotation (see [Motion-related regressors](#motion-related-regressors)).

### ROI-based time series extraction

Expand Down Expand Up @@ -173,8 +173,8 @@ atlases or segmentation algorithms:

Column names are unique alphanumeric values that are defined in a relevant JSON
sidecar file. A naming convention might be to concatenate the atlas, ROI index,
summarization method (defined below) and transformations (see Time series
transformations, above) using snake case. For example,
summarization method (defined below) and transformations (see [Time series
transformations](#time-series-transformations)) using snake case. For example,
`harvard_oxford_cortical_4_PC` could indicate ROI 4 of the Harvard-Oxford
cortical atlas, summarized by taking the first principal component.

Expand Down Expand Up @@ -247,9 +247,11 @@ following names and units:
| `trans_x`, `trans_y`, `trans_z` | mm | Translation parameters |
| `rot_x`, `rot_y`, `rot_z` | radians | Rotation parameters |

Transformations (see Transformations) of motion parameters may be included in
the same file. For example, rot_z_shift_back_sq means square of the lagged
version of Z rotation.
Transformations (see [Time series
transformations](#time-series-transformations)) of motion parameters may be
included in the same file.
For example, `rot_z_shift_back_sq` means square of the lagged version of Z
rotation.

The following columns indicate summarized motion, as defined in the
corresponding references:
Expand Down
18 changes: 9 additions & 9 deletions src/05-derivatives/05-diffusion-derivatives.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,9 @@ should be included in the pipeline documentation.
<pipeline_name>/
sub-<participant_label>/
dwi/
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.nii[.gz]
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.bvals
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_dwi.bvecs
<source_keywords>[_space-<space>][_desc-<label>]_dwi.nii[.gz]
<source_keywords>[_space-<space>][_desc-<label>]_dwi.bvals
<source_keywords>[_space-<space>][_desc-<label>]_dwi.bvecs
```

The JSON sidecar file is REQUIRED (due to the REQUIRED `SkullStripped` field -
Expand Down Expand Up @@ -54,8 +54,8 @@ The following is a general example of naming convention:
<pipeline_name>/
sub-<participant_label>/
dwi/
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
<source_keywords>[_space-<space>][_desc-<label>]_model-<label>[_parameter-<parameter>]_diffmodel.nii[.gz]
<source_keywords>[_space-<space>][_desc-<label>]_model-<label>_diffmodel.json
```

The following models are codified and should be used in the `model-<label>`
Expand Down Expand Up @@ -190,14 +190,14 @@ A 4D volume with floating point numbers:
my_diffusion_pipeline/
sub-01/
dwi/
sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.nii.gz
```

```Text
my_diffusion_pipeline/
sub-01/
dwi/
sub-01_referenecemap-T1w_desc-WLS_model-DTI_diffmodel.json
sub-01_space-T1w_desc-WLS_model-DTI_diffmodel.json
```

```JSON
Expand All @@ -222,7 +222,7 @@ fields for the maps.
<pipeline_name>/
sub-<participant_label>/
dwi/
<source_keywords>[_referencemap-<referencemap>][_space-<space>][_desc-<label>]_model-<label>_<parameter>.nii[.gz]
<source_keywords>[_space-<space>][_desc-<label>]_model-<label>_<parameter>.nii[.gz]
```

### Scalar maps
Expand Down Expand Up @@ -284,7 +284,7 @@ tractography visitation maps should be saved as NIfTIs.
<pipeline_name>/
sub-<participant_label>/
dwi/
<source_keywords>[_referencemap-<referencemap>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
<source_keywords>[_space-<space>][_desc-<label>][_subset-<label>]_tractography.[trk|tck|nii[.gz]]
```

### Filename keys
Expand Down
1 change: 1 addition & 0 deletions src/99-appendices/08-coordinate-systems.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ the units are assumed to be mm.
| FS305 | FreeSurfer variant of the MNI305 space |
| MNI152Lin | Also known as ICBM (version with linear coregistration) [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152Lin) |
| MNI152NLin6\[Sym&#124;Asym\] | Also known as ICBM 6th generation (non-linear coregistration). Used by SPM99 - SPM8 and FSL (MNI152NLin6Sym). [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin6) |
| MNI152NLin6AsymConte69 | Template based on MNI152NLin6Asym using Conte69 data. Built by Human Connectome Project. [https://github.com/Washington-University/HCPpipelines/tree/master/global/templates](https://github.com/Washington-University/HCPpipelines/tree/master/global/templates) |
| MNI152NLin2009\[a-c\]\[Sym&#124;Asym\] | Also known as ICBM (non-linear coregistration with 40 iterations, released in 2009). It comes in either three different flavours each in symmetric or asymmetric version. [http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009](http://www.bic.mni.mcgill.ca/ServicesAtlases/ICBM152NLin2009) |
| MNIColin27 | Average of 27 T1 scans of a single subject [http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres](http://www.bic.mni.mcgill.ca/ServicesAtlases/Colin27Highres) |
| MNI305 | Also known as avg305. |
Expand Down

0 comments on commit da97988

Please sign in to comment.