Skip to content
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

[FIX]: Hierarchical Event Descriptors (HED) page update #1592

Closed
wants to merge 19 commits into from
Closed

[FIX]: Hierarchical Event Descriptors (HED) page update #1592

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
9666777
Update hed.md
tpatpa Aug 23, 2023
faf93b3
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Aug 23, 2023
abae3c7
Update hed.md
tpatpa Aug 23, 2023
1f08baf
Update hed.md
tpatpa Aug 30, 2023
f2a8d73
Update hed.md
tpatpa Aug 30, 2023
e88abc4
Update hed.md
tpatpa Aug 30, 2023
6a4373c
Update hed.md
tpatpa Aug 30, 2023
51f7867
Update hed.md
tpatpa Aug 31, 2023
3fc2e75
Update hed.md
tpatpa Aug 31, 2023
f4b937b
Merge branch 'master' into master
tpatpa Sep 1, 2023
a175947
Revert "Merge branch 'master' into master"
tpatpa Sep 1, 2023
0da7b32
Red/Blue square to match across files
tpatpa Sep 1, 2023
fabfe84
Update hed.md
tpatpa Sep 1, 2023
5c0190c
Update hed.md
tpatpa Sep 5, 2023
6b5e1ca
Update src/appendices/hed.md
tpatpa Sep 11, 2023
9665840
Update src/appendices/hed.md
tpatpa Sep 11, 2023
d73e9a3
Update hed.md
tpatpa Sep 11, 2023
dc94733
Update hed.md
tpatpa Sep 11, 2023
5208fb2
Merge branch 'master' into master
effigies Sep 29, 2023
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
127 changes: 85 additions & 42 deletions src/appendices/hed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,19 @@ A HED annotation consists of terms selected from a controlled
hierarchical vocabulary (the HED schema).
Individual terms are comma-separated and may be grouped using parentheses to indicate
association.
See [https://www.hedtags.org/display_hed.html](https://www.hedtags.org/display_hed.html)
See the [HED Schema Browser](https://www.hedtags.org/display_hed.html)
to view the HED schema and the
[HED resources](https://www.hed-resources.org/en/latest/) site for additional information.

Starting with HED version 8.0.0, HED allows users to annotate using individual
terms or partial paths in the HED vocabulary (for example `Red` or `Visual-presentation`)
terms or partial paths in the HED vocabulary (for example, `Red` or `Visual-presentation`)
rather than the full paths in the HED hierarchy (
`Property/Sensory-property/Sensory-attribute/Visual-attribute/Color/CSS-color/Red-color/Red`
or
`Property/Sensory-property/Sensory-presentation/Visual-presentation`).

HED specific tools MUST treat the short (single term) and long (full path) HED tag forms interchangeably,
converting between the forms when necessary based on the HED schema.
converting between the forms, when necessary, based on the HED schema.
Examples of test datasets using the various forms can be found in
[hed-examples/datasets](https://github.com/hed-standard/hed-examples/tree/main/datasets)
on GitHub.
Expand All @@ -40,14 +40,14 @@ files in various places in the dataset hierarchy
Dataset curators MAY also include additional columns and define their
meanings in associated JSON sidecar files (`events.json`).

Example: An excerpt from an `events.tsv` file containing three columns
**Example:** An excerpt from an `events.tsv` file containing three columns
(`trial_type`, `response_time`, and `stim_file`) in addition to
the required `onset` and `duration` columns.

```Text
onset duration trial_type response_time stim_file
1.2 0.6 go 1.435 images/red_square.jpg
5.6 0.6 stop 1.739 images/blue_square.jpg
5.6 0.6 stop n/a images/blue_square.jpg
```

The `trial_type` column in the above example contains a limited number of distinct
Expand All @@ -66,13 +66,13 @@ The HED annotation for a value column must include a `#` placeholder,
which dedicated HED tools MUST replace by the actual column value when the annotations
are assembled for analysis.

Example: An accompanying `events.json` sidecar describing both categorical and
**Example:** An accompanying `events.json` sidecar describing both categorical and
value columns of the previous example.
tpatpa marked this conversation as resolved.
Show resolved Hide resolved
The `duration` column is also annotated as a value column.

```JSON
{
"Duration": {
"duration": {
"LongName": "Image duration",
"Description": "Duration of the image presentations",
"Units": "s",
Expand All @@ -82,12 +82,12 @@ The `duration` column is also annotated as a value column.
"LongName": "Event category",
"Description": "Indicator of type of action that is expected",
"Levels": {
"go": "A blue square is displayed to indicate starting",
"stop": "A red square is displayed to indicate stopping"
"go": "A red square is displayed to indicate starting",
"stop": "A blue square is displayed to indicate stopping"
},
"HED": {
"go": "Sensory-event, Visual-presentation, (Square, Blue)",
"stop": "Sensory-event, Visual-presentation, (Square, Red)"
"go": "Sensory-event, Visual-presentation, (Square, Red)",
"stop": "Sensory-event, Visual-presentation, (Square, Blue)"
}
},
"response_time": {
Expand All @@ -106,18 +106,20 @@ The `duration` column is also annotated as a value column.

Dedicated HED tools MUST assemble the HED annotation for each event (row) by concatenating the
annotations for each column, along with the annotation contained directly in a `HED` column
of that row as described in the next section.
of that row, as described in the next section.

Example: The fully assembled annotation for the first event in the above
**Example:** The fully assembled annotation for the first event in the above
`events.tsv` file with onset `1.2` (the first row) is:
tpatpa marked this conversation as resolved.
Show resolved Hide resolved

```Text
Duration/0.6 s, Sensory-event, Visual-presentation, (Square, Blue),
(Delay/1.435 ms, Agent-action, (Experiment-participant, (Press, Mouse-button))),
(Duration/0.6 s, Sensory-event, Visual-presentation,
((Square, Red), (Computer-screen, Center-of))),
(Delay/1.435 ms, Agent-action, (Experiment-participant,
(Press, Mouse-button))),
Pathname/images/red_square.jpg
```

## Annotation using the `HED` column
### Annotation using the `HED` column

Another tagging strategy is to annotate individual events directly by
including a `HED` column in the `events.tsv` file.
Expand All @@ -138,7 +140,7 @@ event annotations.

Annotations placed in sidecars are the RECOMMENDED way to annotate data using HED.
These annotations are preferred to those placed
directly in the `HED` column, because they are simpler, more compact,
directly in the `HED` column because they are simpler, more compact,
more easily edited, and less prone to inconsistencies.

## HED and the BIDS inheritance principle
Expand All @@ -162,41 +164,57 @@ The HED vocabulary is specified by a HED schema,
which delineates the allowed HED path strings.
The version of HED used in tagging a dataset should be provided in the `HEDVersion`
field of the `dataset_description.json` file located in the dataset root directory.
This allows for a proper validation of the HED annotations
(for example using the `bids-validator`).
This allows for properly validating the HED annotations
(for example, using the `bids-validator`).

Example: The following `dataset_description.json` file specifies that the
[`HED8.1.0.xml`](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.1.0.xml)
**Example:** The following `dataset_description.json` file specifies that the
[`HED8.2.0.xml`](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml)
file from the `standard_schema/hedxml` directory of the
[`hed-schemas`](https://github.com/hed-standard/hed-schemas)
repository on GitHub should be used to validate the study event annotations.

```JSON
{
"Name": "A great experiment",
"BIDSVersion": "1.7.0",
"HEDVersion": "8.1.0"
"BIDSVersion": "1.8.0",
"HEDVersion": "8.2.0"
}
```

If you omit the `HEDVersion` field from the dataset description file,
a warning will be generated and
any present HED information will be validated using the latest version of the HED schema.
This is bound to result in problems, and hence, it is strongly RECOMMENDED that the
`HEDVersion` field be included when using HED in a BIDS dataset.
The BIDS validator will generate an error if your dataset uses HED
and the `HEDVersion` field is missing from the dataset description file.
To avoid this, include a `HEDVersion` field in the `dataset_description.json`
if you are using HED annotations.

### Using HED library schemas

HED also allows you to use one or more specialized vocabularies along with or instead of
HED also allows you to use one or more specialized vocabulary along with or instead of
the standard vocabulary. These specialized vocabularies are developed by
communities of users and are available in the GitHub
[hed-schemas](https://github.com/hed-standard/hed-schemas) repository.
Library schema are specified in the form `<library-name<_>library-version>`.
tpatpa marked this conversation as resolved.
Show resolved Hide resolved
A library schema is specified in the form `<library-name<_>library-version>`.

#### Partnered library schemas

Partnered library schemas were introduced in HED specification version 3.2.0
and are supported by HED standard schema versions ≥ 8.2.0.
A partnered library schema is tied to a specific version of
the HED standard schema as specified in its header. A given library schema
version is either partnered or standalone.

**Note:** Whether a particular library schema version is partnered or
unpartnered is fixed when the library is released and cannot be changed.
For example,
[HED-SCORE version 1.0.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki)
is unpartnered, but [HED-SCORE version 1.1.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.1.0.mediawiki)
is partnered with standard schema version 8.2.0.

##### Unpartnered library schema example

Example: The following `dataset_description.json` file specifies that the
The following `dataset_description.json` file specifies that the
[HED8.1.0.xml](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.1.0.xml)
standard schema should be used along with the
SCORE library for clinical neurological annotation located at
standard schema should be used along with the HED-SCORE library schema
for clinical neurological annotation located at
[HED_score_1.0.0.xml](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedxml/HED_score_1.0.0.xml).

```JSON
Expand All @@ -206,22 +224,24 @@ SCORE library for clinical neurological annotation located at
"HEDVersion": ["8.1.0", "sc:score_1.0.0"]
}
```
The `sc:` is a user-chosen prefixes used to distinguish the sources
The `sc:` is a user-chosen prefix used to distinguish the sources
of the terms in the HED annotation.
The prefixes MUST be alphanumeric.
Any number of prefixed schemas may be used in addition to a non-prefixed one.

The following HED annotation from this dataset uses the `sc:` prefix with
`Photomyogenic-response` and `Wicket-spikes` because these terms are from the
SCORE library, while `Data-feature` is from the standard HED schema.
`Eye-blink-artifact` and `Seizure-PNES` because these terms are from the
HED-SCORE library schema, while `Data-feature` is from the standard HED schema.

```Text
Data-feature, sc:Photomyogenic-response, sc:Wicket-spikes
Data-feature, sc:Eye-blink-artifact, sc:Seizure-PNES
```

If only one schema is being used for annotation, the prefix can be omitted entirely.
The following `dataset_description.json` indicates that only the SCORE library version
0.0.1 will be used for HED annotation in this dataset.
##### Single unpartnered library schema example

If only one schema is used for annotation, the prefix can be omitted entirely.
The following `dataset_description.json` indicates that only the HED-SCORE library schema version
1.0.0 will be used for HED annotation in this dataset.
tpatpa marked this conversation as resolved.
Show resolved Hide resolved

```JSON
{
Expand All @@ -231,8 +251,31 @@ The following `dataset_description.json` indicates that only the SCORE library v
}
```

The corresponding notations in the dataset do not have a prefix:
The corresponding annotations in the dataset do not have a prefix:

```Text
Eye-blink-artifact, Seizure-PNES
```

##### Partnered library schema example

The following `dataset_description.json` file specifies that
the HED-SCORE library schema
[version 1.1.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.1.0.mediawiki) is used.
This particular library schema version is partnered with the standard schema version
[8.2.0](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml).

```JSON
{
"Name": "A great experiment",
"BIDSVersion": "1.8.0",
"HEDVersion": "score_1.1.0"
}
```
The corresponding annotations in the dataset use tags from the
HED-SCORE library schema (`Eye-blink-artifact` and `Seizure-PNES`) and from the standard HED (`Data-feature`)
as follows:

```Text
Photomyogenic-response, Wicket-spikes
Data-feature, Eye-blink-artifact, Seizure-PNES
```
15 changes: 6 additions & 9 deletions src/modality-specific-files/magnetoencephalography.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,20 +89,17 @@ which some installations impose to be run on raw data prior to analysis.
Such processing steps are needed for example because of active shielding software corrections
that have to be performed to before the MEG data can actually be exploited.

### Recording (i)EEG simultaneously with MEG
### Recording EEG simultaneously with MEG

Note that if (i)EEG is recorded with a separate amplifier,
Note that if EEG is recorded with a separate amplifier,
it SHOULD be stored separately under a new `/eeg` data type
(see the [EEG](electroencephalography.md) and
[iEEG](intracranial-electroencephalography.md) specifications).
(see [the EEG specification](electroencephalography.md)).

If however (i)EEG is recorded simultaneously **with the same MEG system**,
If however EEG is recorded simultaneously **with the same MEG system**,
it MAY be stored under the `/meg` data type.
In that case, it SHOULD have the same sampling frequency as MEG (see `SamplingFrequency` field below).
Furthermore, (i)EEG sensor coordinates MAY be recorded in an
[`electrodes.tsv`](electroencephalography.md#electrodes-description-_electrodestsv)
file using MEG-specific coordinate systems
(see [Coordinate System JSON](#coordinate-system-json-_coordsystemjson) below and
Furthermore, the EEG sensor coordinates SHOULD be specified using MEG-specific coordinate
systems (see [coordinates section](#coordinate-system-json-_coordsystemjson) below and
the [Coordinate Systems Appendix](../appendices/coordinate-systems.md)).

### Sidecar JSON (`*_meg.json`)
Expand Down
3 changes: 0 additions & 3 deletions src/schema/objects/columns.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,9 +37,6 @@ age:
display_name: Subject age
description: |
Numeric value in years (float or integer value).

It is recommended to tag participant ages that are 89 or higher as 89+,
for privacy purposes.
type: number
unit: year
cardiac:
Expand Down
4 changes: 2 additions & 2 deletions src/schema/objects/entities.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,7 +192,7 @@ part:
`part-real`/`part-imag` pairs of files.

Phase images MAY be in radians or in arbitrary units.
The sidecar JSON file MUST include the `"Units"` of the `phase` image.
The sidecar JSON file MUST include the units of the `phase` image.
The possible options are `"rad"` or `"arbitrary"`.

When there is only a magnitude image of a given type, the `part` entity MAY be
Expand Down Expand Up @@ -359,7 +359,7 @@ stain:
although the label may be different.

Descriptions of antibodies SHOULD also be indicated in the `"SamplePrimaryAntibodies"`
and/or `"SampleSecondaryAntibodies"` metadata fields, as appropriate.
and/or `"SampleSecondaryAntobodies"` metadata fields, as appropriate.
type: string
format: label
subject:
Expand Down
Loading