Skip to content

Commit

Permalink
Merge pull request #131 from VisLab/main
Browse files Browse the repository at this point in the history 
Corrected links and other information in READMEs
  • Loading branch information
@VisLab
VisLab authored Dec 27, 2023
2 parents 1b5c53b + e6fb910 commit 29b3854
Show file tree
Hide file tree
Showing 5 changed files with 92 additions and 209 deletions.
96 changes: 50 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,27 +21,36 @@ particularly the [**How do you use HED?**](https://www.hed-resources.org/en/late
for information about how to get started or how to get involved in the HED community.

## Viewing HED schemas

The **HED schemas** are hierarchically-structured vocabularies for annotating data.
The HED ecosystem includes a **standard schema** containing the basic vocabulary
needed for annotation of experimental data as well as specialized **library schemas** for
the additional field-specific terms needed to complete an annotation.


All released and prereleased versions of the HED schemas can be viewed the [**HED Schema Browser**](https://www.hedtags.org/display_hed.html).

The following table summarizes the current versions of the HED schemas.

| Schema | Latest<br/>version| Description | Prerelease<br/>version | DOI |
| ------ | --------------- | ------- | ------------------------- | ---- |
| [**standard**](./standard_schema) | 8.2.0 | Basic vocabulary for annotating data. | 8.3.0 | 10.5281/zenodo.7876037 |
| [**score**](library_schemas/score) | 1.1.0 | SCORE standard vocabulary for <br/>clinical neurological annotation<br/>(See [**Score docs**](https://hed-schemas.readthedocs.io/en/latest/hed_score_library.html).) |1.1.1 | 10.5281/zenodo.7897596 |
| [**score**](library_schemas/score) | 1.1.0 | SCORE standard vocabulary for <br/>clinical neurological annotation<br/>(See [**Score docs**](https://hed-schemas.readthedocs.io/en/latest/hed_score_schema.html.) |1.1.1 | 10.5281/zenodo.7897596 |
| [**lisa**](library_schemas/lisa) | | LISA linguistic stimuli annotation vocabulary. | 0.0.1 | |
| [**testlib**](library_schemas/testlib) | 2.0.0 | A copy of the HED standard vocabulary<br/> for testing. <br/> (May not be stable.) | 2.0.1 | |

## HED formats
HED schemas are stored in two formats: `.mediawiki` and `.xml`.
The `.mediawiki` Markdown format is used by schema developers to create and
maintain HED schemas. For each schema, the `.mediawiki` versions are
stored in the respective `.mediawiki` directory for the schema.

## HED revision process
The `.mediawiki` format is converted to an equivalent
`.xml` format for use with all HED analysis and validation tools.
For each schema, the `.xml` versions are
stored in the respective `.xml` directory for the schema.
An online schema conversion tool is available at as part of the
[**HED online tools**](https://hedtools.org/hed/schemas).

## HED revision process
If you want to suggest a new feature or a change to the standard HED schema or one
of the HED library schemas, just post an [**issue**](https://github.com/hed-standard/hed-schemas/issues)
to this repository, and it will find its way to the right place.
Expand All @@ -53,64 +62,58 @@ schema that is located in the `prerelease` subdirectory.
Upon final review, the new HED schema is released and moved to the
`hedxml` directory of the respective library schema.

For a more complete view of the process see the [**HED schema development guide**](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html).

For a more complete view of the process see the [**HED schema developer's guide**](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.htmlhttps://www.hed-resources.org/en/latest/HedSchemaDevelopersGuide.html).

## Tools to help with HED annotations

The GUI tool [**CTagger**](https://github.com/hed-standard/CTagger) is available to help users with the annotation process.
The GUI tool [**CTagger**](https://www.hed-resources.org/en/latest/CTaggerGuiTaggingTool.html) is available to help users with the annotation process.
CTagger can be used as a standalone application or can be called from EEGLAB via the
[**hedtools plug-in**](https://github.com/hed-standard/hed-matlab) to annotate an EEGLAB dataset/STUDY directly.
[**hedtools plug-in**](https://www.hed-resources.org/en/latest/HedMatlabTools.html) to annotate an EEGLAB dataset/STUDY directly.
Please refer to the linked repositories for more documentation on how to start HED-tagging using CTagger.


## Web-based HED tools

The current online HED tools include an online validator of spreadsheets (Excel or tsv)
containing HED tags.
Schema tools are available for validating and converting HED schema specifications between `.mediawiki` and `.xml` formats.

The released version of the web-based HED tools is located at [**https://hedtools.ucsd.edu/hed**](https://hedtools.ucsd.edu/hed).
The released version of the web-based HED tools is located at [**https://hedtools.org**](https://hedtools.org).
The development version of the tools, used to test features before release,
is located at [**https://hedtools.ucsd.edu/hed_dev**](https://hedtools.ucsd.edu/hed_dev).

is located at [**https://hedtools.org/hed_dev**](https://hedtools.org/hed_dev).

## HED semantic versioning

HED schema use the following rules for
HED schemas use the following rules for
changing the *major.minor.patch* semantic version.
These rules are based on the assumption that the [**HED tag**](https://hed-specification.readthedocs.io/en/latest/02_Terminology.html#hed-tag)
short form will not require data annotators to retag their data for patch-level or minor-version changes of the schema.
That is, a dataset tagged using schema version *X.Y.Z* will also validate for *X.Y+.Z+*.
However, the reverse is not necessarily true.
These rules are based on the assumption that annotators using the [**HED tag**](https://hed-specification.readthedocs.io/en/latest/02_Terminology.html#hed-tag)
short form will not have to retag their data for patch-level or minor-version changes of the schema.
That is, a dataset tagged using schema version *X.Y.Z* will also validate for *X.Y+.Z+*.
In addition, validation errors might occur
during for patch-level or minor-version changes for changes or
corrections in tag values or units.

Here is a summary of the types of changes that correspond to different
levels of changes in the semantic version:

| Change | Semantic-level |
|-----------------------------------------------------|----------------|
| Major addition to HED functionality | Major |
| Tag deleted from schema. | Major |
| Unit or unit class removed from node. | Major |
| Node attribute value changed (excluding below) | Major |
| Inherited attribute change | Minor |
| New property added to schema | Minor |
| New value class added to schema | Minor |
| New unit modifier added to schema | Minor |
| New tag added to the schema. | Minor |
| New attribute added to schema. | Minor |
| New unit class or unit added to schema. | Minor |
| New unit class added to node. | Minor |
| New value class added to node. | Minor |
| Node moved in schema without change in meaning. | Minor |
| Revision of description field in schema. | Patch |
| Correction of suggestedTag or relatedTag. | Patch |


**Note:** It is an official policy that once in a schema, a node will not be removed.
| Change | Semantic-level |
|-------------------------------------------------|----------------|
| Major addition to HED functionality | Major |
| Tag deleted from schema. | Major |
| Unit or unit class removed from node. | Major |
| Node attribute value changed | Minor |
| Inherited attribute change | Minor |
| New property added to schema | Minor |
| New value class added to schema | Minor |
| New unit modifier added to schema | Minor |
| New tag added to the schema. | Minor |
| New attribute added to schema. | Minor |
| New unit class or unit added to schema. | Minor |
| New unit class added to node. | Minor |
| New value class added to node. | Minor |
| Node moved in schema without change in meaning. | Minor |
| Revision of description field in schema. | Patch |
| Correction of suggestedTag or relatedTag. | Patch |


**Note:** It is an official policy that once in a schema, a node will not be removed without
a major schema version change.
If a node becomes out-of-date, a `deprecated` attribute will be added to the tag in the schema.
Suggested replacement tags should be included in the node description.
A suggested replacement should be added to the tag patch table.
Expand Down Expand Up @@ -146,9 +149,10 @@ and events with temporal extent.
> [**Stable link for the latest version of the HED standard schema**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HEDLatest.xml).
The full HED specification is available at the
[**HED specification**](https://hed-specification.readthedocs.io/en/latest/index.html) website.

### Mapping HED tags to defined terms in existing ontologies

The following working document describes the origin of the descriptions associated with individual nodes in the HED hierarchy. Many terms appear in the NCIT ontology (National Cancer Institute Thesaurus OBO edition).

> [**Google doc with mapping of HED-3G term descriptions to existing ontology terms**](https://drive.google.com/file/d/13y17OwwNBlHdhB7hguSmOBdxn0Uk4hsI/view?usp=sharing)
### HED ontologies
Efforts are underway to map HED to a formal ontology in order to leverage links to
other terminologies and vocabularies. The development effort is housed on the
[**hed-ontology**](https://github.com/hed-standard/hed-ontology) GitHub repository.
2 changes: 1 addition & 1 deletion library_schemas/lisa/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,4 @@ LISA is a Hierarchical Event Descriptors Library Schema for Linguistic Stimuli A

LISA allows for annotation of language stimuli on different levels through the orthogonal definition of Language-items and Language-item-properties. Full sentences can be annotated with sentence-level characteristics, while the individual words in the sentence can be associated with word-level characteristics, and so on. Annotation possibilities are extensive and cover characteristics found across languages to allow for between language comparisons.

The current prerelease of the schema is primarily centered around written language and current development focusses on adding grammatical aspect characteristics and spoken word characteristics into the vocabulary.
The current prerelease of the schema is primarily centered around written language and current development focuses on adding grammatical aspect characteristics and spoken word characteristics into the vocabulary.
26 changes: 22 additions & 4 deletions library_schemas/score/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7897596.svg)](https://doi.org/10.5281/zenodo.7897596)

# SCORE HED Library Schema
# HED SCORE Library Schema

This schema is a Hierarchical Event Descriptors (HED) Library Schema implementation of Standardized Computer-based Organized Reporting of EEG (SCORE)[1,2] for describing events occurring during neuroimaging time series recordings.
The HED-SCORE library schema allows neurologists, neurophysiologists, and brain researchers to annotate electrophysiology recordings using terms from an internationally accepted set of defined terms (SCORE) compatible with the HED framework.
The resulting annotations are understandable to clinicians and directly usable in computer analysis.

Future extensions may be implemented in the HED-SCORE library schema.
For more information see https://hed-schema-library.readthedocs.io/en/latest/index.html.
For more information see the [**hed-schemas docs**](https://hed-schemas.readthedocs.io/en/latest/).

The Standardized Computer-based Organized Reporting of EEG (SCORE) is a standard terminology for scalp EEG data assessment designed for use in clinical practice that may also be used for research purposes.
The SCORE standard defines terms for describing phenomena observed in scalp EEG data. It is also potentially applicable (with some suitable extensions) to EEG recorded in critical care and neonatal settings.
Expand All @@ -17,5 +17,23 @@ A second revised and extended version of SCORE achieved international consensus.
### Viewing the SCORE HED Library Schema
> The HED SCORE library can be viewed using the [**HED Schema Browser**](https://www.hedtags.org/display_hed.html).
[1] Beniczky, Sandor, et al. "Standardized computer based organized reporting of EEG: SCORE." Epilepsia 54.6 (2013).
[2] Beniczky, Sandor, et al. "Standardized computer based organized reporting of EEG: SCORE second version." Clinical Neurophysiology 128.11 (2017).
### References

> [1] Pal Attia, T. et al. (2023 preprint).
> *Hierarchical Event Descriptor library schema for EEG data annotation*
> [https://arxiv.org/abs/2310.15173](https://arxiv.org/abs/2310.15173).
> [2] Beniczky, S, et al. (2013).
> *Standardized computer based organized reporting of EEG: SCORE.*
> Epilepsia 54.6 (2013).
> [3] Beniczky, S., et al. (2017).
> *Standardized computer based organized reporting of EEG: SCORE second version.*
> Clinical Neurophysiology 128.11 (2017).
## Stable links for HED SCORE

> [**Stable directory link for schema lookup**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/score/hedxml)
> [**Stable link for latest version**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedxml/HED_score_Latest.xml)
Loading

0 comments on commit 29b3854

Please sign in to comment.