Skip to content

[FIX] Clarify data types and requirement levels for all JSON files #605

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 33 commits into from
Sep 19, 2020
Merged

[FIX] Clarify data types and requirement levels for all JSON files #605

Show file tree
Hide file tree
Changes from 22 commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
4d4dcf4
datatype draft
sappelhoff Sep 14, 2020
1b9ca3d
try smaller margins pdf for better tables
sappelhoff Sep 14, 2020
d08fe4d
specify paper size and margins via tex header
sappelhoff Sep 14, 2020
609e6b9
back to default margins, but valid specification now
sappelhoff Sep 14, 2020
fa17f72
make use of [link][] notation for brevity
sappelhoff Sep 15, 2020
74c1e02
enh tables in modality agnostic files
sappelhoff Sep 15, 2020
d420970
enh tables in common data types
sappelhoff Sep 15, 2020
a0a747d
work on 03-imaging
sappelhoff Sep 15, 2020
3ed71ff
enh genetics tables with req level and datatype
sappelhoff Sep 15, 2020
b34e9d6
enh physio+stim tables
sappelhoff Sep 15, 2020
9999631
enh ieeg, concistency ephys
sappelhoff Sep 15, 2020
cd1def4
fmt fixes, clarify geneticlevel https://github.com/bids-standard/bids…
sappelhoff Sep 15, 2020
5a44332
enh tables in EEG section
sappelhoff Sep 15, 2020
a02e419
backticks
sappelhoff Sep 16, 2020
45a39a4
PowerLineFrequency: number
sappelhoff Sep 16, 2020
9bcc60f
enh task event tables
sappelhoff Sep 16, 2020
04f6443
add links
sappelhoff Sep 16, 2020
36bef00
enh meg tables
sappelhoff Sep 16, 2020
6ee33fa
misc fixes
sappelhoff Sep 16, 2020
51df216
fix reference to by now non-existing section
sappelhoff Sep 16, 2020
71bf05f
get started on MRI tables, but how to proceed?
sappelhoff Sep 16, 2020
de57bd7
continue mri tables as far as possible
sappelhoff Sep 16, 2020
2a36ce6
decrease margins, drop a4 paper in favor of default
sappelhoff Sep 16, 2020
1b3afaa
center header and footer disregarding odd and even pages
sappelhoff Sep 16, 2020
a8cb249
add links, try pdf landscape
sappelhoff Sep 16, 2020
357bfd3
adjust cover abd header for landscape pdf
sappelhoff Sep 16, 2020
0d8cc76
fix: skip broken tables during python script
sappelhoff Sep 16, 2020
13fdd9a
add missing datatypes for mri
sappelhoff Sep 17, 2020
053950e
misc fixes
sappelhoff Sep 17, 2020
f16cfbc
add missing link
sappelhoff Sep 17, 2020
5914cc7
Update src/04-modality-specific-files/04-intracranial-electroencephal…
sappelhoff Sep 17, 2020
e8fe54b
fix pipe
sappelhoff Sep 17, 2020
e87497c
add missing link
sappelhoff Sep 19, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions pdf_build_src/header_setup.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,5 @@
linewidth=\textwidth,
basewidth=0.5em
}

\usepackage[a4paper, margin=1.5in]{geometry}
2 changes: 0 additions & 2 deletions pdf_build_src/pandoc_script.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,6 @@ def build_pdf(filename):
'--include-in-header=./header_setup.tex',
'-V documentclass=report',
'-V linkcolor:blue',
'-V geometry:a4paper',
'-V geometry:margin=2cm',
'--pdf-engine=xelatex',
'--output={}'.format(filename),
]
Expand Down
17 changes: 10 additions & 7 deletions src/02-common-principles.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,13 +426,13 @@ Note that if a field name included in the data dictionary matches a column name
then that field MUST contain a description of the corresponding column,
using an object containing the following fields:

| Field name | Definition |
| :---------- | :--------------------------------------------------------------------------------------------------------------------------- |
| LongName | OPTIONAL. Long (unabbreviated) name of the column. |
| Description | RECOMMENDED. Description of the column. |
| Levels | RECOMMENDED. For categorical variables: a dictionary of possible values (keys) and their descriptions (values). |
| Units | RECOMMENDED. Measurement units. SI units in CMIXF formatting are RECOMMENDED (see [Units](./02-common-principles.md#units)). |
| TermURL | RECOMMENDED. URL pointing to a formal definition of this type of data in an ontology available on the web. |
| **Key name** | **Requirement level** | **Data type** | **Description** |
| ------------ | --------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| LongName | OPTIONAL | [string][] | Long (unabbreviated) name of the column. |
| Description | RECOMMENDED | [string][] | Description of the column. |
| Levels | RECOMMENDED | [object][] of [strings][] | For categorical variables: An object of possible values (keys) and their descriptions (values). |
| Units | RECOMMENDED | [string][] | Measurement units. SI units in CMIXF formatting are RECOMMENDED (see [Units](./02-common-principles.md#units)). |
| TermURL | RECOMMENDED | [string][] | URL pointing to a formal definition of this type of data in an ontology available on the web. |

Please note that while both `Units` and `Levels` are RECOMMENDED, typically only one
of these two fields would be specified for describing a single TSV file column.
Expand Down Expand Up @@ -653,3 +653,6 @@ to suppress warnings or provide interpretations of your file names.

[dataset-description]: 03-modality-agnostic-files.md#dataset-description
[derived-dataset-description]: 03-modality-agnostic-files.md#derived-dataset-and-pipeline-description
[string]: https://www.w3schools.com/js/js_json_syntax.asp
[strings]: https://www.w3schools.com/js/js_json_syntax.asp
[object]: https://www.json.org/json-en.html
53 changes: 28 additions & 25 deletions src/03-modality-agnostic-files.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,20 @@ Templates:
The file `dataset_description.json` is a JSON file describing the dataset.
Every dataset MUST include this file with the following fields:

| **Field name** | **Definition** |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | REQUIRED. Name of the dataset. |
| BIDSVersion | REQUIRED. The version of the BIDS standard that was used. |
| HEDVersion | RECOMMENDED if HED tags are used. The version of the HED schema used to validate HED tags for study. |
| DatasetType | RECOMMENDED. The interpretation of the dataset. MUST be one of `"raw"` or `"derivative"`. For backwards compatibility, the default value is `"raw"`. |
| License | RECOMMENDED. The license for the dataset. The use of license name abbreviations is RECOMMENDED for specifying a license (see [Appendix II](./99-appendices/02-licenses.md)). The corresponding full license text MAY be specified in an additional `LICENSE` file. |
| Authors | OPTIONAL. List of individuals who contributed to the creation/curation of the dataset. |
| Acknowledgements | OPTIONAL. Text acknowledging contributions of individuals or institutions beyond those listed in Authors or Funding. |
| HowToAcknowledge | OPTIONAL. Text containing instructions on how researchers using this dataset should acknowledge the original authors. This field can also be used to define a publication that should be cited in publications that use the dataset. |
| Funding | OPTIONAL. List of sources of funding (grant numbers). |
| EthicsApprovals | OPTIONAL. List of ethics committee approvals of the research protocols and/or protocol identifiers. |
| ReferencesAndLinks | OPTIONAL. List of references to publication that contain information on the dataset, or links. |
| DatasetDOI | OPTIONAL. The Document Object Identifier of the dataset (not the corresponding paper). |
| **Key name** | **Requirement level** | **Data type** | **Description** |
| ------------------ | --------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | REQUIRED | [string][] | Name of the dataset. |
| BIDSVersion | REQUIRED | [string][] | The version of the BIDS standard that was used. |
| HEDVersion | RECOMMENDED | [string][] | If HED tags are used: The version of the HED schema used to validate HED tags for study. |
| DatasetType | RECOMMENDED | [string][] | The interpretation of the dataset. MUST be one of `"raw"` or `"derivative"`. For backwards compatibility, the default value is `"raw"`. |
| License | RECOMMENDED | [string][] | The license for the dataset. The use of license name abbreviations is RECOMMENDED for specifying a license (see [Appendix II](./99-appendices/02-licenses.md)). The corresponding full license text MAY be specified in an additional `LICENSE` file. |
| Authors | OPTIONAL | [array][] of [strings][] | List of individuals who contributed to the creation/curation of the dataset. |
| Acknowledgements | OPTIONAL | [string][] | Text acknowledging contributions of individuals or institutions beyond those listed in Authors or Funding. |
| HowToAcknowledge | OPTIONAL | [string][] | Text containing instructions on how researchers using this dataset should acknowledge the original authors. This field can also be used to define a publication that should be cited in publications that use the dataset. |
| Funding | OPTIONAL | [array][] of [strings][] | List of sources of funding (grant numbers). |
| EthicsApprovals | OPTIONAL | [array][] of [strings][] | List of ethics committee approvals of the research protocols and/or protocol identifiers. |
| ReferencesAndLinks | OPTIONAL | [array][] of [strings][] | List of references to publication that contain information on the dataset, or links. |
| DatasetDOI | OPTIONAL | [string][] | The Document Object Identifier of the dataset (not the corresponding paper). |

Example:

Expand Down Expand Up @@ -69,21 +69,21 @@ In addition to the keys for raw BIDS datasets,
derived BIDS datasets include the following REQUIRED and RECOMMENDED
`dataset_description.json` keys:

| **Key name** | **Description** |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GeneratedBy | REQUIRED. List of [objects][] with at least one element. |
| SourceDatasets | RECOMMENDED. A list of [objects][] specifying the locations and relevant attributes of all source datasets. Valid fields in each object include `URL`, `DOI`, and `Version`. |
| **Key name** | **Requirement level** | **Data type** | **Description** |
| -------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GeneratedBy | REQUIRED | [array][] of [objects][] | Used to specify provenance of the derived dataset. See table below for contents of each object. |
| SourceDatasets | RECOMMENDED | [array][] of [objects][] | Used to specify the locations and relevant attributes of all source datasets. Valid keys in each object include `URL`, `DOI`, and `Version` with [string][] values. |

Each object in the `GeneratedBy` list includes the following REQUIRED, RECOMMENDED
and OPTIONAL keys:

| **Key name** | **Description** |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name | REQUIRED. Name of the pipeline or process that generated the outputs. Use `"Manual"` to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline. |
| Version | RECOMMENDED. Version of the pipeline. |
| Description | OPTIONAL. Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`. |
| CodeURL | OPTIONAL. URL where the code used to generate the derivatives may be found. |
| Container | OPTIONAL. [Object][] specifying the location and relevant attributes of software container image used to produce the derivative. Valid fields in this object include `Type`, `Tag` and `URI`. |
| **Key name** | **Requirement level** | **Data type** | **Description** |
| ------------ | --------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | REQUIRED | [string][] | Name of the pipeline or process that generated the outputs. Use `"Manual"` to indicate the derivatives were generated by hand, or adjusted manually after an initial run of an automated pipeline. |
| Version | RECOMMENDED | [string][] | Version of the pipeline. |
| Description | OPTIONAL | [string][] | Plain-text description of the pipeline or process that generated the outputs. RECOMMENDED if `Name` is `"Manual"`. |
| CodeURL | OPTIONAL | [string][] | URL where the code used to generate the derivatives may be found. |
| Container | OPTIONAL | [object][] | Used to specify the location and relevant attributes of software container image used to produce the derivative. Valid keys in this object include `Type`, `Tag` and `URI` with [string][] values. |

Example:

Expand Down Expand Up @@ -381,3 +381,6 @@ code organization of these scripts at the moment.

[objects]: https://www.json.org/json-en.html
[object]: https://www.json.org/json-en.html
[string]: https://www.w3schools.com/js/js_json_syntax.asp
[strings]: https://www.w3schools.com/js/js_json_syntax.asp
[array]: https://www.w3schools.com/js/js_json_arrays.asp
Loading