diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..f5dd98cc --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,30 @@ +# CHANGELOG for HED specification + +## Changes for HED specification 3.1.0 +This release is focused on corrections and clarifications in the specification document +and does not include any enhancements. + +* [**Clarification**] The inner tag group in a definition cannot be empty. +* [**Clarification**] The additional tags within an `Onset` or `Offset` group must be +enclosed in parentheses. Consequently, only one definition can anchor an event of temporal extent. +* [**Correction/Clarification**] The initial specification said that definitions could be +given anywhere. Our examples only put them in dummy entries in the sidecars. +Allowing definitions to be anywhere turned out to be burdensome for downstream analysis +tools. We have now restricted definitions so that they can only appear in dummy entries of sidecars. +* [**Clarification**] Chapter 3.2 was rewritten so that full specification details of tag +syntax were given and keyed to error codes in Appendix B. +* [**Clarification**] Error codes of Appendix B were modified to have more consistent form, +and some additional codes were added to account for requirements of the specification. +* [**Improvement**] Each error code in Appendix B was given its own markdown section so that +error messages in the validators could use the error code as a link into the specification +for more information about the cause of errors. +* [**Improvement**] A standardized set of validation test data keyed to the error codes +was added to the specification repository in the +[**error_tests**](https://github.com/hed-standard/hed-specification/tree/master/docs/source/_static/data/error_tests) directory. This test data will be validated by both the Python +and JavaScript validators in addition to their internal tests as part of the GitHub actions. +* [**Clarification**] All chapters of the specification were edited for clarity and correctness. + +## Initial release 3.0.0 Oct. 27, 2022. + +The specification version was set to 3.0.0 to designate the specification for HED-3G +corresponding to HED standard schema versions >= 8.0.0 \ No newline at end of file diff --git a/CHANGELOG_SPEC.md b/CHANGELOG_SPEC.md deleted file mode 100644 index 81c9b383..00000000 --- a/CHANGELOG_SPEC.md +++ /dev/null @@ -1,18 +0,0 @@ - -# CHANGELOG for HED specification - -The initial version of the HED specification was created and unofficially released in conjunction -with the first release of the HED schema vocabulary version 8.0.0 on Aug 8, 2021. -However, the versioning of the specification was informal, and minor changes were -made in the specification document as tool implementation proceeded. - -Starting on October 27, 2022, the HED Working Group decided to separate the versioning -of the HED specification document and the HED schema vocabulary. -The HED Working Group recognized that new features would be incorporated into the -HED infrastructure without the need to change the HED vocabulary. - -The first separated version of the HED specification document is HEDSpec 3.0.0 -recognizing correspondence between this version of the specification and the initial -release of the HED-3G infrastructure. - -## Initial release 3.0.0 Oct. 27, 2022. \ No newline at end of file diff --git a/HEDSchemaRevisions.md b/HEDSchemaRevisions.md deleted file mode 100644 index cb6532c1..00000000 --- a/HEDSchemaRevisions.md +++ /dev/null @@ -1,44 +0,0 @@ -(hed-schema-revisions-anchor)= -## HED schema revisions - -As modifications to the HED schema are proposed, they are entered into the -[PROPOSED](PROPOSED.md) document for discussion. -Approved changes and corrections are first made in a working version of the -schema that is located in the [prelease directory](https://github.com/hed-standard/hed-specification/tree/master/prelease) and can be viewed -using the following viewer: - -> [**Expandable html view of the prerelease HED schema**](https://www.hedtags.org/display_hed_prelease.html) - -Upon final review, the new HED schema is released and moved to the -[hedxml directory](https://github.com/hed-standard/hed-specification/tree/master/hedxml). - -### HED schema details -_HED schema_ is the structured vocabulary from which HED annotations base on. HED annotations consist of comma-separated path strings, -selected from the schema. In the newest versions of HED, -all individual nodes in the vocabulary are unique, so users can annotate -by simply giving the last node in the path string rather than the entire path -string: *Red* instead of *Attribute/Sensory/Sensory-property/Visual/Color/CSS-color/Red-color/Red*. - -This repository contains the HED schema specification, where discussions on schema terms and syntax are held via Github issue mechanism and where HED-supporting tools can find machine-readable format of the schema. The HED schema is available in MediaWiki and XML. - -The MediaWiki markdown format, stored in -[`hedwiki`](https://github.com/hed-standard/hed-specification/tree/master/hedwiki), -allows vocabulary developers to view and edit the vocabulary tree using a -human-readable markdown language available in Wikis and on GitHub repositories. -In addition, an expandable non-editable -[HTML viewer](http://www.hedtags.org/display_hed.html) is available -to help users explore the vocabulary. - -All analysis and validation tools operate on an XML translation of the vocabulary -markdown document, stored in [`hedxml`](https://github.com/hed-standard/hed-specification/tree/master/hedxml). - - -### Further documentation - -The documentation on this page refers specifically to the HED vocabulary and supporting tools. Additional documentation is available on: - -> [**HED organization website**](https://www.hedtags.org) - -All of the HED software is open-source and organized into various repositories on the HED standards organization website: - -> [**HED organization github repository**](https://github.com/hed-standard) diff --git a/README.md b/README.md index 05eea39e..b84530a3 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,18 @@ including information on the format and rules for HED vocabularies (schemas) as well as rules for how tools should treat HED-annotated data. -If you just -want to annotate your data, please visit the [**HED resources**](https://www.hed-resources.org) documentation website. +If you just +want to annotate your data, please visit the [**HED resources**](https://www.hed-resources.org/en/latest/index.html) documentation website. If you are a developer of a new HED vocabulary (schema) please see the -[**Schema development guide**](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html). +[Schema development guide](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html). The latest version of the HED specification is available at the [**HED specification**](https://hed-specification.readthedocs.io/en/latest/index.html). -The most current officially released version of the HED specification can be found at [HED specification (PDF)](`) +The official library schemas are now housed on the +[**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. + +The most current officially released version of the HED specification can be found at [**HED specification (PDF)**](`) ## About HED HED (Hierarchical Event Descriptors) is an evolving framework for the description and @@ -31,9 +34,9 @@ motion-capture, EKG, and audiovisual recording. The following white papers give an overview of HED and how it is used. -> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2021). +> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2022). > Building FAIR functionality: Annotating event-related imaging data using Hierarchical Event Descriptors (HED). -> Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics https://doi.org/10.1007/s12021-021-09537-4. +> Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics 20, pages463–481. > [https://link.springer.com/article/10.1007/s12021-021-09537-4](https://link.springer.com/article/10.1007/s12021-021-09537-4). > Robbins, K., Truong, D., Appelhoff, S., Delorme, A., & Makeig, S. (2021). @@ -48,9 +51,10 @@ The HED schema represents the allowed vocabulary for use in annotation. The HED specification document specifies how tools should implement and validate various features of HED. -| HED specification version | Release date | HED schema versions | -| ----------------- | -------------------------- | -------------------------- | -| HED Specification 3.0.0 | Oct 27, 2022 | >= HED 8.0.0 | +| Specification
Version | Release date | Schema
versions | Description | +| ---------- | ---------------- | -------------- | -------------- | +| 3.0.0 | Oct 27, 2022 | ≥ 8.0.0 | - First official release | +| 3.1.0 | Apr 5, 2023 | ≥ 8.0.0 | - Cleanup and clarification
- JSON unit tests keyed to errors. | The first official release of the HED specification, HED Specification 3.0.0, marked the separation of the versioning of the specification and the schema. diff --git a/docs/requirements.txt b/docs/requirements.txt index 828e26ab..f6d03171 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,25 +1,3 @@ -attrs>=21.4.0 -myst-parser>=0.17.2 -Pygments>=2.12.0 -click==8.1.3 -coverage==6.4.1 -defusedxml>=0.7.1 -et-xmlfile>=1.1.0 -Flask>=2.1.2 -Flask-WTF>=1.0.1 -inflect>=5.6.0 -itsdangerous>=2.1.2 -jdcal>=1.4.1 -Jinja2>=3.1.2 -MarkupSafe>=2.1.1 -portalocker>=2.4.0 -python-dateutil>=2.8.2 -pytz>=2022.1 -semantic_version>=2.10.0 -six>=1.16.0 -Sphinx>=4.5.0 -SphinxExtensions>=0.2.0 +Sphinx>=5.2.2 +myst-parser>=0.18.1 sphinx_rtd_theme>=1.0.0 -Werkzeug>=2.1.2 -WTForms>=3.0.1 -xlrd>=2.0.1 diff --git a/docs/source/01_Introduction.md b/docs/source/01_Introduction.md index 9e34fff5..5a69e002 100644 --- a/docs/source/01_Introduction.md +++ b/docs/source/01_Introduction.md @@ -1,38 +1,38 @@ # 1. Introduction to HED This document contains the specification for third generation HED or HED-3G. It is meant for the implementers and users of HED tools. Other tutorials and tagging -guides are available to researchers using HED to annotate their data. -This document (HEDSPEC 3.0.0) contains the specification for the first official release of HED-3G. -This specification applies to HED Schema versions HED 8.0.0-xxx and above. -**When the term HED is used in this document, -it refers to third generation (HED-3G) unless explicitly stated otherwise.** +guides are available to researchers using HED to annotate their data. +This specification applies to HED Schema versions > 8.0.0 and above. The aspects of HED that are described in this document are supported or will soon be supported by validators and other tools and are available for immediate use by annotators. The schema vocabulary can be viewed using an expandable -[schema viewer](https://www.hedtags.org/display_hed.html). +[**schema viewer**](https://www.hedtags.org/display_hed.html). All HED-related source and documentation repositories are housed on the HED-standard -organization GitHub site, [https://github.com/hed-standard](https://github.com/hed-standard), -which is maintained by the HED Working Group. HED development is open-source and -community-based. Also see the official HED website [https://www.hedtags.org](https://www.hedtags.org) +organization GitHub site, [**https://github.com/hed-standard**](https://github.com/hed-standard), +which is maintained by the HED Working Group. +HED development is open-source and community-based. +Also see the official HED website [**https://www.hedtags.org**](https://www.hedtags.org) for a list of additional resources. The HED Working Group invites those interested in HED to contribute to the development process. -Users are encouraged to use the *Issues* mechanism of the `hed-specification` -repository on the GitHub `hed-standard` working group website: -[https://github.com/hed-standard/hed-specification/issues](https://github.com/hed-standard/hed-specification/issues) -to ask for help or make suggestions. The HED discussion forum -[https://github.com/hed-standard/hed-specification/discussions](https://github.com/hed-standard/hed-specification/discussions) is maintained for in depth -discussions of HED issues and evolution. +Users are encouraged to use the +[**issues**](https://github.com/hed-standard/hed-specification/issues) forum +on the [**hed-specification**](https://github.com/hed-standard/hed-specification) +GitHub repository to report issues with this specification document. + +For requests for additional features and vocabulary enhancements of the HED schema use the +[**issues**](https://github.com/hed-standard/hed-schemas/issues) forum on the +[**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. Several other aspects of HED annotation are being planned, but their specification has not been fully determined. These aspects are not contained in this specification document, but rather are contained in ancillary working documents which are open for discussion. These ancillary specifications include the HED working document on -[spatial annotation](https://docs.google.com/document/u/0/d/1jpSASpWQwOKtan15iQeiYHVewvEeefcBUn1xipNH5-8/edit) +[**spatial annotation**](https://docs.google.com/document/u/0/d/1jpSASpWQwOKtan15iQeiYHVewvEeefcBUn1xipNH5-8/edit) and the HED working document on -[task annotation](https://docs.google.com/document/u/0/d/1eGRI_gkYutmwmAl524ezwkX7VwikrLTQa9t8PocQMlU/edit). +[**task annotation**](https://docs.google.com/document/u/0/d/1eGRI_gkYutmwmAl524ezwkX7VwikrLTQa9t8PocQMlU/edit). ## 1.1. Scope of HED @@ -61,32 +61,32 @@ including but not limited to EEG, MEG, iEEG, fMRI, eye-tracking, motion-capture, EKG, and audiovisual recording. HED annotations may be included in BIDS (Brain Imaging Data Structure) -datasets [https://bids.neuroimaging.io](https://bids.neuroimaging.io) as described in -[Chapter 6: Infrastructure](06_Infrastructure.md#6-infrastructure). +datasets [**https://bids.neuroimaging.io**](https://bids.neuroimaging.io) as described in +[**Chapter 6: Infrastructure and tools**](06_Infrastructure_and_tools.md). ## 1.2. Brief history of HED HED was originally proposed by Nima Bigdely-Shamlo in 2010 to support annotation in -[HeadIT](https://headit.ucsd.edu) an early public repository for EEG data hosted by the -Swartz Center for Computational Neuroscience, UCSD (Bigdely-Shamlo et al. 2013). -HED-1G was partially based on CogPO (Turner and Laird 2012). +[**HeadIT**](https://headit.ucsd.edu) an early public repository for EEG data hosted by the +Swartz Center for Computational Neuroscience, UCSD (Bigdely-Shamlo et al., 2013). +HED-1G was partially based on CogPO (Turner and Laird, 2012). Event annotation in HED-1G was organized around a single hierarchy whose root was the -*Time-Locked Event*. Users could extend the HED-1G hierarchy at its deepest (leaf) nodes. -First generation HED (HED-1G, versions < 5.0.0) attempted to describe events using a strictly +`Time-Locked Event`. Users could extend the HED-1G hierarchy at its deepest (leaf) nodes. +First generation HED (HED-1G, versions < 4.0.0) attempted to describe events using a strictly hierarchical vocabulary. HED-1G was oriented toward annotating stimuli and responses, but its lack of orthogonality in vocabulary design presented major difficulties. -If *Red/Triangle* and *Green/Triangle* are terms in a hierarchy, -one is also likely to need *Red/Square* and Green/Square* as well as other color and shape +If `Red/Triangle` and `Green/Triangle` are terms in a hierarchy, +one is also likely to need `Red/Square` and `Green/Square` as well as other color and shape combinations. -HED-2G (versions 5.0.0 - 7.x.x) introduced a more orthogonal vocabulary, +HED-2G (versions 4.0.0 - 7.x.x) introduced a more orthogonal vocabulary, meaning that independent terms were in different subtrees of the vocabulary tree. -Separating independent concepts such as shapes and colors into separate hierarchies, +Separating independent concepts, such as shapes and colors into separate hierarchies, eliminates an exponential vocabulary growth due to term duplication in different -branches of the hierarchy. +branches of the hierarchy. The HED-2G represents a **sub-tag** system. Parentheses were introduced so that terms could be grouped. Tools for validation and epoching based on HED tags were built, and large-scale @@ -112,21 +112,24 @@ user experience. ```` Following basic design principles, the HED Working Group redesigned the HED vocabulary tree to -be organized in a balanced hierarchy with a limited number of subcategories at each node. (See the -[expandable schema browser](https://www.hedtags.org/display_hed.html) to browser the vocabulary -and explore the overall organization. [Chapter2:Terminology](02_Terminology.md#2-hed-terminology) -defines some important HED tags and terminology used in HED.) +be organized in a balanced hierarchy with a limited number of subcategories at each node. +Use the expandable [**schema browser**](https://www.hedtags.org/display_hed.html) +to browser the vocabulary and explore the overall organization. +[**Chapter2:Terminology**](02_Terminology.md#2-hed-terminology) +defines some important HED tags and terminology used in HED. A major improvement in vocabulary design was the adoption of the requirement that individual nodes or terms in the HED vocabulary must be unique. This allows users to use individual node names (short form) rather than the full paths to the schema root during annotation, resulting in substantially simpler, more readable annotations. -To enable and regulate the extension process, the root HED-3G head schema specified here includes, -for the first time, *HED library schema* to extend the HED vocabulary to include terms and concepts -of importance to individual user communities -- for example researchers who design and perform +To enable and regulate the extension process, +*HED library schemas* were introduced to allow detailed annotation of terms +importance to individual user communities without complicating the standard schema. +For example, researchers who design and perform experiments to study brain and language, brain and music, or brain dynamics in natural or virtual -reality environments. The HED library schema concept may also be used to extend HED annotation +reality environments have specialized vocabulary requirements. +The HED library schema concept may also be used to extend HED annotation to encompass specialized vocabularies used in clinical research and practice. HED-3G also introduced a number of advanced tagging concepts that allow users to represent @@ -134,15 +137,17 @@ events with temporal duration, as well as annotations that represent experimenta ## 1.2. Goals of HED -An event is a process that unfolds over time representing something that happens. Events -are typically measured by noting sequences of time points (event markers) usually marking -specific transition points which could be thought of as moments of phase transition -in a dynamic process. HED annotation documents what happens at these event markers in order +An event is a process that unfolds over time and represents something that happens. +Events are typically measured by noting sequences of time points (event markers) marking +specific transition points. + +HED annotation documents what happens at these event markers in order to facilitate data analysis and interpretation. Commonly recorded event markers in electrophysiological data collection include the initiation, termination, or other -features of **sensory presentations** and **participant actions**. Other events may -be **unplanned environmental events** (for example, noise and vibration -from construction work unrelated to the experiment, or a laboratory device malfunction), +features of **sensory presentations** and **participant actions**. + +Other events may be **unplanned environmental events** such as noise and vibration +from construction work unrelated to the experiment, laboratory device malfunction, **changes in experiment control** parameters as well as **data features** and control **mishaps** that cause operation to fall outside of normal experiment parameters. The goals of HED are to provide a standardized annotation and supporting infrastructure. @@ -200,22 +205,26 @@ schema without having to re-implement the annotation tools. A well-specified and ## 1.4. Specification organization This specification is meant to provide guidelines for tool-builders as well as HED annotators. -[Chapter 2: Terminology](02_Terminology.md) reviews the basic terminology used in HED, and -[Chapter 3: Schema](03_Schema.md) outlines the rules for HED vocabularies. Basic and advanced -event models and their annotations are explained in [Chapter 4: Basic annotation](04_Basic_annotation.md) -and [Chapter 5: Advanced annotation](05_Advanced_annotation.md). -Discussions of how tags for local event codes are associated with event instances are deferred to -[Chapter 6: Infrastructure](06_Infrastructure.md#65-bids-support-in-hed). - -HED provides a mechanism for user communities to develop discipline-specific library vocabularies. -(See [Chapter 7: Library schema](05_Advanced_annotation.md) for details.) - -[Appendix A: Schema format](Appendix_A.md) provides a reference manual for the HED vocabulary format rules. -[Appendix B: HED errors](Appendix_B.md) gives a complete listing of HED error codes and their meanings. - -Other resources include a comprehensive list of [HED resources ](HedResources.md) resources and -a [HED-examples](https://hed-examples.readthedocs.io/en/latest/#) -that contains many tutorials and code examples. - -All HED source code and resources are open-source and staged in the HED Standards Organization Repository -[https://github.com/hed-standard](https://github.com/hed-standard). +[**Chapter 2: Terminology**](02_Terminology.md) reviews the basic terminology used in HED, and +[**Chapter 3: HED formats**](03_HED_formats.md) specifies the formats for HED vocabularies and annotations. +Basic and advanced event models and their annotations are explained in +[**Chapter 4: Basic annotation**](04_Basic_annotation.md) +and [**Chapter 5: Advanced annotation**](05_Advanced_annotation.md). +[**Chapter 6: Infrastructure and tools**](06_Infrastructure_and_tools.md) discussions how +tags should be handled by HED-compliant tools. +[**Chapter 7: Library schemas**](07_Library_schemas.md) discusses the basic +rules for library schema creation. + +[**Appendix A: Schema format**](Appendix_A.md) provides a reference manual for the HED schema format rules, and +[**Appendix B: HED errors**](Appendix_B.md) gives a complete listing of HED error codes and their meanings. +A common set of test cases for these errors is available +in [**error_tests**](https://github.com/hed-standard/hed-specification/tree/master/docs/source/_static/data/error_tests) directory of the +[**hed-specification**](https://github.com/hed-standard/hed-specification) GitHub repository. + +Other resources include a comprehensive list of +[**HED resources**](https://www.hed-resources.org) including additional documentation, +tutorials and code examples. + +All HED source code and resources are open-source and staged in +the HED Standards Organization GitHub repository +[**https://github.com/hed-standard**](https://github.com/hed-standard). diff --git a/docs/source/02_Terminology.md b/docs/source/02_Terminology.md index 7624646b..95db4920 100644 --- a/docs/source/02_Terminology.md +++ b/docs/source/02_Terminology.md @@ -1,7 +1,7 @@ # 2. HED terminology The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", -"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in +"RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)]. This specification uses a list of terms and abbreviations whose meaning is clarified here. @@ -89,9 +89,9 @@ A valid path along one branch of a HED vocabulary hierarchy. A valid long-form H is a slash-separated path following the schema tree hierarchy from its root to a term along some branch. Any suffix of a valid long-form HED tag is a valid short-form HED tag. No white space is allowed within terms themselves. For example, the long form of the -HED tag specifying an experiment participant is: *Property/Agent-property/Agent-task-role/Experiment-participant*. -Valid short-form tags are *Experiment-participant*, *Agent-task-role/Experiment-participant*, -and *Agent-property/Agent-task-role/Experiment-participant*. HED tools should treat +HED tag specifying an experiment participant is: `Property/Agent-property/Agent-task-role/Experiment-participant`. +Valid short-form tags are `Experiment-participant`, `Agent-task-role/Experiment-participant`, +and `Agent-property/Agent-task-role/Experiment-participant`. HED tools should treat long-form and short-form tags interchangeably. ## Indicator-variable [*] @@ -112,7 +112,7 @@ repositioning the recording sensors. ## Tag-group -One or more valid, comma-separated HED tags or enclosed in parentheses to indicate +One or more valid, comma-separated HED tags enclosed in parentheses to indicate that these tags belong together. Tag-groups may contain arbitrary nestings of other tags and tag-groups. @@ -124,8 +124,12 @@ sensory presentations as well as specified actions in response to presented situ ## Temporal scope -The time interval between events marking the beginning and end of something in the -experiment. The time between and including the onset and offset of an event. +The time interval between the start and end of an event process. +Often the start time is annotated with the `Onset` tag, +and the end time is annotated with the `Offset` tag. +Since in practical terms the time is measured in discrete samples, +the temporal scope includes the start time sample +but does not include the end time sample. ## Time-block [*] diff --git a/docs/source/03_HED_formats.md b/docs/source/03_HED_formats.md new file mode 100644 index 00000000..12559767 --- /dev/null +++ b/docs/source/03_HED_formats.md @@ -0,0 +1,1122 @@ +(3-hed-formats-anchor)= +# 3. HED formats + +This chapter describes the requirements and formats for HED schema and HED annotations. + +## 3.1. HED schema format + +A **HED schema** is a formal specification of a HED vocabulary and annotation format rules. +A HED schema vocabulary is organized hierarchically so that similar concepts and terms appear +close to one another in the organizational hierarchy. + +HED schema nodes **must** satisfy an "is-a" relationship with their parent nodes in the schema. +That is, if node *A* is an ancestor of node *B* in the schema, +then *B* is a type of *A*. +This relationship is fundamental to HED and permits search generality. +Searches for *A* are able to also return instances of *B*. + +A key requirement for third generation HED (versions >=8.0.0) is that all node names (tag terms) in +the HED schema (except for `#` placeholders) **must be unique**. + +Additional details about HED schema format can be found in appendix +[**A. Schema format details**](./Appendix_A.md) + +### 3.1.1. Official schema releases + +The HED ecosystem supports a standard base schema and additional discipline-specific +library schemas. +(See the [**expandable schema viewer**](https://www.hedtags.org/display_hed.html) +to explore existing schemas.) + +Releases of the HED standard base schema are stored in +[**standard_schema/hedxml**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema/hedxml) +directory of the [**hed-schemas**](https://github.com/hed-standard/hed-schemas) repository. + +Releases of a HED library schemas are stored in a subdirectory of +[**library_schemas**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas) +whose name is the library name. + +### 3.1.2. Schema layout overview + +Schemas can be specified in either `.mediawiki` or `.xml` format. +[**Online tools**](https://hedtools.ucsd.edu/hed/schema) +provide an easy way for users to validate schema and convert between formats. + +HED schema developers usually use `.mediawiki` format for more convenient editing, +display, and viewing on GitHub. +However, the stable links provided for tools to access and download the HED schema +are to the XML versions. +Both formats must be available and synchronized in the +[**hed/standard/hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. + +Regardless of the format, a valid HED schema must have the following sections in this order: + +````{Admonition} Required sections of a HED schema (in the required order): +| Section | Mediawiki format | XML format | +|------- | --------- | ---------- | +| Header line | `HED version="8.0.0"` | `` | +| Prologue | `'''Prologue'''` | ` ... ` | +| Schema start | `!# start schema` | `` ... | +| Schema end | `!# end schema` | `` | +| Unit classes | `'''Unit classes'''` | `` ... `` | +| Unit modifiers | `'''Unit modifiers'''` | `` ... `` | +| Value classes | `'''Value classes'''` | `` ... `` | +| Schema attributes | `'''Schema attributes'''` | `` ... `` | +| Properties | `'''Properties'''` | `` ... `` | +| Epilogue | `'''Epilogue'''` | `` ... `` | +| Ending line | `!# end hed` | `` | +```` + +The sections in the `.xml` version must always be terminated by closing `` tokens, +whereas the sections of the `.mediawiki` version, which is line-oriented, +are terminated when the next section begins (`#!`) or a top tag (`'''`) is encountered. + +The actual HED tag specifications (referred to in the discussion as nodes or tag terms) +appear in the `schema` section, +while the remaining sections specify additional information and behavior. +These additional sections are required, but are allowed to be empty. + +If any of the required sections of the schema are missing or out of order, +a [**SCHEMA_SECTION_MISSING**](./Appendix_B.md#schema_section_missing) error occurs. + +Each of the schema sections has "schema attributes", which are the attributes that may be assigned +to elements in a given section. +If a schema attribute is applied improperly to an element in a given section, +the [**SCHEMA_ATTRIBUTE_INVALID**](./Appendix_B.md#schema_attribute_invalid) error occurs. + +See [**Appendix A. Schema format details**](./Appendix_A.md) for additional details. + +#### 3.1.2.1. The header + +The schema header line specifies the version, which must satisfy semantic versioning. +See [**SCHEMA_VERSION_INVALID**](./Appendix_B.md#schema_version_invalid). + +If the schema is a library schema rather than the standard schema, the library name must be included. +Library names should be lowercase and may only contain alphabetic characters. +Library names must contain only alphabetic lowercase characters and should be short and descriptive. +See [**LIBRARY_NAME_INVALID**](./Appendix_B.md#library_name_invalid). + +A schema's library name or lack there of is used to locate the schema in the +HED schema repository located in the +[**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. + +The header line may optionally include an XSD namespace specification. +If the schema contains any additional unrecognized attributes, +[**SCHEMA_HEADER_INVALID**](./Appendix_B.md#schema_header_invalid) error occurs. + +#### 3.1.2.2. The prologue + +The prologue should contain a concise introduction to the schema and its purpose. +Together with [**the epilogue**](./03_HED_formats.md#3129-the-epilogue) section, +the contents are used by tools to provide information about the schema to the users. + +The prologue may only contain the following: letters, digits, blank, comma, newline, ++, -, :, ;, ., /, (, ), ?, *, %, $, @ or +a [**SCHEMA_CHARACTER_INVALID**](./Appendix_B.md#schema_character_invalid) error occurs. + + +#### 3.1.2.3. The schema section + +The schema section contains the actual vocabulary contents of the schema. +Each element in this section is a *node* element, which we will also call a *tag term*. +The location of the node element within the section specifies its relationship to other tag terms in the schema. + +A node element specifies a name, +node attributes, and an informative description of the tag term's meaning. +A node name may only contain alphanumeric characters, hyphen, and underscore. +An exception to this is the `#` character which is used to represent a placeholder +for a value to be provided during annotation. +See [**SCHEMA_CHARACTER_INVALID**](./Appendix_B.md#schema_character_invalid) and + +Each schema node element must be unique or a +[**SCHEMA_DUPLICATE_NODE**](./Appendix_B.md#schema_duplicate_node) error is generated. + + +#### 3.1.2.4. Unit classes and units + +The unit classes are attributes that modify the `#` schema placeholder nodes. +The unit class definition section specifies the allowed unit classes for the schema +as well as the associated units that can be used with tags that take values. + +Only the singular version of each unit is explicitly specified, +but the corresponding plurals of the explicitly mentioned +singular version are also allowed (e.g., `feet` is allowed in addition to `foot`). +HED uses a `pluralize` function available in both Python and Javascript to check validity. + +Units may be in one of four forms as designated by their unit type attributes: + +| Unit type | Unit type attributes | +| --------- | ---------- | +| SI unit | only `SIUnit` | +| SI unit symbol | both `SIUnit` and `unitSymbol` | +| unit that is not an SI unit | no unit type attribute | +| unit symbol is not an SI unit | only `unitSymbol` | + +Most units appear after the value in annotations. However, certain units such as `$` +appear before their corresponding values. +These units have the `unitPrefix` attribute. + +If a unit class, `SIUnit`, or `unitPrefix` attribute appears in a +section other than the unit class definition section of the schema, +a [**SCHEMA_ATTRIBUTE_INVALID**](./Appendix_B.md#schema_attribute_invalid) error occurs. +See appendix [**A.1.1. Unit classes and units**](./Appendix_A.md#a11-unit-classes-and-units) +for additional details and a listing. + +**Units are not case-sensitive, but unit symbols maintain their case.** + +#### 3.1.2.5. Unit modifiers + +The unit modifier definition section lists the SI unit multiples and submultiples +that are allowed to be prepended to units that have the `SIUnit` schema attribute. + +Unit modifiers can only be used with SI units and SI unit symbols. +SI unit modifiers used with ordinary SI units have the `SIUnitModifier` attribute, +while unit modifiers used with SI unit symbols have the `SIUnitSymbolModifier` attribute. + +If a `SIUnitModifier`, or `SIUNitSymbolModifier` attribute appears in a +section other than `unit modifier section of the schema, +a [**SCHEMA_ATTRIBUTE_INVALID**](./Appendix_B.md#schema_attribute_invalid) error occurs. + +**Unit modifiers are case-sensitive.** + +See appendix [**A.1.2. Unit modifiers**](./Appendix_A.md#a12-unit-modifiers) +for additional details and a listing of values for the standard schema. + +#### 3.1.2.6. Value classes + +The value class definition section specifies rules for +the values that are substituted for placeholders (`#`). +Examples are special characters that are allowed for numeric values +or dates. Placeholders that have no `valueClass` attributes, are assumed to take `textClass` values. + +See appendix [**A.1.3. Value classes**](./Appendix_A.md#a13-value-classes) +for additional details and a listing of values for the standard schema. + +#### 3.1.2.7. Schema attributes + +The schema attribute definition section lists the schema attributes that may be applied to +schema elements in other sections of the schema (except for the properties section). + +The specification of which type of schema elements a particular schema attribute may apply +to is specified by its schema properties. +If a schema attribute appears in a section contradicted by its properties, +a [**SCHEMA_ATTRIBUTE_INVALID**](./Appendix_B.md#schema_attribute_invalid) error occurs. + +See appendices [**A.1.4. Schema attributes**](./Appendix_A.md#a14-schema-attributes) +and [**A.1.5. Schema properties**](./Appendix_A.md#a15-schema-properties) +for additional details and a listing for the standard schema. + +#### 3.1.2.8. Schema properties + +The schema properties section lists the allowed properties of the schema attributes. +These properties help tools validate certain requirements directly based +on the HED schema rather than on a hard-coded implementation. + +There are two types of properties: **form type** and **section type** properties. +The `boolProperty` is a form type property indicating that a schema attribute +does not take a value. +Rather, its presence indicates true and absence indicate false. + +The *section* type properties indicate the sections in which a schema attribute may appear. +The section properties include `unitClassProperty`, `unitModifierProperty`, +`unitProperty`, and `valueClassProperty`. +Schema attributes without any section properties are assumed to apply to node elements. + +A schema attribute may have multiple section properties, +indicating that the attribute may appear as an attribute in multiple sections of the schema. + +See [**A.1.4 Schema attributes**](./Appendix_A.md#a14-schema-attributes) and +[**A.1.5. Schema properties**](./Appendix_A.md#a15-schema-properties) +for information and a listing of schema attributes and their respective properties. + +#### 3.1.2.9. The epilogue + +The epilogue should give license information, acknowledgments, and references. + +The epilogue may only contain the following: letters, digits, blank, comma, newline, ++, -, :, ;, ., /, (, ), ?, *, %, $, @ or +a [**SCHEMA_CHARACTER_INVALID**](./Appendix_B.md#schema_character_invalid) error occurs. + + +### 3.1.3. Naming conventions + +The different parts of the HED schema have different rules +for the characters and the names that are allowed. + +UTF-8 characters are not supported. + + +#### 3.1.3.1. Node elements + +Schema designers and users that extend HED schema or develop library +schema will be mainly concerned with nodes (tag terms) found in the schema section. +The names of these elements must conform to the rules for +[`nameClass`](./Appendix_A.md#a13-value-classes). + +Other conventions and requirements for the contents of schema node elements +are as follows: + + +````{admonition} Naming conventions for nodes (tag terms) in HED schema. +:class: tip +1. By convention, the first letter of a schema node (tag term) should be capitalized with the remainder lower case. +2. Schema node names consisting of multiple words may not contain blanks and should be hyphenated. +3. Schema descriptions should be concise sentences, possibly with clarifying examples. +4. Schema descriptions may include characters allowed by `textClass` as well as commas. +They may not contain square brackets, curly braces, quotes, or other characters. +```` + +#### 3.1.3.2. Epilogue and prologue +The epilogue and prologue section text must conform to the rules for +[`textClass`](./Appendix_A.md#a13-value-classes). +The section text may have new lines, which are preserved. + +#### 3.1.3.3. Naming in other blocks + +The names of elements corresponding to schema attributes, schema properties, +unit classes, and value classes should start with a lower case letter, +with the remainder in camel case. + +Units and unit modifiers follow the naming conventions of the units they represent. + +Case is preserved for unit modifiers, as uppercase and lowercase versions often have distinct meanings. The case for unit symbols is also maintained. + + +### 3.1.4. Mediawiki schema format + +[**Mediawiki**](https://www.mediawiki.org/wiki/Cheatsheet) is a markdown-like format that was +selected as the HED schema editing format because of its flexibility +and ability to represent nested or hierarchical relationships. + +The format is line-oriented, so each schema entry should be on a single line. + +The schema must follow the layout described in the previous section. +All sections are required, although they may be empty. + +Top nodes in the schema are enclosed by pairs of three single quotes (`'''`). +The levels of other nodes are designated by the number of asterisks (`*`) at the beginning of the respective defining lines. +Each term is separated from its level-indicating asterisks by a single space. + +Descriptions, which are enclosed in square brackets (`[ ]`), +indicate the meaning of the item they modify. +The descriptions are displayed to users by schema browsers and other tools, +so every effort should be made to make them informative and clear. + +Attributes are enclosed with curly braces (`{ }`). +These attributes provide additional rules about how the item and +modifying values should be used and handled by tools. + +If an attribute or property is referenced in the schema, +it must be defined in the appropriate definition section of the schema, +or schema processing tools will generate a [**SCHEMA_ATTRIBUTE_INVALID**](./Appendix_B.md#schema_attribute_invalid) error. + +Allowed HED node attributes include unit class and value class values as well as +HED schema attributes that do not have one of the following modifiers: +`unitClassProperty`, `unitModifierProperty`, `unitProperty`, or `valueClassProperty`. +Note: schema attributes having the `elementProperty` may apply anywhere in the +schema, including the schema header, +schema attributes having the `nodeProperty` may only apply to node elements. + + + +HED schema attributes that have the `boolProperty` appear with just their name +in the schema element they are modifying. +The presence of such an attribute indicates that it is true or present. + +HED schema attributes that do not have the `boolProperty` are specified in the form of a +`name=value` pair. +If multiple values of a particular attribute are applicable, +they should be specified as name-value pairs separated by commas within the curly braces. + +The following example shows a simple HED schema in `.mediawiki` format. + +````{admonition} **Example:** Example HED schema in .mediawiki format. + +```tid +HED version="8.0.0" + +'''Prologue''' +This prologue introduces the schema. + +!# start schema +'''Event''' [Something that happens at a given place and time.] +* Sensory-event {suggestedTag=Task-event-role,suggestedTag=Sensory-presentation}[Something perceivable by an agent.] + . . . +'''Property'''{extensionAllowed}[A characteristic.] +* Informational-property [A quality pertaining to information.] +** Label [A string of 20 or fewer characters.] +*** # {takesValue} +!# end schema + +'''Unit classes''' [Unit classes and units for the nodes.] + . . . +'''Unit modifiers''' [Unit multiples and submultiples.] + . . . +'''Value classes''' [Rules for the values provided by users.] + . . . +'''Schema attributes''' [Allowed node attributes.] +* extensionAllowed {boolProperty}[Attribute indicating that users can add child nodes.] +* suggestedTag [Attribute indicating another tag that is often associated with this tag.] +* takesValue {boolProperty}[Attribute indicating a placeholder to be replaced by a user-defined value.] + . . . +'''Properties''' [Properties of the schema attributes.] +* boolProperty [Indicates a schema attribute represents a boolean.] + . . . +'''Epilogue''' +An optional section that is the place for notes and is ignored in HED processing. + +!# end hed +``` + +```` + + +In the above example, `Property` in the `schema` section is a top node because it appears +enclosed by three single quotes, while `Informational-property` is a first-level node +because its defining line begins with a single asterisk (`*`). + +`Sensory-event` in the `schema` section has a `suggestedTag` attribute (shown in curly braces). +Similarly, `Property` has an `extensionAllowed` attribute, and the `#` placeholder has a `takesValue` attribute. +The `schema attributes` section must include definitions of `suggestedTag,` +`extensionAllowed` and `takesValue` or the schema will not validate. + +The definition of the `takesValue` attribute has `boolProperty`, +so a definition of `boolProperty` must be included in the `Properties` section +or the schema will not validate. + +Everything after each HED node (tag term) must be enclosed by `` markup elements. +The contents within these markup elements include the description and attributes. + +Within the HED schema a `#` node indicates that the user must supply a value +consistent with the unit and value class attributes of the `#` node during annotation. +Lines with hashtag (`#`) placeholders should have +everything after the asterisks, including the `#` placeholder, enclosed by `` markup elements. + + +Additional details and rules can be found in appendix +[**A.2 Mediawiki file format**](./Appendix_A.md#a2-mediawiki-file-format) + +### 3.1.5. XML schema format + +The `.xml` format directly mirrors the order and information in the `.mediawiki` version of the schema. + +The `` elements of the schema represent the HED tags (tag terms), +with remaining schema elements specifying additional information and properties. + +Each `` element must have a `` child element corresponding to the HED tag term +that it specifies. + +A `` element should also have a `` child element whose content +corresponds to the text that appears in square brackets (`[ ]`) in the `.mediawiki` version. + +The schema attributes, which appear as `name` values or `name-value` pairs enclosed in +curly braces (`{ }`) in the `.mediawiki` file, are translated into `` child elements +of `` in the `.xml`. These `` elements always have a `` element child +and also have a `` element if the corresponding schema attribute does not have `boolProperty`. + +The following is a translation of the `.mediawiki` example from the previous section in the HEDXML format. + +````{admonition} **Example:** XML version of the example schema in the previous section. + +```xml + + + This prologue introduces the schema. + + + Event + Something that happens at a given place and time. + + Sensory-event + Something perceivable by an agent. + + suggestedTag + Task-event-role + + + + . . . + + Property + A characteristic of some entity. + + extensionAllowed + + + Informational-property + A quality pertaining to information. + + Label + A string of less than 20. + + # + + takesValue + + + + + + + + + + + + extensionAllowed + Attribute indicating that users can add child nodes. + + boolProperty + + + + suggestedTag + Attribute indicating another tag that is often associated with this tag. + + + takesValue + Attribute indicating a placeholder to be replaced by a user-defined value. + + boolProperty + + + + + + boolProperty + Attribute indicating a placeholder to be replaced by a user-defined value. + + + This epilogue is a place for notes and is ignored in HED processing. + +``` +```` + + +Additional details and rules can be found in appendix +[**A.3 XML file format**](./Appendix_A.md#a3-xml-file-format) + +## 3.2. HED annotation format + +**HED annotations** are comma-separated strings of HED tags +drawn from a HED schema vocabulary. +HED validators and other tools use the information encoded in the relevant schema when +performing validation and other processing of HED annotations. + +Users must provide the version of the HED schema they are using when creating an annotation. + +### 3.2.1. Vocabulary organization + +HED (Hierarchical Event Descriptors) are nodes (tag terms) organized hierarchically under their +respective root or **top nodes**. +In HED versions >= 8.0.0 these top nodes are: +`Event`, `Agent`, `Action`, `Item`, `Property`, and `Relation`. +Each top node and its subtree represent distinct **is-a** relationships +for the vocabulary schema. + +The `Event` subtree tags indicate the general event category, such as whether it +is a sensory event, an agent action, a data feature, or an event indicating experiment control or structure. + +The HED annotations describing each event may be assembled from a +number of sources during processing and the annotations associated with a single event +marker may represent multiple events. + +Many analysis tools use the `Event` tags as a primary means of +segregating, epoching, and processing the data. +Ideally, tags from the `Event` subtree should appear at the top level of the +HED annotation describing an event to facilitate analysis. + +The `Agent` subtree tags indicate the types of agents (e.g., persons, animals, avatars) +that take an active role or produce a specified effect. An `Agent` tag should be +grouped with property tags that provide information about the agent, such as +whether the agent is an experiment participant. + +The `Action` subtree tags indicate actions performed by agents. Generally these are +grouped in a triple (`A`, (`Action`, `B`)) which is interpreted as `A` does `Action` on `B`. +If the action does not have a target, it should be annotated (`A`, (`Action`)), meaning +`A` does `Action`. + +The `Item` subtree tags represent things with (actual or virtual) physical existence +such as objects, sounds, or language. + +Descriptive tags are organized in the `Property` subtree. These descriptive +tags should always be grouped with the tags they describe using parentheses. + +Binary relations are in the `Relation` subtree. Like items from the `Action` subtree, +these should be annotated using (`A`, (`Relation`, `B`)). + + +### 3.2.2. Tag forms + +A **HED tag** is a term in the HED vocabulary identified by a path consisting of the +individual node names from some branch of the HED schema hierarchy +separated by forward slashes (`/`). + +Valid HED tags do not have leading or trailing forward slashes (`/`). +A HED tag path may also not have consecutive forward slashes. + +An important requirement of third generation HED (versions >= 8.0.0) +is that the node names in the HED schema **must be unique**. +As a consequence, the user may specify as much of the path to the root as desired +when using the tag in annotation. + +The full path version is referred to as **long form**, +and the version with only the final tag element +(excluding placeholder) is called **short form**. + +Any **intermediate form** of the tag path is also allowed as illustrated by this example: + + +````{Admonition} Examples of allowed forms of HED tags with and without values. +| Short-form | Intermediate form(s) | Long-form | +| -----------| ------------------ |--------- | +| *Cough* | *Move/Breathe/Cough*
*Breathe/Cough* | *Action/Move/Breathe/Cough* | +| *Weight/3 lbs* | *Data-property/Data-value/Physical-value/Weight/3 lbs*
*Data-value/Physical-value/Weight/3 lbs*
*Physical-value/Weight/3 lbs* | *Property/Data-property/Data-value/Physical-value/Weight/3 lbs* | +```` + +HED tools are available to map between shortened and long forms as needed. +The tag must be associated with a schema and must correspond to a path in the schema +(excluding any extension or value). + +See [**NODE_NAME_EMPTY**](./Appendix_B.md#node_name_empty) for errors involving +forward slashes (`/`) and [**TAG_INVALID**](./Appendix_B.md#tag_invalid) for +other types of tag syntax errors. + +### 3.2.3. Tag case-sensitivity + +Although by convention tag terms start with a capital letter with the remainder being lower case, +tag processing is case-insensitive. +This convention makes annotation strings more readable and is recommended +for tag extensions. +Validators and other tools must treat tags containing the same characters, +but different variations in capitalization as equivalent. + +The only exception to the case-insensitive processing rule is that the correct case of units +should be preserved, both during schema processing and during annotation processing. +This rule is required because SI distinguishes symbols and unit modifiers +that differ in case. + +### 3.2.4. Tags that take values + +A HED tag that takes a value corresponds to a schema node whose unique child is a `#` leaf node. +The actual schema `takesValue` attribute appears on the `#` placeholder +rather than on the tag itself. + +These tags may appear with or without a value. +When used with a value, the tag term is followed by a slash, +followed by a value. + +A placeholder or its direct parent tag may not be extended in any other way. +Thus, tags that have placeholder children cannot be extended even +if they inherit an `extensionAllowed` attribute from an ancestor. +The parsers treat any child of these tags as a value substituted for the +placeholder rather than as a tag extension. + +If a `unitClass` is specified as an attribute of the `#` node, then the units specified +must be valid units for that `unitClass`. + +The characters that may be used in the value that replaces the `#` placeholder must be +in the union of the values allowed by the `valueClass` attributes of the`#` node. +If units are given, they may place additional restrictions on the allowed values. + +Units with the `unitPrefix` attribute, such as `$`, appear before the value. Units without the `unitPrefix` attribute appear after the value. +**HED parsers assume that units are separated from values by a single blank regardless of the position of the units.** + +Some unit classes have the `defaultUnits` attribute specifying the units +that downstream analysis tools should assume if units are omitted. + +Additional checks may be made on the substituted values depending on the `valueClass` + +| valueClass | Additional value checks | +| ----------- | ----------------------- | +| numericClass | Must be a valid floating point number. | +| dateTimeClass | Must be a valid ISO8601 value. | + +The values of HED tag placeholders cannot stand alone, +but must include the parent when used in a HED string. +For example, the `Label` node in the HED schema has the `#` child. +Thus, the value `myLabel` meant to +substitute for the `#` child of the `Label` node must include `Label` term when used in a HED tag +(e.g., `Label/myLabel` not `myLabel`). + +The values substituted for `#` may themselves be schema node names provided they conform with any +value class requirements associated with that `#`. +Thus, `Label/Item` is a valid HED tag event though `Item`, itself, is a valid top tag. +It is the `Label` tag with its value `Item` and is unrelated to the `Item` HED tag. +However, `Data-maximum/Item` is not valid because +the `#` child of `Data-maximum` has a `valueClass=numericClass` attribute +and the `Item` value is not numeric. + +Certain unit classes allow other special characters in their value specification. +These special characters are specified in the schema with the `allowedCharacter` attribute. +An example of this is the colon in the `dateTimeClass` value class. + + + +See [**VALUE_INVALID**](./Appendix_B.md#value_invalid) and +[**UNITS_INVALID**](./Appendix_B.md#units_invalid) for information +on the specific validation errors associated with tags that take values. + +### 3.2.5. Tag extensions +A tag extension, in contrast to a value, is a tag that users add +as a child of an existing schema node as a more specific term for an item already in the schema. +For example, a user might want to use `Helicopter` instead of the more general term `Aircraft`. +Since `Aircraft` inherits the `extensionAllowed` attribute, +users may use extended tags such as `Aircraft/Helicopter` in their annotation. +The requirements for such an extension are: + +````{warning} **Requirements for tag extensions by users:** + +1. Unlike values, an extension term must not already be a node in the schema. +2. The extension term must only have alphanumeric, hyphen, or underbar characters so that it +conforms to the rules for a *nameClass* value. +3. The parent of the tag extension must always be included with the extended tag in annotation. +4. The extension term must satisfy the "is-a" relationship with its parent node. +5. The `#` placeholder cannot be used as an extension -- in particular it cannot be used as a placeholder in definitions or as value annotations in sidecars. + +**Note:** The is-a relationship is not checked by validators. +It is needed so that term search works correctly. + +```` + +Tag extensions should follow the same naming conventions as +those for schema nodes. +See [**3.1.3. Naming conventions**](#313-naming-conventions) for more information about HED naming conventions. +A [**STYLE_WARNING**](Appendix_B.md#style_warning) warning is +issued for extension tags that do not follow the HED naming convention. + +Users should not use tag extension unless necessary for their application, +as this breaks the commonality among annotations across datasets. +Please open an [**issue**](https://github.com/hed-standard/hed-examples/issues) +proposing that the new term be added to the schema in question, +if you think the term would be useful to other users. + +See [**TAG_EXTENSION_INVALID**](./Appendix_B.md#tag_extension_invalid) +for information on the specific validation errors associated invalid tag extensions. + +**Note:** User tag extensions are sometimes accidental and due to misspelling, +particularly when a long or intermediate form of the tag is used. +For this reason the [**TAG_EXTENDED**](./Appendix_B.md#tag_extended) +warning is issued for extended tags during validation. + +### 3.2.6. Tag prefixes + +Users may select tags from multiple schemas, +but additional schemas must be included in the HED version specification. + +Users are free to use any alphabetic prefix and associate it with a specific +schema in the HED version specification. +Tags from the associated schema must be prefixed with this name (followed by a colon) +when used in annotation. + +Terms from only one schema can appear in the annotation without a namespace prefix followed by a colon. + +See [**TAG_PREFIX_INVALID**](./Appendix_B.md#tag_prefix_invalid) +for information on the specific validation errors associated with missing schemas. + +See [**7.4. Library schema in BIDS**](./07_Library_schemas.md#74-library-schemas-in-bids) for an example of how the +prefix notation is used in BIDS. + + +### 3.2.7. Strings and groups + +A **HED string** is an unordered, comma-separated list of HED tags and/or HED tag groups. + +A **HED tag group** is an unordered, +comma-separated list of HED tags and/or tag groups enclosed in parentheses. +Tag groups may include other tag groups. + +The validation errors for HED tags and HED strings are summarized in +[**Appendix B: HED errors**](Appendix_B.md#b-hed-errors). + +#### 3.2.7.1. Parenthesis and order + +Any ordering of HED tags and HED tag groups at the same level within a HED string is equivalent. +Valid HED strings may have parentheses nested to arbitrary levels (nested groups). +The parentheses must be properly nested and matched. + +Parentheses are meaningful and convey association. +If `A` and `B` represent HED expressions, (`A`, `B`) is not equivalent to +the HED string `A`, `B`. +The distinction should be preserved if possible. +(`A`, `B`) means that HED tag `A` and HED tag `B` are associated with each other, +whereas `A`, `B` means that `A` and `B` are each annotating some larger construct. + +Specific rules of association will be encoded in a future version of the HED specification. + +See [**PARENTHESES_MISMATCH**](./Appendix_B.md#parentheses_mismatch) +for validation errors result from improper use of parentheses. + + +#### 3.2.7.2. Tag group attributes + +A HED tag corresponding to a schema node with the `tagGroup` attribute +must appear inside parentheses (e.g., must be in HED tag group). + +A HED tag corresponding to a schema node with the `topLevelTagGroup` must appear +in an unnested HED group in an assembled HED annotation. +Only one tag with the `topLevelTagGroup` attribute may appear in the same +top-level group. +The `topLevelTagGroup` attribute is usually associated with tags +that have special meanings in HED such as `Definition` and `Onset`. + +See [**TAG_GROUP_ERROR**](./Appendix_B.md#tag_group_error) for +information on the group errors detected based on schema attributes. + +#### 3.2.7.3. Empty tags and groups + +Empty parentheses and multiple commas with no intervening tags represent empty tags and are invalid, +as are HED strings with leading or trailing commas. +Hence, if `A` and `B` are any HED expressions, +(`A`, ((`B`))) is valid but (`A`, ()) is not. + +See [**TAG_EMPTY**](./Appendix_B.md#tag_empty) for +information on the validation errors due to empty tags or groups. +Some of these errors may be reported as +[**COMMA_MISSING*](./Appendix_B.md#comma_missing) + + +#### 3.2.7.4. Repeated expressions + +Duplicated tag expressions at the same level in a +HED tag group or HED string are not allowed. +For example, the expressions (`Red`, `Blue`, `Red`) and +(`Red`, `Blue`), (`Red`, `Blue`) have duplicated tag expressions at the same +level and are hence invalid. + +See [**TAG_EXPRESSION_REPEATED**](./Appendix_B.md#tag_expression_repeated) for +more details on validation errors due to repeated tag expressions. + + +### 3.2.8. Special tags + +#### 3.2.8.1. The `Definition` tag + +A HED definition is a tag group consist of a `Definition` tag that takes +a value representing the definition's name and a tag group defining the concept. +Each definition is independent and stands alone. +The definition must contain a non-empty tag group. + +The `Definition` tag corresponds to a schema node with the `topLevelTagGroup` attribute, +assuring that definitions cannot be nested. + +HED definitions may not contain any `Def` or `Def-expand` tags and must contain +exactly one `Definition` tag. +Multiple definitions with the same definition name are not allowed. + +The `Definition` tag must be extended with a +value representing the definition name and may +be additionally extended by a `#` placeholder. +If the definition name includes the `#` placeholder extension, +then the defining tags must +include exactly one tag that takes a value along with its `#` placeholder. + +Definitions with the same name are considered duplicate definitions regardless of +whether one has a placeholder and another does not. +**However, each distinct substituted value represents a distinct definition name for +purposes of `Onset`/`Offset` processing.** + +See [**DEFINITION_INVALID**](./Appendix_B.md#definition_invalid) for +a listing of situations in which a definition may be invalid. + +See also [**Chapter 5.1 Creating definitions**](./05_Advanced_annotation.md#51-creating-definitions) +for more details and examples. + +#### 3.2.8.2. `Def` and `Def-expand` tags + +A definition is incorporated into annotations using the tag +`Def/xxx` where `xxx` is the definition's name. + +Alternatively, the annotator may use an expanded form `(Def-expand/xxx, yyy)` +where `xxx` is the definition's name and `yyy` is a tag group containing +the definitions contents. + +The two usages are equivalent, and tools should be able to transform between the two representations. +Note, however, that transforming from a `Def` to a `Def-expand-group` requires the definition, +while transforming from a `Def-expand-group` to `Def` form does not. + +For definitions that include a placeholder, a value must be substituted for +the `#` placeholder in `Def` and `Def-expand-group` when final +annotation assembly occurs. + +See [**DEF_INVALID**](./Appendix_B.md#def_invalid) and +[**DEF_EXPAND_INVALID**](./Appendix_B.md#def_expand_invalid) +for details on the types of errors that occur with `Def` and `Def-expand`. + +See also [**Using definitions**](./05_Advanced_annotation.md#52-using-definitions) +for more details and examples. + +#### 3.2.8.3. `Onset` and `Offset` tags + +The `Onset` and `Offset` tags are used to represent the temporal extent +of events that have non-zero duration. +Each of these tags must appear in a top level tag group with a +`Def` or `Def-expand-group` anchor. + +A tag group with an `Onset` represents the start of an event that extends over time. +A tag group with an `Offset` represents the end of an event that was previously initiated by an `Onset` group. +A given event of temporal extent is also terminated by the appearance of another +`Onset` group with the same `Def` or `Def-expand-group` anchor. + +The `Onset` tag group may only contain its `Def` or `Def-expand-group` anchor and +at most one additional inner tag group in addition to the `Onset` tag. + +The `Offset` tag group may only contain its `Def` or `Def-expand-group` anchor in +addition to the `Offset` tag. + +These requirements imply that `Onset` and `Offset` must be the only tags +in their tag group with the `topLevelTagGroup` attribute. +`Onset` and `Offset` tags correspond to schema nodes with the `topLevelTagGroup` attribute. +This implies, for example, that HED definition's contents may not include +`Onset` or `Offset` tags. + +See [**ONSET_OFFSET_ERROR**](./Appendix_B.md#onset_offset_error) and + [**TAG_GROUP_ERROR**](./Appendix_B.md#tag_group_error) and +for a listing of specific errors associated with onsets and offsets. + +[**Chapter 5.3.1 Using Onset and Offset**](./05_Advanced_annotation.md#531-using-onset-and-offset) +in Chapter 5 gives examples of usage and additional details. + + +#### 3.2.8.4. The `Event-context` tag + +The `Event-context` tag corresponds to a schema node with both the `topLevelTagGroup` and `unique` attributes. +This implies that there can be only one `Event-context` group in each assembled event-level HED string. +The `Event-context` group contains information about what other events are ongoing at the time point +associated with the event marker for which the annotation is included. + +In general, the `Event-context` group is not included in annotations, but is generated by tools during +downstream event processing. + +See [**TAG_GROUP_ERROR**](./Appendix_B.md#tag_group_error) and +[**TAG_NOT_UNIQUE**](./Appendix_B.md#tag_not_unique) for additional information +on validation errors related to `Event-context`. + +Additional details and examples for `Event-context` can be found in +[**5.5. Event contexts**](./05_Advanced_annotation.md#55-event-contexts). + +### 3.2.9. Sidecars + +A sidecar is a dictionary that can be used to associate tabular file columns +and their values with HED annotations. +The rows of tabular event files represent time markers on the experimental timeline, +and the assembled annotations for each row describe what happened at that time marker. +A sidecar containing annotations associated with the columns of such an event file +allows HED tools to assemble HED annotations for each row in the file. + +The rows of tabular files representing other types of information +can also be annotated in the same way. + +The "HED" key, which may only appear at the second level in the JSON dictionary, +designates an entry that contains HED annotations. +"HED" keys that appear at other levels of the JSON sidecar are considered to be +in error. + +HED sidecar validation assumes that the dictionary is saved in JSON format and complies with the +[**BIDS sidecar**](https://bids-specification.readthedocs.io/en/stable/appendices/hed.html) format. + +#### 3.2.9.1. Sidecar entries + +A BIDS sidecar is dictionary with many possible types of entries, three of which are relevant to HED. +These entries all have `"HED"` as a key in one or more second-level dictionaries. + +````{Admonition} Three types of JSON sidecar entries of interest to HED tools +- **Categorical entries**: are associated with a particular event file column and provide +individual annotations for each column value. +The dictionary is not required to provide annotations for every possible +value a categorical column, although tools may choose to issue a warning if appropriate. +The dictionary may also include annotations for values that do not appear in the associated event file column. +

+ +- **Value entries**: are associated with a particular event file column and provide +an annotation that applies to any entry in the column. +The HED annotation must contain a single `#` placeholder, +and each individual column value is substituted for the `#` in the annotation +when the annotation for the entire row is assembled. + +

+ +- **Dummy entries**: are similar in format to categorical entries, +but are not associated with any event file columns. +Rather these annotations are mainly used to gather HED definitions. + +```` + +HED definitions are required to be separated into +dummy sidecar column entries. +They may not appear in sidecar entries containing tags other than definitions. + +The sidecar does not have to provide a HED-relevant entry for every event file column. +Columns with no corresponding sidecar entry are skipped during assembly of the HED annotation +for an event file row. + +For compatibility with [**BIDS**](https://bids.neuroimaging.io/), +tabular file column entries containing `n/a` are ignored. +The sidecar is not permitted to provide an annotation for `n/a`. +Further, `"HED"` can only appear as a second-level dictionary key. + +The following example illustrates the three types of JSON sidecar entries that are relevant to HED. +Entries without a `"HED"` key in the second level entry dictionaries are ignored. + +(example-sidecar-anchor)= +````{Admonition} Examples of the three types of sidecar annotation entries relevant to HED +:class: tip +```json +{ + "trial_type": { + "LongName": "Event category", + "Description": "Indicator of type of action that is expected", + "HED": { + "go": "Sensory-event, Visual-presentation, (Square, Blue)", + "stop": "Sensory-event, Visual-presentation, (Square, Red)" + } + }, + "response_time": { + "LongName": "Response time after stimulus", + "Description": "Time from stimulus presentation until subject presses button", + "HED": "(Delay/# ms, Agent-action, (Experiment-participant, (Press, Mouse-button)))" + }, + "dummy_defs": { + "HED": { + "MyDef1": "(Definition/Cue1, (Buzz))", + "MyDef2": "(Definition/Image/#, (Image, Face, Label/#))" + } + } +} +``` +```` + +In the example, the `trial_type` key references a **categorical** entry. +Categorical entries have keys corresponding to the event file column names. +The value of a categorical entry is a dictionary which has a `"HED"` key. +In the above example, the keys of this second dictionary are the values (`go` and `stop`) that +appear in the `trial_type` column of the event file. +The values are the HED annotations associated with those values. +Thus, the `"Sensory-event, Visual-presentation, (Square, Blue)"` is the HED annotation +associated with a `go` value in the `trial_type` column of the associated event file. + +The `response_time` key references a **value annotation**. +Value entries have keys, one of which is `"HED"`. +Associated with the `"HED"` key is a HED annotation value. +There must be exactly one `#` placeholder in the annotation. +The actual value in the `response_time` column is substituted for the +`#` when the annotation is needed. + +The `dummy_defs` is an example of a **dummy annotation**. +The value of this entry is a dictionary with a `"HED"` key +pointing to a dictionary. +A dummy annotation is similar in form to a **categorical annotation**, +but its keys do not correspond to any event file column names. +Rather it is used as a container to organize HED definitions. + +In the example, +`Definition/Cue1` is a definition that does not use a placeholder (`#`) modifier in its name, +while `Definition/Image/#` is a definition whose name `Image` is modified by a placeholder value. +Notice that `Image` is both a definition name and an actual tag in the schema in this example. +This is permitted. + +#### 3.2.9.2. Sidecar validation + +As with other entities definitions should be removed from sidecars and validated separately, +although validation error messages for such definitions should be associated with +the locations of the definitions in the sidecars. + +HED categorical sidecar entries contain HED strings and should be validated in the same way. + +HED value sidecar entries must contain exactly one `#` placeholder in the HED string annotation associated +with the entry. The `#` placeholder should correspond to a `#` in the HED schema, +indicating that the parent tag (also included in the annotation) expects a value. + +If the placeholder is followed by a unit designator, the validator checks that +these units are consistent with the unit class of the +corresponding `#` in the schema. The units are not mandatory. + +Errors that are particularly relevant to sidecars include [**PLACEHOLDER_INVALID**](./Appendix_B.md#placeholder_invalid) and [**SIDECAR_INVALID**](./Appendix_B.md#sidecar_invalid). + +If the sidecar is missing an annotation for a categorical column value, +the [**SIDECAR_KEY_MISSING**](./Appendix_B.md#sidecar_key_missing) warning is generated. + + +### 3.2.10. Tabular files + +A tabular file is a text file in which each line represents a row in a table. +The column entries in a given row are separated by tabs. +Further, the first line of the file must contain a tab-separated list of +column names, which should be unique. +This description of tabular file conforms to that used by [**BIDS**](https://bids.neuroimaging.io/). + +Generally each row in a tabular file represents an item and the columns values provide properties of that item. +The most common HED-annotated tabular file represents event markers in an experiment. +In this case each row in the file represents a time at which something happened. + +Another common HED-annotated tabular file represents experiment participants. +In this case each row in the file represents a participant, and the columns provide +characteristics or other information about the participant identified in that row. + +In any case, the general strategy for validation or other processing is: +1. Process the individual components of the HED annotation (tag and string level processing). +2. Assemble the component annotations for a row (event or row level processing). +3. Check consistency and relationships among the row annotations (file-level processing). + +#### 3.2.10.1. Tabular annotations + +HED annotations in tabular files can occur both in a `HED` column within the file and +in an associated JSON sidecar. + +The HED strings that appear in a `HED` column must be valid HED strings. + +Definitions many not appear in the `HED` column of a tabular file. +Definitions may not appear in any entry of a JSON sidecar corresponding +to a column of the tabular file. + +#### 3.2.10.2. Event-level processing + +After individual HED tags and HED strings in the `HED` column of tabular files and +in the associated sidecars are validated or otherwise processed, +the HED strings associated with each row of the tabular file must be assembled to provide an overall +annotation for the row. +We refer to this as *event-level* or *row* processing. + +````{Admonition} General procedure for event-level (row) processing. + +1. Start with an empty list. +2. For each categorical column, the column value for the row is looked up in the sidecar. +If an annotation for that column value is available it is concatenated to the list. +3. For each value column, if a column an associated value entry in the sidecar, +the row value is substituted for `#` placeholder in the annotation and the result concatenated to the list. +4. If a `HED` column annotation exists for that row, it is concatenated to the list. +5. Finally, all the entries of the list are joined using a comma (`,`) separator. + +In all cases `n/a` column values are skipped. +```` + +For an example, see [**How HED works in BIDS**](https://www.hed-resources.org/en/latest/BidsAnnotationQuickstart.html#how-hed-works-in-bids) tutorial. + +If the HED schema used for processing contains a schema node that has the `required` attribute, then +the assembled HED annotations for each row must include that tag. +Currently, HED schema versions >= 8.0.0 do not contain any nodes with the `required` +attribute, and this attribute may be deprecated in future versions of the schema. + +If the HED schema used for processing contains a schema node that has the `unique` attribute, +then the assembled HED annotations for each row must contain no more than one occurrence of that tag. +Currently, only `Event-context` has the `unique` attribute for HED schema versions >= 8.0.0. + +See [**REQUIRED_TAG_MISSING**](./Appendix_B.md#required_tag_missing) +and [**TAG_NOT_UNIQUE**](./Appendix_B.md#tag_not_unique) for information +on the validation errors that may occur with tags that have the `required` or `unique` +schema attributes, respectively. + +#### 3.2.10.3 File-level processing + +HED versions >= 8.0.0 allow annotation of relationships among rows in a tabular file. +Hence, processing generally requires that annotations for all the rows be assembled +so that consistency can be checked. + +To validate temporal scope, the validator must assure that each `Onset` and `Offset` tag +is associated with an appropriately defined identifier corresponding to a definition name. +The validator must also check to make sure that `Onset` and `Offset` tags are +properly matched within the data recording. +In particular every `Offset` tag group must correspond to a preceding `Onset` tag group. + +See [**ONSET_OFFSET_ERROR**](./Appendix_B.md#onset_offset_error) for details on the +type of errors that are generated due to `Onset` and `Offset` errors. diff --git a/docs/source/03_Schema.md b/docs/source/03_Schema.md deleted file mode 100644 index f86a9895..00000000 --- a/docs/source/03_Schema.md +++ /dev/null @@ -1,432 +0,0 @@ -# 3. The HED schema - -A HED schema is the formal specification of the HED vocabulary and rules for annotating events. -The HED schema vocabulary is organized hierarchically so that similar concepts and terms appear -close to one another in the organizational hierarchy. (See the -[expandable schema viewer](https://www.hedtags.org/display_hed.html).) -Valid HED annotations must be drawn from a HED schema vocabulary and HED validators -and other tools use the information encoded in the relevant schema when -performing validation and other processing of HED annotations. - -Users must provide the version of the HED schema they are using when creating an annotation. -Past, present, and future versions of the HED schema adhere to -[semantic versioning](https://semver.org/) with version numbers of the form -*x.y.z* representing *major.minor.patch* versions. Although schema developers work with HED -schema in `.mediawiki` format for ease in editing, HED tools generally use XML versions -of the HED schema. - -````{admonition} **Standard development process for XML schema.** -:class: tip - -1. Create or modify a `.mediawiki` file containing the schema. -2. Convert to `.xml` using the [HED tools](https://hedtools.ucsd.edu/hed/schema). -3. View in the [expandable schema viewer](https://www.hedtags.org/display_hed.html) to verify. -```` - -HED schema XML filenames use the standardized format `HEDx.y.z.xml`. These standardized names -make it easier for tools to locate the appropriate HED schema version in the HED working group -[GitHub website](https://github.com/hed-standard). The XML schema versions are stored in the -[`hedxml`](https://github.com/hed-standard/hed-specification/tree/master/hedxml) directory of the -[HED specification repository](https://github.com/hed-standard/hed-specification). - -Third generation HED begins with schema version 8.0.0. Thus, the file containing the first -official release of the third generation HED schema is `HED8.0.0.xml`. Note: HED versions -*8.0.0-alpha.1* through *8.0.0-beta.5* are prerelease versions of HED-3G and should not be -used as they will eventually be deprecated. - -Releases are stored in [`hedxml`](https://github.com/hed-standard/hed-specification/tree/master/hedxml) -directory of the [`hed-specification`](https://github.com/hed-standard/hed-specification) repository. -Deprecated versions of the HED schema are stored in the -[`hedxml/deprecated`](https://github.com/hed-standard/hed-specification/tree/master/hedxml/deprecated) -directory of the [`hed-specification`](https://github.com/hed-standard/hed-specification) repository. - -All data recordings in a dataset should be annotated using a single version of the standard -HED schema. Validation and analysis tools are not expected to handle multiple versions of -the standard HED schema when processing a dataset. Datasets may also include annotations -from multiple HED library schema extensions in addition to those from the standard schema, -as described in [Chapter 7: Library schema](07_Library_schema.md#7-library-schema) of this document. -A more detailed discussion of the HED schema format appears in -[Appendix A](Appendix_A.md#a-schema-format). - - -## 3.1. Mediawiki schema format - -HED schema developers usually specify schema in `.mediawiki` format for more convenient editing, -display, and reference on GitHub. However, tools assume that the schema is in .mediawiki format. -Conversion tools allow The following brief example illustrates the format. A full description -of the format is given in [Appendix A](Appendix_A.md#a-schema-format). - -````{admonition} **Example:** Layout of a HED schema (.mediawiki). - -```moin -HED version="8.0.0" - -'''Prologue''' -This prologue introduces the schema. - -!# start schema -'''Event''' [Something that happens at a given place and time.] -* Sensory-event {suggestedTask=Task-event-role}[Something perceivable by an agent.] - . . . -'''Property'''{extensionAllowed}[A characteristic.] -* Informational-property [A quality pertaining to information.] -** Label {requireChild} [A string of 20 or fewer characters.] -*** # {takesValue, valueClass=nameClass} -!# end schema - -'''Unit classes''' [Unit classes and units for the nodes.] - . . . -'''Unit modifiers''' [Unit multiples and submultiples.] - . . . -'''Value classes''' [Rules for the values provided by users.] - . . . -'''Schema attributes''' [Allowed node attributes.] - . . . -'''Properties''' [Properties of the schema attributes.] - . . . -'''Epilogue''' -An optional section that is the place for notes and is ignored in HED processing. - -!# end hed -``` - -```` - -Beginning with third generation HED (HED schema versions 8.0.0 and later), **terms in a given schema must be unique within that schema.** This uniqueness rule allows automated expansion of short form HED strings into their full long forms. - -Top level tree root elements are enclosed by triple single quotes. Each child term within the -schema must be on a single line that begins with a certain number of consecutive asterisks (`*`) -corresponding to the term’s level within the hierarchy. The term or node name is separate from -its level-indicating asterisks by a space. - -Everything after each HED term must be enclosed by `` markup elements. Items within these markup elements include a term description and term attributes. - -Term (node element) descriptions are enclosed in square brackets (`[ ]`) in the `.mediawiki` -specification and indicate the meaning of the term or tag they modify. - -HED term attributes are enclosed with curly braces (`{ }`). These term attribute provide -additional rules about how the tag and modifying values should be used and handled by tools. -Allowed HED term attributes include unit class and value class values as well as -HED schema attributes that do not have the `unitClassProperty`, `unitModifierProperty`, -`unitProperty`, or `valueClassProperty`. - -HED term attributes appear in the schema specification either as `name` attributes or as -`name=value` pairs. The presence of a `name` attribute for a schema node element indicates -that the attribute is true for that term, while the presence of a `name=value` attribute -indicates that the attribute has the specified value for that term. If multiple values -of a particular attribute are applicable, they should be specified as separate name-value pairs. - -The hashtag character (`#`) is a placeholder for a user-supplied value. Within the HED schema a -`#` node indicates that the user must supply a value consistent with the unit classes and value -classes of the `#` node if it has any. Lines with hashtag (`#`) placeholders should have -everything after the asterisks enclosed by `` markup elements. - - -## 3.2. XML schema format - -The HED XML version of the schema is used during validation and analysis. -The `.xml` format has changed with the release of HED-3G. This modification of the -XML format was done for the following reasons. - -````{admonition} **Reasons for XML file format change for HED.** -:class: tip - -1. To correctly handle multiple values of schema attributes. -2. To preserve the prologue and epilogue information present in `.mediawiki` files. -3. To allow schema attributes to be formally specified and validated. -4. To allow an XSD specification of the HED schema for validation of the schema. -```` - -The following is a translation of the `.mediawiki` example from the previous section in -the new XML format. A complete specification of the format is given in -[Appendix A: Schema format](Appendix_A.md#a-schema-format). - -````{admonition} **Example:** XML version of previous example. - -```xml - - - This prologue introduces the schema. - - - Event - Something that happens at a given place and time. - - Sensory-event - Something perceivable by an agent. - - suggestedTag - Task-event-role - - - - . . . - - Property - A characteristic of some entity. - - extensionAllowed - - - Informational-property - A quality pertaining to information. - - Label - A string of less than 20. - - requireChild - - - # - - takesValue - - - valueClass - nameClass - - - - - - ... - ... - ... - ... - ... - This epilogue is a place for notes and is ignored in HED processing. - -``` -```` - -### 3.2.1 The `` element - -Each `` element must have a `` child element corresponding to the HED tag term -that it specifies. A `` element may also have a `` child element containing -the text that appears in square brackets (`[ ]`) in the `.mediawiki` version. -The schema attributes (which appear as `name` values or `name-value` pairs enclosed in -curly braces {} in the `.mediawiki` file) are translated into `` child elements -of `` in the `.xml`. - -### 3.2.2 Unit classes and modifiers - -The HED schema also includes a `` section that specifies the allowed -unit classes and the corresponding allowed unit names. Only the singular version of each unit name is explicitly specified, but the corresponding plurals of the explicitly mentioned -singular versions are also allowed (e.g., `feet` is allowed in addition to `foot`). -HED uses a `pluralize` function available in both Python and Javascript to check validity. - -The `` section lists the SI unit multiples and submultiples -that are allowed to be prepended to units that have the `SIUnit` schema attribute. - -### 3.2.3 Value classes - -The ` `section specifies rules for the values that are substituted -for placeholders (`#`). Examples are special characters that are allowed for numeric values -or dates. Placeholders that have no `valueClass` attributes, are assumed to follow the -rules for HED tag naming described in the next section. - -### 3.2.4 Schema attributes - -The `` section lists the schema attributes that apply to some -nodes and definitions in other sections of the schema. The specification of which type of -elements an attribute may apply to is specified by the property attributes of these schema -attributes. - -### 3.2.5 Schema properties - -The `` section lists properties of the schema attributes, themselves. -This specification allows general validation to handle a lot of the processing directly based -on the HED schema contents rather than on hard-coded implementation. - -## 3.3. Allowed names and values - -The different parts of the HED schema and associated HED tags have different rules -for the characters and names that are allowed. UTF-8 characters are not supported. -Schema designers and users that extend HED schema must use node or term names -that conform to the rules for `valueClass=nameClass`. Placeholder values that don’t have -an associated `valueClass` attribute are also assumed to have `valueClass=nameClass`. - -### 3.3.1 Rules for the HED schema - -`````{list-table} Rules for valid terms in the HED schema. -:header-rows: 1 -:widths: 20 50 - -* - Element - - Allowed characters -* - Node (`nameClass`) - - Alphanumeric characters, hyphens, and underbars with no white space. -* - Description (`textClass`) - - Alphanumeric characters, blanks, commas, periods, semicolons,
- colons, hyphens, underbars, forward slashes, carets (^), and parentheses. -* - Placeholder (`#`) - - A special node value which indicates a later substitution. -````` - -````{admonition} Notes on rules for allowed characters in the HED schema. -:class: tip -1. The first letter of a schema term should be capitalized with the remainder lower case. -2. Schema terms containing multiple words cannot contain blanks and should be hyphenated. -3. Schema descriptions should be concise sentences, possibly with clarifying examples. -4. Schema descriptions cannot contain square brackets, curly braces, quotes, or punctuation -not specifically allowed by `textClass`. -```` - -### 3.3.2 Rules for HED tags - -HED tags are paths within the HED schema. Tags corresponding to schema nodes that have a `#` -placeholder child can be extended by a slash followed by a value that conforms to the value and -unit classes specified in the schema `#` placeholder node. These values can be terms -corresponding to existing schema nodes, provided the terms satisfy value and unit class constraints. - -Nodes that do not have a `#` placeholder child may be extended by additional terms separated by -slashes, provided that they have inherited the `extensionAllowed` attribute. In this case, -the extension terms should conform to the rules for node names and may not already be a node in the -schema. - -`````{list-table} Rules for valid HED tags and their extensions. -:header-rows: 1 -:widths: 20 50 - -* - Element - - Allowed characters -* - Node extensions (`nameClass`) - - Alphanumeric characters, hyphens, and underbars with
- no white space.
- The extension cannot be an existing schema node. -* - Description tag values (`textClass`) - - Alphanumeric characters, blanks, commas, periods, semicolons,
- colons, hyphens, underbars, forward slashes, carets (^), and parentheses. -* - Placeholder substitutions - - Depends on `valueClass` as well as allowed `unitClass` and unit modifiers. -* - Library names - - A single word containing only alphabetic characters. -* - Namespaces - - A single alphabetic word followed by a single colon. -````` - -````{admonition} Notes on rules for allowed characters in the HED tags. -:class: tip -1. The first letter of a node name extensions should be capitalized with the remainder lower case. -2. Terms containing multiple words cannot contain blanks and should be hyphenated. -3. Blanks around comma and parentheses delimiters are not part of a HED tag. -4. Values substituted for `#` may have special characters determined by the value class. -For example, the colon (:) is specifically allowed for the `dateTimeClass` value class. -7. Units are separated from their value by at least one blank whether prefix or suffix. -8. Library namespace names are local and consist of a short alphabetic word followed by a single colon. -```` - -### 3.3.3 Placeholders in HED tags - -The values of HED tag placeholders cannot stand alone, but must include the parent when used in a HED string. -For example, the *Label* node in the HED schema has the `#` child. Thus, the value *myLabel* meant to -substitute for the `#` child of the *Label* node must include *Label* when used in a HED tag -(e.g., *Label/myLabel* not *myLabel*). - -The values substituted for `#` may themselves be schema node names provided they conform with any -value class requirements associated with that `#`. -Thus, *Label/Item* is a valid HED tag. However, *Data-maximum/Item* is not valid because -the `#` child of *Data-maximum* has a *valueClass=numericClass* attribute. - -Certain unit classes allow other special characters in their value specification. -These special characters are specified in the schema with the `allowedCharacter` attribute. -An example of this is the colon in the `dateTimeClass` unit class. - -## 3.4. Vocabulary organization - -The HED-3G schema (version 8.0.0 and above) contains six root trees of HED terms: *Event*, -*Agent*, *Action*, *Item*, *Property*, and *Relation*. - -The *Event* root tree terms indicate the general category of the event, such as whether it -is a sensory event, an agent action, a data feature, or an event indicating experiment -control or structure. The HED annotations describing each event may be assembled from a -number of sources during processing. - -The assembled HED string annotating an event should have at least one tag from the -*Event* tree, as many analysis tools use the *Event* tags as a primary means of -segregating, epoching, and processing the data. Ideally, tags from the *Event* -subtree should appear at the top level of the HED annotation describing an -event to facilitate analysis. - -The *Agent* root tree terms indicate types of agents (e.g., persons, animals, avatars) -that take an active role or produce a specified effect. An *Agent* tag should be -grouped with property tags that provide information about the agent, such as -whether the agent is an experiment participant. - -The *Action* root tree terms describe actions performed by agents. Generally these are -grouped in a triple *(A, (Action, B))* which is interpreted as *A* does *Action* on *B*. -If the action does not have a target, it should be annotated *(A, (Action))*, meaning -*A* does *Action*. - -The *Item* root tree terms describe things with (actual or virtual) physical existence -such as objects, sounds, or language. - -Descriptive elements are organized in the *Property* rooted tree. These descriptive -elements should always be grouped with the elements they describe using parentheses. - -Binary relations are in the *Relation* rooted tree. Like items from the *Action* -sub-tree, these should be annotated using *(A, (Relation, B))*. - - -## 3.5. Tag syntax - -A **HED tag** is a term in the HED vocabulary identified by a path consisting of the -individual node names from some branch of the HED schema hierarchy separated by forward -slashes (/). -An important requirement of third generation HED is that the node names in -the HED schema **must be unique**. As a consequence, the user can specify as much of the path to the -root as desired. The full path version is referred to as **long form** and truncated versions as -**short form**. HED tools are available to map between shortened tags and long form as needed. -Any intermediate form of the tag path is also allowed as illustrated by this example: - -````{admonition} **Example:** Equivalent forms for HED tag representing a triangle. - -1. *Item/Object/Geometric-object/2D-shape/Triangle* -2. *Object/Geometric-object/2D-shape/Triangle* -3. *Geometric-object/2D-shape/Triangle* -4. *2D-shape/Triangle* -5. *Triangle* -```` - -For values that are substituted for a placeholder (`#`) child, the tag must include the parent -as illustrated in this example for the *Label* tag. The values that replace these `#` -placeholders may be schema node names, if the value and unit classes associated with -the `#` placeholder permit it. - -````{admonition} **Example:** Equivalent forms for HED tag representing the label Image1. - -1. *Property/Informational-property/Label/Image1* -2. *Informational-property/Label/Image1* -3. *Label/Image1* -```` - -A **HED string** is a comma-separated list of HED tags and/or HED tag groups. -A **HED tag group** is a comma-separated list of HED tags and/or tag groups enclosed in -parentheses. Tag groups may include other tag groups. Parentheses convey association, -since HED strings are unordered lists. The terms in a HED string must be unique, -thus, a HED string forms a set. - -````{admonition} **Example:** Nested HED tag group indicated press. - -**Short form:** -> *((Human-agent, Experiment-participant), (Press, Mouse-button))* - -**Long form:** -> *((Agent/Human-agent,* -> *Property/Agent-property/Agent-task-role/Experiment-participant),* -> *(Action/Move/Move-body-part/Move-upper-extremity/Press,* -> *Item/Object/Man-made-object/Device/IO-device/Input-device/Computer-mouse/Mouse-button))* - -```` - -The validation errors for HED tags and HED strings are summarized in -[Appendix B: HED errors](Appendix_B.md#b-hed-errors). - -**HED `#` placeholders** cannot have siblings. Thus, tags that have placeholder -children cannot be extended even if they inherit an `extensionAllowed` attribute -from an ancestor. The parsers treat any child of these tags as a value rather than a tag. - -**HED values** can be strings or numeric values followed by a unit specification. -If a `unitClass` is specified as an attribute of the `#` node, then the units specified -must be valid units for that `unitClass`. **HED parsers assume that units are separated from -values by at least one blank.** diff --git a/docs/source/04_Basic_annotation.md b/docs/source/04_Basic_annotation.md index 36c375eb..e2982618 100644 --- a/docs/source/04_Basic_annotation.md +++ b/docs/source/04_Basic_annotation.md @@ -2,18 +2,18 @@ This section illustrates the use of HED tags and discusses various tags that are used to document the structure and organization of electrophysiological experiments. The simplest annotations -treat each event as happening at a single point in time. The annotation process for such +treat each event as happening at a single point in time. The annotation procedure for such events involves describing what happened during that event. This chapter illustrates basic HED descriptions of four types of events that are often annotated using single event markers: **stimulus events**, **response events**, **experiment control events**, and **data features**. -HED-3G now also allows more sophisticated models of events that unfold over time using +HED also allows more sophisticated models of events that unfold over time using multiple event markers. Downstream analyses often look for neurological effects directly following (or preceding) event markers. The addition of HED context, allows information about events that occur over extended periods of time to propagate to intermediate time points. -[Chapter 5: Advanced annotation](05_Advanced_annotation.md#5-advanced-annotation) +[**Chapter 5: Advanced annotation**](05_Advanced_annotation.md#5-advanced-annotation) develops the HED concepts needed to capture these advanced models of events as well as event and task inter-relationships. @@ -29,11 +29,11 @@ between the onset and offset (for example, the maximum velocity point in a parti movement or the maximum potential peak of an eye-blink artifact). A typical example of an experiment using time-marked event annotation is simple target -detection. In this experiment geometric shapes of different colors are presented on a computer +in which geometric shapes of different colors are presented on a computer screen at two-second intervals. After every visual shape presentation, the subject is asked to press the left mouse button if the shape is a green triangle or the right mouse button otherwise. After a block of 30 such presentation-response sequences (trials), the control software sounds a -buzzer to indicate that the subject can rest for 5 minutes before continuing to the next block of +buzzer to indicate that the subject can rest for 2 minutes before continuing to the next block of trials. After the experiment is completed, the experiment runs an eyeblink-detection tool on the EEG data and inserts an event marker at the amplitude maximum of each detected blink artifact. @@ -43,24 +43,28 @@ EEG data and inserts an event marker at the amplitude maximum of each detected b The target detection experiment described above is an example of a stimulus-response paradigm: perceptually distinct sensory stimuli are presented at precisely recorded times (typically with abrupt onsets) and ensuing and/or preceding precisely-timed changes in the behavioral and -physiological data streams are annotated or analyzed. Stimulus onsets (typically) are annotated -with the *Sensory-event* tag. Additional tags indicate task role. Separation of what an event is -(as designated by a tag from the *Event* subtree) from its task role (as indicated by other -descriptive tags) is an important design change that distinguishes HED-3G from earlier versions +physiological data streams are annotated or analyzed. +Stimulus onsets (typically) are annotated with the `Sensory-event` tag. +Additional tags indicate task role. +Separation of what an event is (as designated by a tag from the `Event` subtree) +from its task role (as indicated by other descriptive tags) is an important design change +that distinguishes HED-3G from earlier versions of HED and enables effective annotation in more complex situations. -A stimulus event can be annotated at different levels of detail. When not needed, fine details -can generally be ignored, but once annotated can provide valuable information for later, -possibly unanticipated analysis purposes. In a series of examples, we will annotate successively -more details about the experiment events. Each example shows both the short form and long form. +A stimulus event can be annotated at different levels of detail. +When not needed, fine details can generally be ignored, but once annotated can provide valuable information for later, +possibly unanticipated analysis purposes. +In a series of examples, we will annotate successively +more details about the experiment events. +Each example shows both the short form and long form. The elements in the long form that correspond to the short form are shown in bold-face. -In addition, the long form has a description, which is omitted from the short-form for -readability. +In addition, the long form includes a `Description` tag, +which is omitted from the short-form for readability. The following example illustrates a very basic annotation of a stimulus event, indicating -the stimulus is a green triangle presented visually. The annotation indicates that +the stimulus is a green triangle presented visually. The annotation states that this is a visual sensory event intended to be an experiment stimulus. -*Sensory-event* is in the *Event* rooted tree and indicates the general class +`Sensory-event` is in the `Event` rooted tree and indicates the general class that this event falls into. ````{admonition} **Example:** Version 1 of a visual stimulus annotation. @@ -81,42 +85,51 @@ that this event falls into. The example HED string above illustrates the most basic form of point event annotation. In general, the annotation for each event should include at least one tag from the -*Event* tree. If there are multiple sensory presentations in the -same event, a single *Sensory-event* tag covers the general category for -all presentations in the event. The individual presentations (which may include different -modalities) are grouped with their descriptive tags, while the *Sensory-event* tag applies overall. In this case there is only one, so the grouping is not necessary. - -The *Experimental-stimulus* is a *Task-property* tag. Whether a particular sensory event -is an experiment stimulus depends on the particular task, hence *Experimental-stimulus* -is a *Task-property*. Sensory events that are extraneous to the task can also occur, +`Event` tree. +If there are multiple sensory presentations in the same event, +a single `Sensory-event` tag covers the general category for all presentations in the event. +The individual presentations (which may include different +modalities) are grouped with their descriptive tags, +while the `Sensory-event` tag applies overall. +In this case there is only one, so the grouping is not necessary. + +The `Experimental-stimulus` is a `Task-property` tag. +Whether a particular sensory event is an experiment stimulus depends on the particular task, +hence `Experimental-stimulus` is a `Task-property`. +Sensory events that are extraneous to the task can also occur, so it is important to distinguish those that are related to the intent of the task. The remaining portion of the annotation describes what the sensory presentation is. -The *Green* and *Triangle* tags are grouped to indicate specifically that a green -triangle is presented. *Visual-presentation* is a *Sensory-property* tag from the -*Property* rooted tree. Which senses are impacted by the *Sensory-event* should -always be indicated, even if it appears to be obvious to the reader. +The `Green` and `Triangle` tags are grouped to indicate specifically that a green +triangle is presented. +`Visual-presentation` is a `Sensory-property` tag from the +`Property` rooted tree. +The senses are impacted by the `Sensory-event` should always be indicated, +even if it appears to be obvious to the reader. The goal is to facilitate machine-actionable analysis. HED has a number of qualitative relational tags designating spatial features such as -*Center-of*, which should always be included if possible. These qualitative terms +`Center-of`, which should always be included if possible. These qualitative terms provide clear search anchors for tools looking for general positional characteristics. Hemispheric and vertical distinctions have particular neurological significance. More detailed size, shape, and position information enhances the annotation. However, actual detailed information requires the specification of a frame -of reference, a topic deferred until later in this document. +of reference, a topic not addressed by the current HED specification. -The order of the tags does not matter. HED strings are unordered lists of HED tags -and tag groups. Where the grouping of associated tags needs to be indicated, most -commonly in the case of tags with modifiers, the related tags should be put in a -tag group enclosed by parentheses (as above). +**The order of the tags does not matter.** +HED strings are unordered lists of HED tags and tag groups. +Where the grouping of associated tags needs to be indicated, +most commonly in the case of tags with modifiers, +the related tags should be put in a tag group enclosed by parentheses (as above). -Notice that the long form version also includes a *Description* tag that gives a text -description of the event. Users should always include a *Description* tag in the annotation -of each event type. The *Description* tag is omitted for readability in the short form examples. +Notice that the long form version also includes a `Description` tag that gives a text +description of the event. +The `Description` tag is omitted for readability in the short form examples. As a matter of practice, however, users should start with a detailed text description of each -type of event before starting the annotation. This description can serve as a check on the -consistency and completeness of the annotation. Generally users annotate using the short form +type of event before starting the annotation. +This description can serve as a check on the +consistency and completeness of the annotation. +Generally users annotate using the short form for HED tags and use tools to map the short form into the long form during validation or analysis. @@ -150,21 +163,23 @@ presentation includes information about the role this stimulus appears in the ta ```` -The *Intended-effect* tag is a *Task-effect-evidence* tag that describes the effect +The `Intended-effect` tag is a `Task-effect-evidence` tag that describes the effect expected to be elicited from the participant experiencing the stimulus. This tag indicates, that based on the specification of the task, we can conclude -that the subject will be looking for the triangle (*Target*) and that its appearance -is unusual (*Oddball*). - -Three other tags in the *Task-effect-evidence* are *Computational-evidence*, -*External-evidence*, and *Behavioral-evidence*. In many experiments, a subject indicates -that something occurs by performing an action such as pushing the left mouse button for -a green triangle and the right button otherwise. When the left-mouse button is pushed, +that the subject will be looking for the triangle (`Target`) and that its appearance +is unusual (`Oddball`). + +Three other tags in the `Task-effect-evidence` are `Computational-evidence`, +`External-evidence`, and `Behavioral-evidence`. +In many experiments, a subject indicates that something occurs by performing +an action such as pushing the left mouse button for +a green triangle and the right button otherwise. +When the left-mouse button is pushed, one may conclude that the participant has behaved as though the green triangle appears. -If the button push is tagged with *Behavioral-evidence*, automated tools can check whether -the intended effect agrees with subject behavior. An example of *External-evidence* +If the button push is tagged with `Behavioral-evidence`, automated tools can check whether +the intended effect agrees with subject behavior. An example of `External-evidence` is annotation by a speech therapist about whether the participant stuttered in a speech -experiment. *Computational-evidence* might be generated from BCI annotation. +experiment. `Computational-evidence` might be generated from BCI annotation. HED-3G has more sophisticated methods of specifying the relationships of events and tasks. These require more advanced tagging mechanisms that are discussed later in this document. @@ -174,8 +189,8 @@ These require more advanced tagging mechanisms that are discussed later in this In many experiments, the participant is asked to press (or select and press) a finger button to indicate their perception of or judgment concerning the stimulus. These types of events, -as well as participant actions not related to the task, are annotated as *Agent-action* events. -*Agent-action* events can be annotated with varying levels of detail, as illustrated by +as well as participant actions not related to the task, are annotated as `Agent-action` events. +`Agent-action` events can be annotated with varying levels of detail, as illustrated by the next two examples. ````{admonition} **Example:** Version 1 of button press annotation. @@ -185,12 +200,13 @@ the next two examples. ```` -The *Participant-response* tag indicates that this event represents a task-related response -to a stimulus. The *Press* tag is from the *Action* subtree and is grouped with the -*Mouse-button* to indicate the pressing of a button. In general, *Action* elements can -be considered verbs, while *Items* and *Agents* can be considered nouns. +The `Participant-response` tag indicates that this event represents a task-related response +to a stimulus. The `Press` tag is from the `Action` subtree and is grouped with the +*Mouse-button* to indicate the pressing of a button. +In general, `Action` elements can be considered verbs, +while `Item` and `Agent` elements can be considered nouns. These elements form a natural sentence structure: (subject, (verb, direct object)), -with the subject and direct object being formed by noun elements. *Attribute* +with the subject and direct object being formed by noun elements. `Property` elements are the adjectives, adverbs, and prepositions that modify and connect these elements. @@ -217,24 +233,24 @@ elements are the adjectives, adverbs, and prepositions that modify and connect t ```` -The *Participant-response* tag is modified by tags that indicate that the participant is -reacting by responding as though the stimulus were an oddball target. Specifically the -*Behavioral-evidence* tag documents that the subject gave a response indicating an oddball -target. In other words, the participant pressed the left mouse button indicating an oddball +The `Participant-response` tag is modified by tags that indicate that the participant is +reacting by responding as though the stimulus were an oddball target. +Specifically the `Behavioral-evidence` tag documents that the subject gave a response indicating an oddball target. +In other words, the participant pressed the left mouse button indicating an oddball target, which may or may not match the stimulus that was presented. Other details should be annotated, including whether the subject’s left, right, or dominant hand was used to press the mouse button and whether the left mouse button -or right mouse button was pressed. (This factor was indicated in the *Description*, +or right mouse button was pressed. (This factor was indicated in the description, but not in the machine-actionable tags.) ## 4.5. Experimental control Experiments may have experiment control events written into the event record, -often automatically by the presentation or control software. In the illustration -provided above, a buzzer sounded by the control software indicates -that the subject should rest. +often automatically by the presentation or control software. +In the illustration provided above, +a buzzer sounded by the control software indicates that the subject should rest. ````{admonition} **Example:** Version 1 of a simple feedback event. @@ -257,9 +273,9 @@ that the subject should rest. Another type of tagging documents computed data features and expert annotations that have been inserted post-hoc into the experimental record as events. -The *Computed-feature* and *Observation* tags designate whether the event came -from a computation or from manual evaluation. The following example illustrates -a HED annotation from +The `Computed-feature` and `Observation` tags designate whether the event came +from a computation or from manual evaluation. +The following example illustrates a HED annotation computed from a program. ````{admonition} **Example:** Annotation of an inserted computed feature. @@ -275,17 +291,19 @@ a HED annotation from ```` -As shown by this example, the *Computed-feature* tag is grouped with a label of the form -*toolName_featureName*. In this example, the computed property is just a marker of where -a feature was detected. If a value was computed at this point, an additional *Value* tag -would be included. +As shown by this example, the `Computed-feature` tag is grouped with a label of the form +`toolName_featureName`, in this case the Blinker tool for detecting eye-blinks in EEG. +The computed property is just a marker of where a feature was detected. +If a value was computed at this point, an additional *Data-value* tag would be included. -Clinical evaluations are observational features and many fields have standardized names -for these features. Although the HED standard itself does not specify these names, +Clinical evaluations are observational features, +and many fields have standardized names for these features. +Although the HED standard itself does not specify these names, library schema representing terminology in clinical or application subfields may provide -the vocabulary. (See [Chapter 7: Library schema](07_Library_schema.md#7-library-schema) -for a discussion of library schema.) The following example illustrates how annotation from -a human expert can be annotated in HED. +the vocabulary. +[**Chapter 7: Library schemas**](./07_Library_schemas.md) presents some rules for schema developers. + +The following example illustrates how annotation from a human expert can be annotated in HED. ````{admonition} **Example:** Annotator AJM identifies a K-complex in a sleep record. @@ -303,29 +321,33 @@ a human expert can be annotated in HED. ## 4.7. What else? Most event annotation focuses on basic identification and description of stimuli and the -participant’s direct response to that stimuli. However, for accurate comparisons across studies, -much more information is required and should be documented with HED tags rather than just with -text descriptions. This is particularly true if this information is relevant to the experimental -intent, varied during the experiment, or likely to evoke a neural response. - -The example of [Section 4.1:Instantaneous events](#41-instantaneous-events), -the sensory presentation of a green triangle stimulus image models the event as happening -at a single point in time. More realistically, the green triangle might be displayed -for an extended period (during which other events might occur). Further, the disappearance -of the triangle is likely to elicit a neural response. Exactly how this information should -be represented is discussed in -[Section 5.3: Temporal scope](05_Advanced_annotation.md#53-temporal-scope) with the -introduction of temporal scope and its use with *Onset* and *Offset*. - -Even for a standard setup, aspects such as the screen size, the distance and position of the -participant relative to the screen and the stimulus, as well as other details of the environment, -should be documented as part of the overall experiment context. These details allow analysis -tools to compare and contrast studies or to translate visual stimuli into visual field -information. *Event-context* tags, which are introduced in -[Section 5.5: Event context](05_Advanced_annotation.md#55-event-context), allow this information to be -propagated to recording events in a manner that is convenient for analysis. - -HED also allows the embedding of annotations for the design of the experiment, documenting -how and when condition variables and other aspects of an experiment are changed. -[Section 5.6: Experimental design](05_Advanced_annotation.md#56-experimental-design) +participant’s direct response to that stimuli. +However, for accurate comparisons across studies, +much more information is required and should be documented with HED tags +rather than just with text descriptions. +This is particularly true if this information is relevant to the experimental intent, +varied during the experiment, or likely to evoke a neural response. + +The example of [**Chapter 4.1:Instantaneous events**](#41-instantaneous-events), +models the sensory presentation of the stimulus images happening at a single point in time. +More realistically, the green triangle might be displayed +for an extended period (during which other events might occur). +Further, the disappearance of the triangle is likely to elicit a neural response. +Exactly how this information should be represented is discussed in +[**Chapter 5.3: Temporal scope**](05_Advanced_annotation.md#53-temporal-scope). + +Even for a standard setup, aspects such as the screen size, +the distance and position of the participant relative to the screen and the stimulus, +as well as other details of the environment, +should be documented as part of the overall experiment context. +These details allow analysis tools to compare and contrast studies or to +translate visual stimuli into visual field information. +`Event-context` tags, which are introduced in +[**Chapter 5.5: Event contexts**](05_Advanced_annotation.md#55-event-contexts), +allow this information to be propagated to recording events in a manner +that is convenient for analysis. + +HED also allows the embedding of annotations for the design of the experiment, +documenting how and when condition variables and other aspects of an experiment are changed. +[**Chapter 5.6: Experimental design**](05_Advanced_annotation.md#56-experimental-design) describes HED mechanisms for annotating this information. diff --git a/docs/source/05_Advanced_annotation.md b/docs/source/05_Advanced_annotation.md index e2377da2..dd79b427 100644 --- a/docs/source/05_Advanced_annotation.md +++ b/docs/source/05_Advanced_annotation.md @@ -1,48 +1,48 @@ # 5. Advanced annotation -## 5.1. HED definitions +## 5.1. Creating definitions -HED-3G introduces the *Definition* tag to facilitate tag reuse and to allow implementation of concepts such as -**temporal scope**. The *Definition* tag allows researchers to create a name to represent a group of tags and +HED version 8.0.0 introduced the `Definition` tag to facilitate tag reuse and +to allow implementation of concepts such as **temporal scope**. +The `Definition` tag allows researchers to create a name to represent a group of tags and then use the name in place of these tags when annotating data. These short-cuts make tagging easier and reduce the chance of errors. Often laboratories have a standard setup and event codes with particular meanings. -Researchers can define names and reuse them for multiple experiments. -Another important role of definitions is to provide the structure for implementing temporal scope -as introduced in [Section 5.3: Temporal Scope](05_Advanced_annotation.md#53-temporal-scope). +Researchers can define names and reuse them for multiple experiments. -A **HED definition** is a tag group that includes one *Definition* tag whose required -child value names. -The definition usually includes an optional tag-group specifying the actual definition information. -The following summarizes the syntax of definition. +Another important role of definitions is to provide the structure for +implementing temporal scope as introduced in [**Chapter 5.3: Temporal Scope**](05_Advanced_annotation.md#53-temporal-scope). -``````{admonition} Syntax summary for *Definition* +A **HED definition** is a tag group that includes one `Definition` tag whose required +child value is the definition's name. +The definition tag group also includes an internal tag-group +specifying the definition's content. +The following summarizes the syntax of HED definitions. + +``````{admonition} Syntax summary for HED definitions. **Short forms:** - ~ *(Definition/XXX, (tag-group))* - ~ *(Definition/XXX/#, (tag-group))* + ~ *(Definition/xxx, (definition-content))* + ~ *(Definition/xxx/#, (definition-content))* **Long forms:** - ~ *(Property/Organizational-property/Definition/XXX, (tag-group))* - ~ *(Property/Organizational-property/Definition/XXX/#, (tag-group))* + ~ *(Property/Organizational-property/Definition/xxx, (definition-content))* + ~ *(Property/Organizational-property/Definition/xxx/#, (definition-content))* ````{admonition} Notes: :class: tip -1. *XXX* is the name of the definition and *(tag-group)* is the definition’s value. -2. If the *XXX/#* form is used, then the definition’s *(tag-group)* MUST contain a single `#` +1. *xxx* is the name of the definition, and *(definition-content)* is a tag group +containing the tags representing the definition’s contents. +2. If the *xxx/#* form is used, then the *(definition-content)* MUST contain a single `#` representing a value to be substituted for when the definition is used. -3. The *tag-group* may be omitted if the only purpose of the definition is to define -a label to anchor temporal scope. ([Chapter 5.3: Temporal Scope](05_Advanced_annotation.md#53-temporal-scope)). -4. The *tag-group* is required if the `#` placeholder is used. -5. Neither the definition name *XXX* nor the value substituted for -the `#` placeholder can be node names. + ```` `````` The following example defines the *PlayMovie* term. -````{admonition} **Example:** *PlayMovie* represents playing a movie on the screen. +````{admonition} **Example:** *PlayMovie* defines the playing a movie on a computer screen. **Short form:**
> *(Definition/PlayMovie, (Visual-presentation, Movie, Computer-screen))* @@ -55,13 +55,12 @@ The following example defines the *PlayMovie* term. ```` -The placeholder form of the definition is used, for example, -to annotate an experimental parameter whose value is selected -at random for each occurrence. -The annotator can use a single definition name and just substitute the value -for each occurrence. +The next example gives a definition that uses a placeholder representing a presentation +rate, for example, to annotate events in which a presentation rate is varied +at random. Usually the specific value substituted for the `#` will come from +one of the columns in the `events.tsv` file. -````{admonition} **Example:** Value definition to annotate the rate of visual presentation. +````{admonition} **Example:** Use definition with placeholder to annotate a variable presentation rate. **Short form:** > *(Definition/PresentationRate/#,* @@ -71,34 +70,56 @@ for each occurrence. > *(Property/Organizational-property/Definition/PresentationRate/#,* > *(Property/Sensory-property/Sensory-presentation/Visual-presentation,* > *Property/Task-property/Task-event-role/Experimental-stimulus,* -> *Data-property/Data-value/Spatiotemporal-value/Rate-of-change/Temporal-rate/#))* +> *Data-property/Data-value/Spatiotemporal-value/Rate-of-change/Temporal-rate/# Hz))* ```` + +Definitions may only appear in dummy entries of JSON sidecars and as external dictionaries. +Definitions cannot be nested. +Further, definitions must appear as top-level tag groups. + +The validation checks made by the HED validator when assembling and processing definitions +are summarized in [**Appendix B: HED errors**](Appendix_B.md#b-hed-errors). +In addition to syntax checks, which occur in early processing passes, +HED validators check that the definition names have unique definitions. +Additional checks for temporal scope are discussed in +[Chapter 5.2: Using definitions](05_Advanced_annotation.md#52-using-definitions) and +[Chapter 5.3: Temporal scope](05_Advanced_annotation.md#53-temporal-scope). + + ## 5.2. Using definitions -When a definition name such as *PlayMovie* or *PresentationRate* is used in an annotation, -the name is prefixed by *Def/* to indicate that the name represents a defined name. -In other words, *Def/PlayMovie* is shorthand for *(Visual, Movie, Screen)*. -The following summarizes *Def/* syntax rules. +This section describes how to use definitions to assist in annotation. + +### 5.2.1. The *Def* tag + +When a definition name such as `PlayMovie` or `PresentationRate` is used in an annotation, +the name is prefixed by the `Def` tag to indicate that the name represents a defined name. +In other words, `Def/PlayMovie` is shorthand for +`(Visual-presentation, Movie, Computer-screen)`. -``````{admonition} Syntax summary for *Def* +The following summarizes `Def` tag syntax rules. + +``````{admonition} Syntax summary for the Def tag: **Short forms:** - ~ *Def/XXX* - ~ *Def/XXX/#* + ~ *Def/xxx* + ~ *Def/xxx/yyy* **Long forms:** - ~ *Property/Organizational-property/Def/XXX* - ~ *Property/Organizational-property/Def/XXX/#* + ~ *Property/Organizational-property/Def/xxx* + ~ *Property/Organizational-property/Def/xxx/yyy* ````{admonition} Notes: :class: tip -1. *XXX* is the name of the definition. -2. If the *XXX/#* form is used, then the corresponding definition’s *(tag-group)* MUST contain a single `#` +1. *xxx* is the name of the definition. +2. *yyy* is the value that is substituted for the definition's placeholder if it has one. +2. If the *xxx/yyy* form is used, then the corresponding definition’s tag-group MUST contain a single `#` representing a value to be substituted for when the definition is used. ```` `````` -The following example shows how a defined name is used in annotation. + +The following example shows how `Def` is used in annotation. ````{admonition} **Example:** Use *PresentationRate* to annotate a presentation rate of 1.5 Hz. @@ -110,36 +131,53 @@ The following example shows how a defined name is used in annotation. ```` -During analysis, tools usually replace *Def/PlayMovie* with a fully expanded tag string. -Tools must retain the association of the expanded tag string with the definition name for -identification during searching and substitution. - -When a definition is expanded, the resulting tag string should include the definition -name using the *Def-expand* tag. In other words, the tools should expand the definition as -*(Def-expand/PlayMovie, Visual, Movie, Screen)*. The *Def-expand/PlayMovie* is inserted -in the definition tag group as part of the expansion to keep the association with -the original definition. - -**Usually definitions do not contain tags from the *Event* subtree.** -The standard practice is to use the elements of the *Event* subtree as top-level tags to -designate the general category of an event. This practice makes it easier for search and -analysis tools to filter events without extensive parsing. -The annotator can use tags such as *Experimental-stimulus* -(Long form: *Property/Task-property/Task-event-role/Experimental-stimulus*) -to explain the role of a particular sensory presentation element in the experiment -within the definition. - -Definitions may appear anywhere in a HED event file or in auxiliary files associating metadata -with HED tags such as JSON sidecars in BIDS datasets. Multiple definitions can be defined or -used in the same HED string annotation, but definitions cannot be nested. -Further, definitions must appear as top-level tag groups. Tools generally make a pass -through the event information to extract the definitions prior to other processing. -The validation checks made by the HED validator when assembling and processing definitions -are summarized in [Appendix B:](Appendix_B.md#b1-hed-validation-errors). +### 5.2.2. The *Def-expand* tag + +The `Def-expand` tag provides an alternative to `Def` tag in annotations. +Unlike the `Def` tag, a `Def-expand` tag must be in a tag group that includes +an inner tag group with the definition's contents. +If the definition includes a placeholder, that must be replaced with these +contents by the appropriate value. + +The following summarizes `Def-expand` tag syntax rules. + +``````{admonition} Syntax summary for the Def-expand tag: +**Short forms:** + ~ *(Def-expand/xxx, (definition-contents))* + ~ *(Def-expand/xxx/yyy, (definition-contents))* + +**Long forms:** + ~ *(Property/Organizational-property/Def-expand/xxx, (definition-contents))* + ~ *(Property/Organizational-property/Def-expand/xxx/yyy, (definition-contents))* + +````{admonition} Notes: +:class: tip +1. *xxx* is the name of the definition. +2. *yyy* is the replacement value for the `#` placeholder. +3. If the *xxx/yyy* form is used in the definition, then the replacement value (*yyy* above) +must replace placeholders both in the definition's name and its contents. +```` +`````` + +The following example shows how `Def-expand` is used in an annotation. + +````{admonition} **Example:** Use *PresentationRate* to annotate a presentation rate of 1.5 Hz. + +**Short form:** +> *(Def-expand/PresentationRate/1.5 Hz,* +> *(Visual-presentation, Experimental-stimulus, Temporal-rate/1.5 Hz))* + +**Long form:** +> *(Property/Organizational-property/Def-expand/PresentationRate/1.5 Hz,* +> *(Property/Sensory-property/Sensory-presentation/Visual-presentation,* +> *Property/Task-property/Task-event-role/Experimental-stimulus,* +> *Data-property/Data-value/Spatiotemporal-value/Rate-of-change/Temporal-rate/1.5 Hz))* + +```` +During analysis, tools may replace `Def/PlayMovie` with a fully expanded tag string. +Tools sometimes need to retain the association of the expanded tag string with the definition +name for identification during searching and substitution. -In addition to syntax checks, which occur in early processing passes, HED validators check -that names are defined before they are used as definitions. Additional checks for temporal -scope are discussed in [Section 5.3: Temporal scope](05_Advanced_annotation.md#53-temporal-scope). ## 5.3. Temporal scope @@ -155,59 +193,92 @@ HED events are assumed to be point events unless they are given an explicit temp Some events, such as the setup and initiation of the environmental controls for an experiment, may have a temporal scope that spans the entire data recording. Other events, such as the playing of a movie clip or a participant performing an action in -response to a sensory presentation, may last for seconds or minutes. Temporal scope captures -the effects of these extended events in a machine-actionable manner. -HED has two different mechanisms for expressing temporal scope: *Onset*/*Offset* and *Duration*. +response to a sensory presentation, may last for seconds or minutes. +Temporal scope captures the effects of these extended events in a machine-actionable manner. +HED has two distinct mechanisms for expressing temporal scope: `Onset`/`Offset` and `Duration`/`Delay`. +Tools can transform between one representation and the other. +However, transform from the `Duration`/`Delay` representation to the `Onset`/`Offset` +representation may require the addition of additional rows (time markers) in the events file. + +The mechanisms are summarized in the following table and discussed in more detail +in the following sections. + -### 5.3.1. *Onset* and *Offset* +| Tag | Meaning | Usage | +| ---- | ----------- | ------- | +| `Onset` | Marks start of event | Used with a `Def` tag or `Def-exand` group anchor.
The corresponding end is marked using
`Onset` or `Offset` with same anchor. | +| `Offset` | Marks end of event | Used with a `Def` tag or `Def-exand` group anchor.
Must be preceded by an `Onset`
anchored by the same definition. | +| `Inset` | Marks event intermediate pt | New in standard schema 8.2.0.
Used with a `Def` tag or `Def-exand` group anchor.
Must be within the event markers
for an `Onset` marked-event with the same anchor. | +| `Duration ` | Marks end of an event. | Doesn't use a definition anchor.
Starts at the current event marker unless `Delay`.
If `Delay` included, start = current marker + delay.
The offset = start + duration. | +| `Delay` | Marks delayed onset. | Doesn't use a definition anchor.
If no `Duration`, treated as point event.
Commonly for delayed response times. | +| `Event-context` | Context of ongoing events. | Should only be inserted by tools.
Each unique event marker can have
only one `Event-context` group.| -The most direct HED method of specifies scoped events by combining *Onset* and *Offset* tags with defined names. +All of these tags must appear in a `topLevelTagGroup`, which implies that they can't be nested. +`Delay` and `Duration` will not be fully supported until HED standard schema version 8.2.0. + +The `Inset` tag will also not be included until HED standard schema version 8.2.0, +but is listed here for completeness. + +### 5.3.1. Using `Onset` and `Offset` + +The most direct HED method of specifying scoped events combines +`Onset` and `Offset` tags with defined names. Using this method, an event with temporal scope actually corresponds to two point events. -The initiation event is tagged by a *(Def/XXX, Onset)* where *XXX* is a defined name. -The end of the event’s temporal scope is marked either by a *(Def/XXX, Offset)* or by -another *(Def/XXX, Onset)*. +The initiation event is tagged by a `(Def/xxx, Onset)` where `xxx` is a defined name. +The end of the event’s temporal scope is marked either by a `(Def/xxx, Offset)` or by +another `(Def/xxx, Onset)`. The `Def/xxx` is said to **anchor** the definition. +The `Onset` tag group may contain an additional internal tag group in addition to the +anchor `Def` tag. This internal tag group usually contains annotations specific +to this instance of the event. As with all HED tags and groups, order does not matter. Event initiations identified by definitions with placeholders are handled similarly. -Suppose the initiation event is tagged by a *(Def/XXX/YYY, Onset)* where *XXX* -is a defined name and *YYY* is the value substituted for the '#' placeholder. -The end of this event's temporal scope is marked either by *(Def/XXX/YYY, Offset)* or by -another *(Def/XXX/YYY, Onset)*. A subsequent *(Def/XXX/ZZZ, Onset)* where *YYY* and *ZZZ* -are different is treated as a completely distinct temporal event. +Suppose the initiation event is tagged by a `(Def/xxx/yyy, Onset)` where `xxx` +is a defined name and `yyy` is the value substituted for the `#` placeholder. +The end of this event's temporal scope is marked either by `(Def/xxx/yyy, Offset)` or by +another `(Def/xxx/yyy, Onset)`. +An intervening `(Def/xxx/zzz, Onset)`, where `yyy` and `zzz` +are different, is treated as a completely distinct temporal event. -Table 5.3 summarizes *Onset* and *Offset* usage. +The following table summarizes `Onset` and `Offset` usage. +**Note**: A `Def-expand/xxx` tag group can be used +interchangeably with the `Def/xxx`. -``````{admonition} **Syntax summary for *Onset* and *Offset*.** + +``````{admonition} **Syntax summary for Onset and Offset.** **Short forms:** - ~ *(Def/XXX, Onset, (tag-group))* - ~ *(Def/XXX/#, Onset, (tag-group))* - ~ *(Def/XXX, Offset)* - ~ *(Def/XXX/#, Offset)* + ~ *(Def/xxx, Onset, (tag-group))* + ~ *(Def/xxx/yyy, Onset, (tag-group))* + ~ *(Def/xxx, Offset)* + ~ *(Def/xxx/yyy, Offset)* **Long forms:** - ~ *(Property/Organizational-property/Def/XXX,* + ~ *(Property/Organizational-property/Def/xxx,* *Property/Data-property/Data-marker/Temporal-marker/Onset, (tag-group)* - ~ *(Property/Organizational-property/Def/XXX/#,* + ~ *(Property/Organizational-property/Def/xxx/#,* *Property/Data-property/Data-marker/Temporal-marker/Onset, (tag-group)* - ~ *(Property/Organizational-property/Def/XXX, Property/Data-property/Data-marker/Temporal-marker/Offset)* - ~ *(Property/Organizational-property/Def/XXX/#, Property/Data-property/Data-marker/Temporal-marker/Offset)* + ~ *(Property/Organizational-property/Def/xxx, Property/Data-property/Data-marker/Temporal-marker/Offset)* + ~ *(Property/Organizational-property/Def/xxx/#, Property/Data-property/Data-marker/Temporal-marker/Offset)* ````{admonition} Notes: :class: tip -1. *XXX* is the name of the definition. -2. The *(tag-group)* is optional. -3. The additional tag-group is only in effect for that particular scoped event - and not for all *XXX*. -4. If the *Def/XXX/#* form is used, the `#` must be replaced by an actual value. -5. The entire definition identifier *Def/XXX/#*, including the value substituted for the `#`, +1. *xxx* is the name of the definition anchoring the scoped event. +2. *yyy* is the value substituted for a definition's placeholder if it has one. +3. The *(tag-group)* contains optional tags specific to that temporal event. +This tag group is not the tag group specifying the contents of the definition.. +4. The additional tag-group is only in effect for that particular scoped event + and not for all events anchored by *Def/xxx*. +5. If the *Def/xxx/#* form is used, the `#` must be replaced by an actual value. +6. The entire definition identifier *Def/xxx/#*, including the value substituted for the `#`, is used as the anchor for temporal scope. ```` `````` -For example, the *PlayMovie* definition of the previous section just defines the playing of a -movie clip on the screen. The *(tag-group)* might include tags identifying which clip is -playing in this instance. This syntax allows one definition name to be used to represent the +For example, the `PlayMovie` definition of the previous section just defines the playing of a +movie clip on the screen. +The *(tag-group)* might include tags identifying which clip is playing in this instance. +This syntax allows one definition name to be used to represent the playing of different clips. ````{admonition} **Example:** The playing of a Star Wars clip using *PlayMovie*. @@ -238,19 +309,19 @@ playing of different clips. > *Data-property/Data-marker/Temporal-marker/Offset)* ```` -The *PlayMovie* scoped event type can be reused to annotate the playing of other movie clips. -However, scoped events with the same defined name (e.g., *PlayMovie*) cannot be nested. -The temporal scope of a *PlayMovie* event ends with a *PlayMovie* offset or with the -onset of another *PlayMovie* event. +The `PlayMovie` scoped event type can be reused to annotate the playing of other movie clips. +However, scoped events with the same defined name (e.g., `PlayMovie`) cannot be nested. +The temporal scope of a `PlayMovie` event ends with a `PlayMovie` offset or with the +onset of another `PlayMovie` event. -In the previous example, the *PlayMovie* defined name "anchors" the temporal scope, -and the appearance of another *Def/PlayMovie* indicates the previous movie has ceased. -The *Label* tag identifies the particular movie but does not affect the *Onset*/*Offset* +In the previous example, the `Def/PlayMovie` "anchors" the temporal scope, +and the appearance of another `Def/PlayMovie` indicates the previous movie has ceased. +The `Label` tag identifies the particular movie but does not affect the `Onset`/`Offset` determination. If you want to have interleaved movies playing, use definitions with placeholder values as shown in the next example. The example assumes a definition -*Definition/MyPlayMovie/#* exists. +`Definition/MyPlayMovie/#` exists. ````{admonition} **Example:** The interleaved playing of Star Wars and Forrest Gump. @@ -276,103 +347,174 @@ placeholder values as shown in the next example. The example assumes a definitio Because tools need to have the definitions in hand when fully expanding during validation and analysis, tools must gather applicable definitions before final processing. -Library functions in Python, Matlab, and JavaScript are being developed to support -gathering of definitions and the expansion. +Library functions in Python, Matlab, and JavaScript are available to support +gathering of definitions and the expansion. +These definitions may be given in JSON sidecars or provided externally. -### 5.3.2. *Duration* +### 5.3.2. Using `Duration` -The *Duration* tag is an alternative method for specifying an event with temporal scope. -The start of the temporal scope is the event in which the *Duration* tag appears. +The `Duration` tag is an alternative method for specifying an event with temporal scope. +The start of the temporal scope is the event in which the `Duration` tag appears. The end of the temporal scope is implicit and may not coincide with an actual event -appearing in the recording. Instead, tools calculate when the scope ends in the data recording. +appearing in the recording. +Instead, tools calculate when the scope ends (i.e., the event offset) by +adding the value of the duration to the onset of the event marker associated +with that `Duration` tag. As with all HED tags and groups, order does not matter. + +The following table summaries the syntax for `Duration`. -*Duration* tags do not need a defined label. *Duration* may be grouped with tags representing -the additional information associated with the temporal scope of that event. -This grouping usually does not include tags from the *Event* rooted tree. +``````{admonition} **Syntax summary for Duration.** +**Short forms:** + ~ *(Duration/xxx, (tag-group))* + ~ *(Duration/xxx, Delay/yyy, (tag-group))* + +**Long forms:** + ~ *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Duration/xxx,* + *(tag-group)* + ~ *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Duration/xxx,* + *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Delay/yyy,* + *(tag-group))* + +````{admonition} Notes: +:class: tip +1. *xxx* is a time value for the duration. +2. *yyy* is a time value for the delay if given. +2. The *(tag-group)* contains the additional tags specific to the temporal event whose duration is specified. + +```` +`````` + +`Duration` tags do not use a definition anchor. +`Duration` should be grouped with tags representing additional information associated +with the temporal scope of that event. + +The `Duration` tag must appear in a top level tag +group that may include an additional `Delay` tag. +If the `Duration` appears with `Delay`, the end of the temporal event is the onset of the current event plus the delay value plus the duration value. -````{admonition} **Example:** Use *Duration* for the playing of a 2-s movie clip of Star Wars. +Several events with temporal-scopes defined by `Duration` tag groups +may appear in the annotations associated with the same event marker. + +````{admonition} **Example:** Use the Duration tag to annotate the playing of a 2-s movie clip of Star Wars. **Short form:** -> *Sensory-event,* -> *(Duration/2 s, Visual-presentation, (Movie, Label/StarWars), Computer-screen)* +> *(Duration/2 s, (Sensory-event, Visual-presentation, (Movie, Label/StarWars)))* -**Long form:** -> *Event/Sensory-event,* +**Long form:** > *(Property/Data-value/Spatiotemporal-value/Temporal-value/Duration/2 s,* +> *(Event/Sensory-event,* > *Property/Sensory-property/Sensory-presentation/Visual-presentation,* > *(Item/Object/Man-made-object/Media/Visualization/Movie,* -> *Property/Informational-property/Label/StarWars),* -> *Item/Object/Man-made-object/Device/IO-device/Output-device/Display-device/Computer-screen,* -> *Property/Informational-property/Description/Play a movie clip for 2 s.)* +> *Property/Informational-property/Label/StarWars)))* ```` -The *Duration* tag is convenient because its use does not require a *Definition*. The *Duration* -tag has the same effect on event context as the onset/offset mechanism explained in -the previous sections. However, the ending time point of -events whose temporal scope is defined with *Duration* is not marked by an explicit event in the data -recording. This has distinct disadvantages for analysis if the offset is expected to elicit a -neural response, which is the case for most events involving visual or auditory presentations. +The `Duration` tag has the same effect on event context as the +`Onset`/`Offset` mechanism explained in +[**5.5. Event contexts**](./05_Advanced_annotation.md#55-event-contexts) +The `Duration` tag is convenient because its use does not require a definition. +However, the ending time point of events whose temporal scope is defined +with `Duration` is not marked by an explicit event in the data recording. +This has distinct disadvantages for analysis if the offset is expected to elicit a +neural response, which is the case for many events involving visual or auditory presentations. +The use of the `Duration` tag will not be fully supported by validators until HED +standard schema version 8.2.0. -### 5.3.3. Temporal offsets with *Delay* +### 5.3.3. Using `Delay` -The *Delay* tag is grouped with a set of tags to indicate that the associated tag-group is +The `Delay` tag is grouped with an inner tag group to indicate that the associated tag-group is actually an implicit event that occurs at a time offset from the current event. -A typical use case is when the user response time to a stimulus is recorded as a -delay time relative to the onset of the corresponding stimulus event. This strategy is -convenient for some time-locked analyses. HED tools could be developed to support the -expansion of delayed events into actual events in the event stream, provided delays were -consistently provided as signed numerical values relative to the anchor onset. +`Delay` tags do not use a definition anchor. + +If the tag group containing the `Delay` also contains a `Duration` tag, +then the tag group represents an event with temporal extent. +Otherwise, it is considered a point event. +As with all HED tags and groups, order does not matter. + +The following table summarizes the syntax for `Delay`. + +``````{admonition} **Syntax summary for Delay.** +**Short forms:** + ~ *(Delay/xxx, (tag-group))* + ~ *(Delay/xxx, Duration/yyy, (tag-group))* + +**Long forms:** + ~ *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Delay/xxx,* + *(tag-group)* + ~ *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Duration/xxx,* + *(Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Delay/yyy,* + *(tag-group))* + +````{admonition} Notes: +:class: tip +1. *xxx* is a time value for the duration. +2. *yyy* is a time value for the delay if given. +2. The *(tag-group)* contains the additional tags specific to the temporal event whose duration is specified. + +```` +`````` + + +A typical use case for `Delay` is when a secondary stimulus appears offset from +the first. A typical use case for `Delay` combined with `Duration` is the encoding +of a participant response, where the reaction time is measured relative to +a secondary stimulus (such as a 'go'). + + In the following example, a trial consists of the presentation of a cross in the center of the screen. The participant responds with a button press upon seeing the cross. The response time of the button push is recorded relative to the stimulus presentation as part of the stimulus event. -````{admonition} **Example:** Use *Delay* for offset events. +````{admonition} **Example:** Use the delay mechanism for a participant response. **Short form:** -> *Sensory-event, Experimental-stimulus, Visual-presentation,* -> *(Cross, (Center-of, Computer-screen)),* -> *(Agent-action, Delay/2.83 ms, (Participant-response, (Press, Mouse-button)))* +> *(Sensory-event, (Experimental-stimulus, Visual-presentation, Cross))* +> *(Delay/2.83 ms, (Agent-action, Participant-response, (Press, Mouse-button)))* **Long form:** -> *Event/Sensory-event,* +> *(Event/Sensory-event,* > *Property/Task-property/Task-event-role/Experimental-stimulus,* > *Property/Sensory-property/Sensory-presentation/Visual-presentation,* -> *(Item/Object/Geometric-object/2D-shape/Cross,* -> *(Relation/Spatial-relation/Center-of,* -> *Item/Object/Man-made-object/Device/IO-device/Output-device/Display-device/Computer-screen)),* -> *(Event/Agent-action,* -> *Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Delay/2.83 ms,* +> *(Item/Object/Geometric-object/2D-shape/Cross)),* +> (*Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Delay/2.83 ms,* +> *(Event/Agent-action,* > *(Property/Task-property/Task-event-role/Participant-response,* > *(Action/Move/Move-body-part/Move-upper-extremity/Press/,* > *Item/Object/Man-made-object/Device/IO-device/Input-device/Computer-mouse/Mouse-button))),* -> *Property/Informational-property/Description/A cross is displayed* -> *in the center of the screen and the participant responds by pushing a button.* ```` -Notice that the *Agent-action* tag from the *Event* subtree is included in the *Delay* tag-group. -This allows tools to identify this tag-group as representing a distinct event. -For BIDS datasets, such response delays would be in value columns of the `_events.tsv` +Notice that the `Agent-action` tag from the `Event` subtree is +included in the `Delay` tag-group. +This allows tools to identify this tag group as a distinct event. +For BIDS datasets, such response delays would be recorded in a column of the `events.tsv` event files. The HED annotation for the JSON sidecar corresponding to these files would contain a `#`. At HED expansion time, tools replace the `#` with the column value (2.83) corresponding to each event. +The `Delay` tag can also be used in the same top level tag group as the `Duration` tag to +define an event with temporal extent. +HED tools are being developed to support the expansion of delayed events to have their +own event markers without the delay tag. +However, use of the `Delay` tag will not be fully supported by validators until HED +standard schema version 8.2.0. ## 5.4. Event streams -An event stream is a sequence of events in a data recording. The most obvious event stream -is the sequence consisting of all the events in the recording, but there are many other -possible streams such as the stream consisting of all sensory events or the stream consisting -of all participant response events. +An event stream is a sequence of events in a data recording. +The most obvious event stream is the sequence consisting of all the events in the recording, +but there are many other possible streams such as the stream consisting o +f all sensory events or the stream consisting of all participant response events. -Event streams can be identified and tagged using the *Event-stream* tag, allowing annotators +Event streams can be identified and tagged using the `Event-stream` tag, allowing annotators to more easily identify subsets of events and interrelationships of events within those event -sequences. An event having the tag *Event-stream/XXX* is part of event stream XXX. +sequences. + +An event having the tag `Event-stream/xxx` indicates that event or marker is part of event stream `xxx`. ````{admonition} **Example:** Tag a face event as part of the *Face-stream* event stream. @@ -391,76 +533,91 @@ sequences. An event having the tag *Event-stream/XXX* is part of event stream XX Using a tag to identify an event stream makes it easier for downstream tools to compute relationships among subsets of events. -## 5.5. Event context +**Note:** Event streams are still under development. + +## 5.5. Event contexts Event annotations generally focus on describing what happened at the instant an event was initiated. However, the details of the setting in which the event occurs also influence neural -responses. For the *PlayMovie* example of the previous section, events that occur between the -*Onset* and *Offset* pairs for *PlayMovie* should inherit the information that a particular movie -is playing without requiring the user to explicitly enter those tags for every intervening event. +responses. For the `PlayMovie` example of the previous section, +events that occur between the `Onset` and `Offset` pairs for `PlayMovie` should +inherit the information that a particular movie is playing without requiring +the user to explicitly enter those tags for every intervening event. The process of event context mapping should be deferred until analysis time because other events might be added to the event file after the initial annotation of the recording. For example, a user might run a tool to mark blink or other features as events prior -to doing other analyses. HED uses the *Event-context* tag to accomplish the required context mapping. +to doing other analyses. +HED uses the `Event-context` tag to accomplish the required context mapping. -In normal usage, **the *Event-context* tag is not used directly by annotators**. -Rather, tools insert the *Event-context* tag at analysis time to + +In normal usage, **the `Event-context` tag is not used directly by annotators**. +Rather, tools insert the `Event-context` tag at analysis time to handle the implicit context created by enduring or scoped events. However, annotators may use the tag when an event has explicit context information -that must be accounted for. +that must be accounted for. +Tools are available to insert the appropriate `Event-context` at analysis time. +The `Event-context` has the `unique` attribute, +implying that only one `Event-context` tag group may appear in the assembled +HED annotation corresponding to each time-marker value. ``````{admonition} **Syntax summary for *Event-context*.** **Short form:** - ~ *(Event-context, other-tags)* + ~ *(Event-context, other-tag-groups)* **Long form:** - ~ *(Property/Organizational-property/Event-context, other-tags)* + ~ *(Property/Organizational-property/Event-context, other-tag-groups)* ````{admonition} Notes: :class: tip -1. An event can have at most one *Event-context*. -2. HED-compliant analysis tools should insert the annotations describing each temporally -scoped event into the *Event-context* tag group of the events within its +1. The `Event-context` may only appear in a top-level tag group of an assembled HED string. +2. An event can have at most one `Event-context` tag group in its assembled HED annotation. +3. HED-compliant analysis tools should insert the annotations describing each temporally +scoped event into the `Event-context` tag group of the events within its temporal scope during final assembly before analysis of the event. -3. Other task-event relationships may be inserted as tags within the *Event-context* -tag group either at annotation time or analysis time. +4. Each of these internal annotations should be in a group, indicating that they represent a distinct event process. ```` `````` ## 5.6. Experimental design Most experiments are conducted by varying certain aspects of the experiment and measuring the -resulting responses while carefully controlling other aspects. The intention of the experiment -is annotated using the HED *Condition-variable*, *Control-variable*, and *Indicator-variable* -tags. +resulting responses while carefully controlling other aspects. +The intention of the experiment is annotated using the HED `Condition-variable`, +`Control-variable`, and `Indicator-variable` tags. -The *Condition-variable* tag is used to mark the independent variables of the experiment +The `Condition-variable` tag is used to mark the independent variables of the experiment -- those aspects of an experiment that are explicitly varied in order to observe an effect -or to control bias. Contrasts, a term that appears in the neuroscience and statistical -literature, are examples of experimental conditions, as are factors in experimental designs. - -The *Indicator-variable* tag is used to mark quantities that are explicitly measured or -calculated to evaluate the effect of varying the experimental conditions. Indicator variables -often fall into the *Event/Data-feature* category. Sometimes the values of these data features -are explicitly annotated as events. Researchers should provide a sufficiently detailed +or to control bias. +Contrasts, a term that appears in the neuroscience and statistical literature, +are examples of experimental conditions as are factors in experimental designs. + +The `Indicator-variable` tag is used to mark quantities that are explicitly measured or +calculated to evaluate the effect of varying the experimental conditions. +Indicator variables often fall into the `Event/Data-feature` category. +Sometimes the values of these data features are explicitly annotated as events. +Researchers should provide a sufficiently detailed description of how to compute these data features so that they can be reproduced. -The *Control-variable* tag represents an aspect of the experiment that is held constant +The `Control-variable` tag represents an aspect of the experiment that is held constant throughout the experiment, often to remove variability. -Researchers should use *Condition-variable*, *Control-variable*, and *Indicator-variable* tags to -capture the experiment intent and organization in as much detail as possible. Consistent and -detailed description allows tools to extract the experiment design from the data in a -machine-actionable form. Good tagging processes suggest creating definitions with understandable -names to define these aspects of the dataset. This promotes easy searching and extraction for +Researchers should use `Condition-variable`, `Control-variable`, +and `Indicator-variable` tags to capture the experiment intent and +organization in as much detail as possible. +Consistent and detailed description allows tools to extract the experiment design +from the data in a machine-actionable form. +Good tagging processes suggest creating definitions with understandable +names to define these aspects of the dataset. +This promotes easy searching and extraction for analyses such as regression or other modeling of the experimental design. -To illustrate the use of condition-variables to document experiment design, consider an -experiment in which one of the conditions is the rate of presentation of images displayed on the -screen. The experiment design compares responses under slow and fast image presentation rate -conditions. To avoid unfortunate resonances due to a poor choice of rates, the “slow” and “fast” +To illustrate the use of condition-variables to document experiment design, +consider an experiment in which one of the conditions is the rate of +presentation of images displayed on the screen. +The experiment design compares responses under slow and fast image presentation rate conditions. +To avoid unfortunate resonances due to a poor choice of rates, the “slow” and “fast” rate conditions each consist of three possible rates. Selection among the three eligible rates for the given condition is done randomly. @@ -495,10 +652,11 @@ the group. ```` -*Organizational* tags such as *Condition-variable* are often used in the tag-groups of -temporally scoped events. The *Onset* of such an event represents the start of the -*Condition-variable*. The corresponding *Offset* marks the end of the period during which -this condition is in effect. This type of annotation makes it straightforward to extract +`Organizational-property` tags such as `Condition-variable` are often +used in the tag-groups of temporally scoped events. +The `Onset` of such an event represents the start of the`Condition-variable`. +The corresponding `Offset` marks the end of the period during which this condition is in effect. +This type of annotation makes it straightforward to extract the experimental design from the events. ````{admonition} **Example:** Annotation using *SlowPresentation* condition. @@ -512,9 +670,9 @@ the experimental design from the events. > *Property/Data-property/Data-marker/Temporal-marker/Onset)* ```` -During analysis, the *Def* tags will be replaced with the actual definition’s tag group -with an included *Def-expand* tag giving the definition’s name. Note: expansion is done -by tools at analysis time. +During analysis, the `Def` tags may be replaced with the actual definition’s tag group +with an included `Def-expand` tag giving the definition’s name. +Note: expansion is done by tools at analysis time. ````{admonition} **Example:** Expanded form of the previous example. @@ -536,32 +694,31 @@ Event/Sensory-event,* Properly annotated condition variables and response variables can allow researchers to understand the details of the experiment design and perform analyses such as ANOVA (ANalysis Of VAriance) or regression to extract the dependence of responses on the -condition variables. The time-organization of an experiment can be annotated with the -Organizational tags *Time-block* and *Task-trial* and used for visualizations of experimental -layout. +condition variables. +The time-organization of an experiment can be annotated with the +Organizational tags `Time-block` and `Task-trial` and used for +visualizations of experimental layout. A typical experiment usually consists of a sequence of subject task-related activities interspersed with rest periods and/or off-line activities such as filling in a survey. -The *Time-block* tag is used to mark a contiguous portion of the data recording during -which some aspect of the experiment conditions is fixed. *Time-block* tags can be used -to represent temporal organization in a manner similar to the way *Condition-variable* +The `Time-block` tag is used to mark a contiguous portion of the data recording during +which some aspect of the experiment conditions is fixed. +`Time-block` tags can be used to represent temporal organization +in a manner similar to the way `Condition-variable` tags are used to represent factors in an experiment design. - ## 5.7. Specialized annotation -A significant problem with schema design is term accretion. Each type of experiment will have -specific terms or concepts that are important for the experiment’s purpose or design but are -not widely applicable to other experiments. Schema designers might be tempted to add terms -specific to familiar experiments or for annotators to extend the schema tree with terms -specific to their experiments during annotation. -The *Parameter* tag and its children *Parameter-label* and *Parameter-value* are general-purpose -tags designed to fill the missing term gap. They can be used to tag important specific concepts +### 5.7.1. Parameter tags + +The `Parameter` tag and its children `Parameter-label` and `Parameter-value` +are general-purpose tags designed to fill the missing term gap. +They can be used to tag important specific concepts in a way that can be used for automated tools without triggering problems of accretion. For example, consider the problem of how to annotate repetition lag between successive -presentations of a particular face image. There are several ways to annotate, but annotating -with *Parameter* is a good compromise between clarity and machine-actionability. +presentations of a particular face image. +There are several ways to annotate, but annotating with `Parameter` is a good compromise between clarity and machine-actionability. ````{admonition} **Example:** Annotate face repetition and interval using *Parameter-value*. @@ -571,7 +728,7 @@ with *Parameter* is a good compromise between clarity and machine-actionability. ```` Annotate the number of times a face image has appeared and the interval since last time this -face was shown using more specific tags for the value *Parameter-value*: +face was shown using more specific tags for the value `Parameter-value`: ````{admonition} **Example:** Annotate the number of times a face image has appeared. @@ -595,3 +752,5 @@ and their values, while statistical tools can look for dependencies on these var parameter names are designed to be self-documenting. Parameters are often used for derived values such as response times that are used as indicator variables in the experiment. They are also sometimes used as part of control variable definitions. + +**Note:** Parameters and related annotations are still under development. \ No newline at end of file diff --git a/docs/source/06_Infrastructure.md b/docs/source/06_Infrastructure.md deleted file mode 100644 index 750e0c62..00000000 --- a/docs/source/06_Infrastructure.md +++ /dev/null @@ -1,250 +0,0 @@ -# 6. Infrastructure - -This section gives an overview of the HED infrastructure. Additional details and links to specific -tools are available in (Tools.md)[Tools.md]. - - -## 6.1. Short and long forms - -Tools that are third-generation HED-compliant must be able to handle both short-form and -long-form versions of HED strings. Analysis tools often need to transform all HED tags to long -form before processing. To this end, mapping functions are being developed in Python, Matlab, -and JavaScript. These libraries also provide mapping from long form to short form. -As illustrated in the previous sections, the short form is much more readable and compact. - -## 6.2. File formats - -Dataset events are often represented using spreadsheets either in `.tsv` or Excel format. -The rows of each spreadsheet correspond to events, while the columns contain identifying -information pertaining to the events. The first row of each spreadsheet usually contains -column names that document what each column represents. Usually one column contains the -time of the event. Other columns may contain categorical values, other values, or HED strings. - -Categorical column values are chosen from a small, explicitly defined subset. -Value columns may contain numeric values or other types of values such as file names. -HED tools assume that event files are spreadsheets, either in BIDS (`.tsv`) format or -Excel format. - -The HED tools require that each column of an event file contains items of the same class -(categorical or value) and that value columns contain items of the same basic type. Files not -satisfying these requirements may need additional processing before being handled by HED tools. - -### 6.2.1. BIDS event files -[BIDS (Brain Imaging Data Structure)](https://bids.neuroimaging.io/is ) is a specification -along with supporting tools for organizing and describing brain imaging and behavioral data. -BIDS event files satisfy the criteria of the previous section. - -BIDS supports HED annotation of events. BIDS events appear in tab-separated value (`_events.tsv`) -files in various places in the dataset hierarchy. BIDS event files must have an `onset` column -and a `duration` column. The following shows an excerpt from a BIDS event file: - - -````{admonition} **Example:** Excerpt from a BIDS event file. - -``` -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 -``` -```` - -The `trial_type` column contains categorical values, while the `response_time` and `stim_file` -columns contain non-categorical values. In theory `stim_file` could be considered a categorical -column if there were just a few possible images, but this would not be common usage. -BIDS allows an optional column named `HED` to contain HED strings relevant for the event -instance. The above example does not have this column. - -Processing tools read these event files and create their own event representation. -The Python version of HEDTools uses the Pandas `DataFrame` for its low-level representations. -For MATLAB programs, the dataset events are often held in `struct` arrays. -In EEGLAB, for example, the events for an EEG data recording appear in the `EEG.event` -structure array. The time of the event is given in frames in the `EEG.event.latency` -field for data that has not been epoched. - - -### 6.2.2. BIDS sidecars - -BIDS also recommends data dictionaries in the form of JSON sidecars to document -the meaning of the data in the event files.HEDTools assume -that dictionaries for event metadata are contained in BIDS-compatible sidecars. - -BIDS allows the tagging of both categorical and non-categorical columns in these sidecars -as explained in the [HED appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/03-hed.md) of the BIDS -specification. Internally, EEGLAB and CTAGGER use mapping objects that are stored in the EEG -structure. However, these mapping options can be written to or read from BIDS JSON sidecars. - -Each event file spreadsheet column containing categorical values may also have a categorical -dictionary that documents the meaning of the data in that column. HED also provides for the HED -tagging of non-categorical columns as explained below. The following example shows the JSON -sidecar format for annotating the same event file of the previous section. The `"HED"` key -for the `"trial_type"` column indexes the categorical dictionary associated with the -`trial_type` column in the event file. - -````{admonition} **Example:** JSON sidecar for annotating the columns of an event file. - -```json -{ - "trial_type": { - "LongName": "Event category", - "Description": "Indicator of type of action that is expected.", - "Levels": { - "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, Red), (Computer-screen, Center-of), Description/A red square is displayed to indicate starting.", - "stop": "Sensory-event, Visual-presentation, (Square, Blue), (Computer-screen, Center-of), Description/A blue square is displayed to indicate stopping." - } - }, - "response_time": { - "LongName": "Response time after stimulus", - "Description": "Time from stimulus until subject presses button.", - "Units": "ms", - "HED": "(Delay/# ms, Agent-action, Experiment-participant, Press, Mouse-button, Description/Time from stimulus until subject presses button)" - }, - "stim_file": { - "LongName": "Stimulus file name", - "Description": "Relative path of the stimulus image file", - "HED": "Pathname/#, Description/Relative path of the stimulus image file" - } -} -``` -```` - -Non-categorical columns such as `response_time` and `stim_file` have a dictionary “HED” value -consisting of a HED string rather than another dictionary. This HED string must have a single `#` -placeholder. The corresponding value in the spreadsheet column replaces the `#` when the event -annotation is assembled. - -### 6.2.3. HED version in BIDS - -The HED version is included as the value of the `"HEDVersion"` key in the -`dataset_description.json` metadata file located at the top level in a BIDS dataset. -HEDTools retrieve the appropriate HED schema directly from GitHub when needed. -The following examples shows how a BIDS user specifies that HED version 8.0.0 is -used for a dataset called "A wonderful experiment". BIDS locates the appropriate -version of the schema on GitHub and downloads it during the validation process. -The following examples shows a simple `dataset_description.json`. - -````{admonition} **Example:** BIDS dataset description using HED version 8.0.0. - -```json -{ - "Name": "A wonderful experiment", - "BIDSVersion": "1.4.0", - "HEDVersion": "8.0.0" -} -``` -```` - - - -## 6.3. Levels of validation - -Validation of HED annotations is an essential step in using HED for large-scale, reproducible -analysis. Third-generation HED encourages a more detailed and useful documentation of events -and provides mechanisms for mapping the interrelationships of events and task intent. -The additional annotation power also requires more extensive validation to assure consistency -across annotations. HED-validators are provided in both Python and JavaScript. -There is also a MATLAB wrapper for the Python validator functions. - -There are five levels of validation: tag level, string level, dictionary level, event level, -and data-recording level. Previous generations of HED only required validation at the first -four of these. Since third-generation HED can document relationships across events, -it also requires an additional level to validate cross-event relationships. -Validation can also be categorized as syntactic or semantic. Syntactic validation, -which occurs mainly at the HED tag and HED string levels, tests that the tags are -properly formed, independently of the HED schema or purpose of the tags. Semantic -validation tests that the tags are used correctly and that they comply with the relevant schema. -Syntactic validation is usually done initially during the parsing of the HED strings -into HED tags. - - -### 6.3.1. Tag validation - -HED tag level validation checks each individual HED tag against its associated schema. -The long-form tag must be in the schema. HED tags that take a value (have a `#` child in the -schema) must have values that only contain appropriate characters. If the HED tag `#` has a -*unitClass* attribute, the units must comply with those of the specified *unitClass*. -If the HED tag has additional nodes beyond the leaf node in the schema, the *extensionAllowed* -attribute must be in effect for the leaf node. - - -### 6.3.2. String validation - -HED string level validation focuses on the proper formation of HED strings and tag-groups -within the HED strings. Syntactic HED string validation includes matching of parentheses and -proper delimiting of HED tags by commas. Semantic HED string validation includes verification -that HED definitions have the proper form. - - -### 6.3.3. Sidecar validation - -HED dictionary validation assumes that the dictionaries have been written in the JSON format -of [BIDS sidecars](https://bids-specification.readthedocs.io/en/stable/appendices/hed.html). -The validation is similar to HED string evaluation, but the error messages are keyed to -dictionary location rather than to line numbers in the event file or spreadsheet. -The validator checks that there is exactly one `#` in the HED string annotation associated -with each non-categorical column. The `#` placeholder should correspond -to a `#` in the HED schema, indicating that the parent tag expects a value. -If the placeholder is followed by a unit designator, the validator checks that -these units are consistent with the unit class of the -corresponding `#` in the schema. The units are not mandatory. - - -### 6.3.4. Event validation - -Dataset formats such as BIDS (Brain Imaging Data Structure) allow users to provide HED tags -in multiple places. For example, if a study uses local codes to represent different types of -events, the dataset specification often allows users to use the local codes when listing the -events and then provide some format of dictionary mapping local codes to tags. -During event level validation, all of these tags must be assembled into a HED string -representing the full HED annotation for that event. - -Several tag attributes are validated at this stage. The expanded event-level HED string -annotating an event must include all tags with the *required* attribute and only one copy -of each tag with the *unique* attribute. - - -### 6.3.5. Recording validation - -The introduction of definitions and temporal scope has added additional complexity -to validation. Instead of being able to validate the HED string for each event individually, -third generation HED validators must also check consistency across all events in the -data-recording. This validation requires multiple passes through of the assembled HED tags -associated with the data-recording. - -Since *Definition* tags can appear anywhere in the event annotations for a data recording, -an initial scan must be made to assemble all definitions for a data recording and -to make sure that the definition names are unique. - -To validate temporal scope, the validator must assure that each *Onset* and *Offset* tag -is associated with an appropriately defined label. The validator must also check to make -sure that *Onset* and *Offset* tags are properly matched within the data recording. - - -## 6.4. Analysis tools - -Third-generation HED analysis tools also require some additional infrastructure. These tools -should call the HED libraries to fully expand the tags for a data recording before doing -analysis. In addition to converting all HED tags to their long form, the library tools can -remove the definitions and replace *def/* with the full tag expansion with any defined labels. - -Each event that is within the temporal scope of a scoped event, should have the scoped event -information added to the *Event-context* tag group of the intermediate event upon request. -*Delay* tag expansions as insertions of actual events should also be supported. -*Duration* tag expansion in which offset events should be inserted should also be supported. -The HED tools should provide this expansion capability as well as a standardized representation -of events in a data recording to enable tools to use a standard API for accessing tag information. - - -## 6.5. BIDS support in HED - -HED provides a JavaScript validator in the [hed-javascript](https://github.com/hed-standard/hed-javascript) repository, which is available as an installable package via [npm](https://www.npmjs.com/). -The [BIDS validator](https://github.com/bids-standard/bids-validator) -incorporates calls to this package to validate HED tags in BIDS datasets. - -The [hedtools](https://pypi.org/project/hedtools/) package includes -input functions that use [Pandas](https://pandas.pydata.org/) data frames to construct internal -representations of HED-annotated event files. - diff --git a/docs/source/06_Infrastructure_and_tools.md b/docs/source/06_Infrastructure_and_tools.md new file mode 100644 index 00000000..c18c6c81 --- /dev/null +++ b/docs/source/06_Infrastructure_and_tools.md @@ -0,0 +1,265 @@ +# 6. Infrastructure and tools + +The HED infrastructure includes libraries written in Python, Matlab, +and JavaScript that support the use of HED in validation and/or applications. +This section describes the expected behavior of the HED infrastructure and +its integration into other systems such as [**BIDS**](https://bids.neuroimaging.io/). + +In general, tools should either explicitly call HED validation to assure that the input +tag strings are valid or should make explicit that they assume the HED has already been validated. +Most tools will use the later approach. + +See [**3.2. HED annotation format**](./03_HED_formats.md#32-hed-annotation-format) +for more detailed specifications of HED formats. + +See [**4. Basic annotation**](./04_Basic_annotation.md) and +[**5. Advanced annotation**](./05_Advanced_annotation.md) for examples and usage. + +## 6.1. Basic tag handling + +HED-compliant tools should be able to a handle HED string in its equivalent forms +and using various valid syntax as described in this section. + +### 6.1.1. Tag forms + +````{warning} +HED-compliant tools should be able to handle tags in **long-form**, +**short-form** or any valid **intermediate-form**. + +```` + +Tools may assume that validated HED tags do not have leading, trailing, or +consecutive forward slashes in their names. + +In addition to being property formed, validated HED strings will correspond to +terms in the schemas under which they were validated. + +Tools should not distinguish between variations in case for the same tag term. +Only units must have their cases preserved. + +Tools may assume that the individual tags within validated HED strings have +values of the proper form and that the units, if provided, are consistent with +any unit classes + +**Note**: At this time it is not required that terms with specified unit classes +always have associated units. However, it is implicitly assumed that if +the units are omitted in this case, the value has the default units. + +See [**3.2.2. Tag forms**](./03_HED_formats.md#322-tag-forms) for more information +on tag forms. + +### 6.1.2. Parentheses and commas + +Tools may assume that validated HED strings have no duplicates, empty tags, +empty groups (parentheses enclosing only whitespace), or mismatched parentheses. + +Grouping with parentheses in HED means that the tags are associated. + +````{warning} +HED-compliant tools should be able to handle arbitrary correctly **nested parentheses** +and correctly distinguish differences in grouping. + +```` + +(tag-ordering-anchor)= +### 6.1.3. Tag ordering + +Any ordering of HED tags and HED tag groups at the same level within a HED tag group is equivalent. + +Any ordering of top-level HED tags and HED tag groups in a HED string is equivalent. + +````{warning} +HED-compliant tools should not rely on the order that HED tags appear within a string or group during processing. +```` + +### 6.1.4. Definitions + + +````{warning} +HED-compliant tools should be able to expand, shrink, or remove definitions. +```` + +HED definitions should only appear in sidecars in dummy entries +or in an accompanying definition list. +Actual `Definition` groups should not appear in the `HED` column of event files. + + +## 6.2. File-level handling + +Dataset formats such as [**BIDS**](https://bids.neuroimaging.io/) (Brain Imaging Data Structure) +allow users to provide HED tags in multiple places. +For example, BIDS dataset event files often use local codes to identify event markers +in tabular (`events.tsv`) files +and then provide dictionaries called JSON sidecars to map local codes to annotations. + +The introduction of definitions and temporal scope for HED versions >= 8.0.0 +has added additional complexity to validation and processing. +Instead of being able to validate the HED string for each event individually, +HED validators must now also check consistency across all events in the data-recording. + +Tools should make explicit whether they support temporal scope. +Tools that support temporal scope should be able to add scoped event +information to the `Event-context` tag group of the intermediate events upon request. + +Tools should make explicit whether they support insertion of actual events +for `Delay` tag expansions and for the offsets of `Duration` tags. +This information will allow analysts to call HED tools that support these operations +to appropriately modify event files as a preamble to processing +if the tool does not support these tags. + +## 6.3. HED support of BIDS + +[**BIDS**](https://bids.neuroimaging.io/) (Brain Imaging Data Structure) is a +widely-adopted specification and supporting tools for organizing and +describing brain imaging and behavioral data. + +BIDS dataset events are stored in tab-separated value files whose names end in `events.tsv`. +HED's use of tabular files and sidecars closely aligns with BIDS and its requirements. +HED has been incorporated into the BIDS standard as the mechanism for annotating +tabular files. + +### 6.3.1. BIDS tabular files + +The following shows an excerpt from a BIDS event file: + +````{admonition} **Example:** Excerpt from a BIDS event file. + +``` +onset duration trial_type response_time HED +1.2 0.6 go 1.435 Label/Starting-point, Quiet +5.6 0.6 stop 1.739 n/a +``` +```` + + +The first two columns in a BIDS events file are required to be `onset` and `duration`, respectively. +The `onset` is the time in seconds of an event marker relative to the start of its corresponding +data recording, +while the `duration` represents the duration in seconds of some aspect of the event. +The remaining columns in this event file are optional. + +BIDS reserves an optional column named `HED` to contain HED strings relevant for the event instance. +In the above example, the first row `HED` column contains `Label/Starting-point, Quiet`, +while the second row contains `n/a`, indicating that entry should be ignored. + +HED annotations can also be associated with entries in other columns of the event file +through an associated JSON sidecar as described in the next section. + +### 6.3.2. BIDS sidecars + +BIDS also recommends data dictionaries in the form of JSON sidecars to document +the meaning of the data in the event files. +HEDTools supports BIDS dataset format, where event metadata is contained +in compatibly-named sidecars. +See the [**example sidecar**](./03_HED_formats.md#3291-sidecar-entries) in Chapter 3 +for an explanation of the different sidecar entries. + +### 6.3.3. Annotation assembly + +HED tools are available to assemble the annotations associated with each row in +a tabular file using its `HED` column and the sidecar information associated +with other columns of the events file. + +For example, the annotations for the first row of the +[**example event file**](./06_Infrastructure_and_tools.md#631-bids-tabular-files) +above can be assembled using the +[**example sidecar**](./03_HED_formats.md#3291-sidecar-entries) in Chapter 3 +to give the following annotation: + +````{admonition} Example assembled HED annotation for one event marker. + +> `Sensory-event`, `Visual-presentation`, (`Square`, `Blue`), +> (`Delay/1.435 ms`, `Agent-action`, (`Experiment-participant`, (`Press`, `Mouse-button`))), +> `Label/Starting-point`, `Quiet` + +```` +The process is to look up the appropriate row annotation for each column in the sidecar and append these with an annotation in the `HED` column if available. + +### 6.3.4. HED version in BIDS + +The HED version is included as the value of the `"HEDVersion"` key in the +`dataset_description.json` metadata file located at the top level in a BIDS dataset. +HEDTools retrieve the appropriate HED schema directly from GitHub +or from locally cached versions when needed. + +The following example `dataset_description.json` specifies that HED version 8.0.0 is +used for a dataset called "A wonderful experiment". + +````{admonition} **Example:** BIDS dataset description using HED version 8.0.0. + +```json +{ + "Name": "A wonderful experiment", + "BIDSVersion": "1.4.0", + "HEDVersion": "8.0.0" +} +``` +```` + +It is possible to include library schema in the HED version specification of the +`dataset_description.json` file as shown by the following example: + +````{admonition} **Example:** BIDS dataset description using HED version 8.1.0 and score library 1.0.0. +```json + +{ + "Name": "A great experiment", + "BIDSVersion": "1.7.0", + "HEDVersion": ["8.1.0", "sc:score_1.0.0"] +} +``` +```` + +The version specification indicates that tags from the `score` library must be prefixed with `sc:` +in dataset HED annotations. + +The prefix notation (such as the `sc:` prefix for the `score` library in the previous example is required when more than one schema is used in the annotation. +However, prefixes can be used with the standard schema as well as library schemas +as illustrated by the following example. + +````{admonition} **Example:** Prefixed standard schema in BIDS dataset description version specification. + +```json + +{ + "Name": "A great experiment", + "BIDSVersion": "1.7.0", + "HEDVersion": ["st:8.1.0", "score_1.0.0"] +} +``` +```` + +For this specification tags from the standard schema must be prefixed +by `st:`, while tags from the `score` library are unprefixed. +The `sc:` and `st:` prefixes are arbitrary (usually short) alphabetic strings +chosen by the annotation and are specific to each dataset based on its +version specification. + + + +````{warning} +HED-compliant tools must be able to handle multiple schemas and prefixed +tags. +```` + + +### 6.3.5. HED in the BIDS validator + +HED provides a JavaScript validator in the [**hed-javascript**](https://github.com/hed-standard/hed-javascript) repository, which is available as an installable package via [**npm**](https://www.npmjs.com/). +The [**BIDS validator**](https://github.com/bids-standard/bids-validator) +incorporates calls to this package to validate HED tags in BIDS datasets. + +### 6.3.5. HED python tools + +The [**hedtools**](https://pypi.org/project/hedtools/) package includes +input functions that use [**Pandas**](https://pandas.pydata.org/) data frames to construct internal +representations of HED-annotated event files. + +HED schema developers generally do initial development of the schema using `.mediawiki` format. +The tools to convert schema between `.mediawiki` and `.xml` format are located +in the `hed.schema` module of the +[**hedtools**](https://github.com/hed-standard/hed-python/tree/master/hedtools) +project of the [**hed-python**](https://github.com/hed-standard/hed-python) GitHub repository. +All conversions are performed by converting the schema to a `HedSchema` object. +Then modules `wiki2xml.py` and `xml2wiki.py` provide top-level functions to perform these +conversions. \ No newline at end of file diff --git a/docs/source/07_Library_schema.md b/docs/source/07_Library_schemas.md similarity index 52% rename from docs/source/07_Library_schema.md rename to docs/source/07_Library_schemas.md index d56d0593..0cac1b04 100644 --- a/docs/source/07_Library_schema.md +++ b/docs/source/07_Library_schemas.md @@ -18,7 +18,7 @@ usable by the broader user community. Third generation HED instead introduces the concept of the **HED library schema**. To use a programming analogy, when programmers write a Python module, the resulting code -does not become part of the Python language or core library. Instead, the module becomes +does not become part of the Python language or core libraries. Instead, the module becomes part of a library used in conjunction with core modules of the programming language. Similar to the design principles imposed on function names and subclass organization in @@ -27,9 +27,9 @@ software development, HED library schemas must conform to some basic rules: ``````{admonition} Rules for HED library schema design. :class: tip -1. Library schema must be given a name containing only alphabetic chararacters. +1. A library schema must be given a name containing only alphabetic chararacters. This name must appear in the schema header line in the required format. -2. The library must use semantic versioning and follow the versioning update rules used by +2. A library library must use semantic versioning and follow the versioning update rules used by the HED standard schema. 3. Every term must be unique within the library schema and must conform to the rules for HED schema terms. @@ -38,7 +38,7 @@ should be meaningful in themselves without reference to their position in the sc 5. If possible, no schema sub-tree should have more than 7 direct subordinate sub-trees. 6. Terms that are used independently of one another should be in different sub-trees (orthogonality). 7. The schema should include the schema attributes, unit classes, unit modifiers, value classes, -and schema properties present in the standard HED schema. +and schema properties present in the HED standard schema. `````` @@ -47,9 +47,11 @@ and used, in addition to the standard HED schema. Libraries allow individual res communities to annotate details of events in experiments designed to answer questions of interest to particular research or clinical communities. Since it would be impossible to avoid naming conflicts across schema libraries that may be built in parallel by different -user communities, HED supports schema library namespaces. Users will be able to add library -tags qualified with namespace designators. All HED schemas, including library schemas, -adhere to [semantic versioning](https://semver.org/). +user communities, HED supports schema library namespaces +(the prefix notation described in the previous section). +Users will be able to add library tags qualified with namespace designators. +All HED schemas, including library schemas, +adhere to [**semantic versioning**](https://semver.org/). In general, library schema developers should include the auxiliary schema classes from the standard HED schema: the schema attributes, unit classes, unit modifiers, @@ -57,23 +59,20 @@ value classes, and schema properties. The HED tools support these auxiliary classes but in general would not support special handling of added classes beyond basic verification. -If your schema requires schema classes that are not available +If your application requires schema classes that are not available in the standard HED schema and would like these classes to be supported, -please make a request using the [**HED specification issues**](https://github.com/hed-standard/hed-specification/issues) forum. - -Please do not duplicate tags in the `Property/Informational-property` and -`Relation` subtrees, as many of these tags have specialized uses and tool support. -In particular, `Definition`, `Def`, `Def-expand` and `Event-context` should -NEVER be duplicated in a library schema. +please make a request using the [**HED examples issues**](https://github.com/hed-standard/hed-examples/issues) forum. +A schema should not duplicate tags found in the standard schema. ## 7.1. Defining a schema -A HED library schema is defined in the same way as the standard HED schema except that it has an -additional attribute name-value pair, `library="xxx"` in the schema header. We will use as an -illustration a library schema for driving. Syntax details for a library schema are similar to -those for the standard HED schema. (See [Appendix A: Schema format](Appendix_A.md#a-schema-format) -for more details). +A HED library schema is defined in the same way as the standard HED schema +except that it has an additional attribute name-value pair `library="xxx"` +in the schema header. +We will use as a library schema for driving as an illustration. +Syntax details for a library schema are similar to those for the standard HED schema. + ````{admonition} **Example:** Driving library schema (MEDIAWIKI template). @@ -101,44 +100,41 @@ and *property-specification*. ``` ```` -The schema XML file should be saved as `HED_driving_1.0.0.xml` to facilitate -specification in tools. +During annotation tags from different library schemas can +be intermixed with those of the standard schema. +Since the node names within a library must be +unique, annotators can use short form as well as fully expanded tag paths for library schema +tags as well as those from the standard HED schema. + +The schema XML file should be saved as `HED_driving_1.0.0.xml` so that tools can locate them. +The official location of HED standard and library schemas is the +[**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. ## 7.2. Schema namespaces -As part of the HED annotation process, users must associate a standard HED schema with their -datasets. -Users may also include tags from an arbitrary number of additional library schemas. -For each library schema used to annotate a data recording, -the user must associate a local -name with the appropriate library schema name and version. -Each library must be associated with a distinct local name within a recording annotations. -The local names should be strictly alphanumeric with no blanks or punctuation. - -The user must pass information about the library schema and their associated local names to -processing functions. HED uses a standard method of identifying namespace elements by prefixing -HED library schema tags with the associated local names. Tags from different library schemas can -be intermixed with those of the standard schema. Since the node names within a library must be -unique, annotators can use short form as well as fully expanded tag paths for library schema -tags as well as those from the standard HED schema. +As part of the HED annotation process, users must associate one or more +HED schemas with their datasets. +If multiple schemas are used, users must define a local prefix for +each additional schema and prefix the tags from each of these +additional schemas by their respective prefix in annotations. +The local names should be strictly alphabetic with no blanks or punctuation. +If a tag prefix is invalid in the version specification, +a schema loading error occurs. + + ````{admonition} **Example:** Driving library schema example tags. ``` -dp:Action/Drive/Change-lanes +dp:Drive-action/Change-lanes dp:Drive/Change-lanes dp:Change-lanes ``` ```` A colon (`:`) is used to separate the qualifying local name from the remainder of the tag. -Notice that *Action* also appears in the standard HED schema. Identical terms may be used -in a library schema and the standard HED schema. Use of the same term implies a similar -purpose. Library schema developers should try not to reuse terms in the standard schema -unless the intention is to convey a close or identical relationship. - -## 7.3. Attributes and classes +## 7.3. Library schema layout In addition to the specification of tags in the main part of a schema, a HED schema has sections that specify unit classes, unit modifiers, value classes, schema attributes, @@ -147,24 +143,25 @@ as follows: ### 7.3.1. Required sections -The required sections of a library schema are: the *schema-specification*, -the *unit-class-specification*, the *unit-modifier-specification*, -the *value-class-specification* section, the *schema-attribute-specification* section, -and the *property-specification*. The library schema must include all required +The required sections of a library schema are the same as those for the +standard schema. +These sections are listed in +[**3.1.2. Schema layout overview**](./03_HED_formats.md#312-schema-layout-overview). +The library schema must include all required schema sections even if the content of these sections is empty. ### 7.3.2. Relation to standard HED schema Any schema attribute, unit class, unit modifier, value class, or property used in the library schema must be specified in the appropriate section of the library schema -regardless of whether these appear in the standard HEd schema. Validators check the library +regardless of whether these appear in the standard HED schema. Validators check the library schema strictly on the basis of its own specification without reference to another schema. ### 7.3.3. Schema properties -HED only supports the schema properties listed in Table B.2: *boolProperty*, -*unitClassProperty*, *unitModifierProperty*, *unitProperty*, and *valueClassProperty*. +HED only supports the schema properties listed in +[**A.1.5. Schema properties**](./Appendix_A.md#a15-schema-properties). If the library schema uses one of these in the library schema specification, then its specification must appear in the *property-specification* section of the library schema. @@ -178,17 +175,21 @@ information for these. ### 7.3.5. Value classes -The standard value classes (*dateTimeClass[*]*, *nameClass*, *numericClass[*]*, -*posixPath[*]*, *textClass[*]*) if used, should have the same meaning as in the -standard HED schema. The hard-coded behavior associated with the starred ([*]) value -classes will be the same. Library schema may define additional value classes and +The standard value classes listed in [**A.1.3. Value classes**](./Appendix_A.md#(a-13-value-classes) +are the only value classes that should be used in designing library schemas as +these are the only ones that general tools will support. +If additional value classes are needed, they should be proposed on `hed-schemas` repository +[**issue forum**](https://github.com/hed-standard/hed-schemas/issues). + +Library schema may define additional value classes and specify their allowed characters, but no additional hard-coded behavior will be available in the standard toolset. This does not preclude special-purpose tools from incorporating their own behavior. ### 7.3.6. Schema attributes -The standard schema attributes (*allowedCharacter*, *defaultUnits*, *extensionAllowed*, +The standard schema attributes listed in +[**A.1.4. Schema attributes**](./Appendix_A.md#(*allowedCharacter*, *defaultUnits*, *extensionAllowed*, *recommended*, *relatedTag*, *requireChild*, *required*, *SIUnit*, *SIUnitModifier*, *SIUnitSymbolModifier*, *suggestedTag*, *tagGroup*, *takesValue*, *topLevelTagGroup*, *unique*, *unitClass*, *unitPrefix*, *unitSymbol*, *valueClass*) should have the same @@ -200,9 +201,10 @@ their own behavior. ### 7.3.7. Syntax checking -Regardless of whether a specification is in the standard HED schema or not, HED tools can perform basic syntax checking. +Regardless of whether an entity is in the standard HED schema or a library schema, +HED schema validation tools perform basic syntax checking. -````{admonition} Basic syntax checking for library schema. +````{admonition} Basic syntax checking for HED schemas. :class: tip 1. All attributes used in the schema proper must be defined in the schema attribute section of the schema. @@ -211,76 +213,46 @@ Regardless of whether a specification is in the standard HED schema or not, HED 4. Actual handling of the semantics by HED tools only occurs for entities appearing in the standard HED schema. ```` -## 7.4. library schemas in BIDS +## 7.4. Library schemas in BIDS The most common use case (for 99.9% of the HED users) is to tag events using -one of the standard HED schemas (preferably the latest one) available in the -`hedxml` directory of the `hed-specification` repository of the +a standard HED schemas (preferably the latest one) available in the +`standard_schema/hedxml` directory of the `hed-schemas` repository of the `hed-standard` organization on GitHub. The standard schemas are available at: -[https://github.com/hed-standard/hed-specification/tree/master/hedxml](https://github.com/hed-standard/hed-specification/tree/master/hedxml). +[**https://github.com/hed-standard/hed-schemas/tree/main/standard_schema**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema). -This section explains the changes that are being proposed in BIDS to accommodate -access to HED library schemas in addition to the standard HED schemas. -This section will be updated as the proposals progress though the -BIDS review process. -The initial proposal only supports **official standard schemas** available at -[https://github.com/hed-standard/hed-specification/tree/master/hedxml](https://github.com/hed-standard/hed-specification/tree/master/hedxml) -and **official library schemas** available at -[https://github.com/hed-standard/hed-schema-library/tree/main/library_schemas](https://github.com/hed-standard/hed-schema-library/tree/main/library_schemas). +The **official library schemas** are available at +[**https://github.com/hed-standard/hed-schemas/tree/main/library_schemas**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas). Standard schemas are referenced by their version number (e.g., `8.0.0`), while library schema are referenced by a combination of library name -and version number (e.g., `score_0.0.1`). - -The major change proposed to the BIDS specification is to allow the value -associated with the `"HEDVersion"` key in the `dataset_description.json` -file to be an array rather than a string expressing the HED version. -This proposed change will allow users more flexibility in specifying the -standard HED schema and will accommodate an arbitrary number of library schemas. -The different cases are illustrated in the following examples. - -The original BIDS specification just allows the standard HED schema, -which is named using a version number. - - -````{admonition} **Example:** Using just the standard HED schema in BIDS. -```json -{ - "Name": "A wonderful experiment", - "BIDSVersion": "1.6.0", - "HEDVersion": "8.0.0" -} - -``` -```` - +and version number (e.g., `score_1.0.0`). The following example specifies that version 8.0.0 of the standard HED schema is to be used in addition to two library schemas: -the `score` library version `0.0.1` and the `testlib` library version `1.0.2`. +the `score` library version `1.0.0` and the `testlib` library version `1.0.2`. -````{admonition} **Example:** Proposed specification of library schema in BIDS. +````{admonition} **Example:** An example specification with multiple schemas. ```json { "Name": "A wonderful experiment", - "BIDSVersion": "1.6.0", - "HEDVersion": ["8.0.0", "sc:score_0.0.1", "ts:testlib_1.0.2"] + "BIDSVersion": "1.8.0", + "HEDVersion": ["8.0.0", "sc:score_1.0.0", "ts:testlib_1.0.2"] } ``` ```` - Based on the above description tools will download: 1. The standard HED schema: -[https://github.com/hed-standard/hed-specification/tree/master/hedxml/HED8.0.0.xml](https://github.com/hed-standard/hed-specification/tree/master/hedxml/HED8.0.0.xml). -2. The HED `score` library schema version 0.0.1: -[https://github.com/hed-standard/hed-schema-library/tree/main/library_schemas/score/hedxml/HED_score_0.0.1.xml](https://github.com/hed-standard/hed-schema-library/tree/main/library_schemas/score/hedxml/HED_score_0.0.1.xml). +[https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HED8.0.0.xml](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HED8.0.0.xml). +2. The HED `score` library schema version 1.0.0: +[https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedxml/HED_score_1.0.0.xml](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedxml/HED_score_0.0.1.xml). 3. The HED `testlib` library schema version 1.0.2: -[https://github.com/hed-standard/hed-schema-library/tree/main/library_schemas/testlib/hedxml/HED_testlib_1.0.2.xml](https://github.com/hed-standard/hed-schema-library/blob/main/library_schemas/testlib/hedxml/HED_testlib_1.0.2.xml). +[https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/testlib/hedxml/HED_testlib_1.0.2.xml](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/testlib/hedxml/HED_testlib_1.0.2.xml). A schema browser is available for each library. For example the schema browser for the `score` library schema is available at @@ -293,34 +265,43 @@ specification, so tags from this schema may appear directly in the annotation. The `sc` and `ts` are local names used to distinguish tags from the additional schema. -Tags from the `score` library schema are of the form `sc:XXX` where `XXX` +Tags from the `score` library schema are of the form `sc:xxx` where `xxx` is a tag from the `score` schema. -Similarly, tags from the `testlib` library schema are of the form `ts:YYY` -where `YYY` is a tag from the `testlib` schema. - -In the following sample annotation `Data-feature` is from the standard HED schema, -while `Photomyogenic-response` and `Wicket-spikes` are from the `score` library. - -````{admonition} **Example:** An annotation using tags from two schemas. -```Text -Data-feature, sc:Photomyogenic-response, sc:Wicket-spikes -``` -```` +Similarly, tags from the `testlib` library schema are of the form `ts:yyy` +where `yyy` is a tag from the `testlib` schema. The array specification of the schema versions can have at most one version appearing without a colon prefix. -For some applications, the annotator will only want to use a particular -library schema. The following example specifies that only the `score` -library will be used. No prefixes are required in this case. + +### 7.1. Using library schema in BIDS + +The following `datset_description.json` of a BIDS dataset +indicates that HED standard schema version 8.1.0 should be used +alone with SCORE library schema 1.0.0. +The tags are.... +````{admonition} Illustration of using the namespace prefix for tagging. +:class: tip + -````{admonition} **Example:** Use of only the score library schema for tagging. ```json { - "Name": "A wonderful experiment", - "BIDSVersion": "1.6.0", - "HEDVersion": "score_0.0.1" + "Name": "A great experiment", + "BIDSVersion": "1.8.0", + "HEDVersion": ["8.1.0", "sc:score_1.0.0"] } ``` + +```text +"Data-feature, sc:Photomyogenic-response, sc:Wicket-spikes" +``` ```` + + +Additional information can be found in [**HED schema format**](./03_HED_formats.md#31-hed-schema-format) of Chapter 3 +and [**Appendix A: Schema format details**](Appendix_A.md) for additional information. + +Schema developers should also consult the +[**HED schema development guide**](https://www.hed-resources.org/en/latest/HedSchemaDevelopmentGuide.html). + diff --git a/docs/source/Appendix_A.md b/docs/source/Appendix_A.md index abe4d5bf..05490c51 100644 --- a/docs/source/Appendix_A.md +++ b/docs/source/Appendix_A.md @@ -1,23 +1,418 @@ -# A. Schema format +(appendix-a-schema-format-details-anchor)= +# A. Schema format details -HED schema developers generally do initial development of the schema using `.mediawiki` format. -The tools to convert schema between `.mediawiki` and `.xml` format are located in the -`hed.schema` module of the -[hedtools](https://github.com/hed-standard/hed-python/tree/master/hedtools) -project of the hed-python repository located at -[https://github.com/hed-standard/hed-python](https://github.com/hed-standard/hed-python). -All conversions are performed by converting the schema to a `HedSchema` object. -Then modules `wiki2xml.py` and `xml2wiki.py` provide top-level functions to perform these -conversions. This appendix presents the rules for standard HED schema and library schema in `.mediawiki` -and `.xml` formats. +This appendix augments the discussion of HED schema formats presented +in [**Chapter 3: HED formats**](./03_HED_formats.md) of the HED specification. +The appendix presents additional details on the rules with examples +for standard HED schema and HED library schema in `.mediawiki` and `.xml` formats. -## A.1. Mediawiki file format +## A.1. Auxiliary schema sections + +This section gives information about how the various auxiliary sections of the HED +schema are used to specify the behavior of the schema elements. + +### A.1.1. Unit classes and units + +Unit classes allow annotators to express the units of values in a consistent way. +The plurals of the various units are not explicitly listed, but are allowed as HED +tools uses standard pluralize functions to expand the list of allowed units. + +Units corresponding to unit symbols (i.e., have a `unitSymbol` attribute) +represent abbreviated versions of units and cannot be pluralized. + +Elements with the `SIUnit` modifier may be prefixed with a multiple or a sub-multiple modifier. +If the SI unit does not also have the `unitSymbol` attribute, then multiples and sub-multiples +with the `SIUnitModifier` attribute are used for the expansion. + +On the other hand, units with both `SIUnit` and `unitSymbol` attributes are expanded using +multiples and sub-multiples having the `SIUnitSymbolModifier` attribute. + +Note that some units such as byte are designated as SI units, +although they are not part of the SI standard. +However, they follow the same rules for unit modifiers as do SI units. + + +`````{list-table} Unit classes and units in HED 8.0.0 (* indicates unit symbol). +:widths: 20 10 40 +:header-rows: 1 + +* - Unit class + - Default units + - Units +* - accelerationUnits + - m-per-s^2 + - m-per-s^2* +* - angleUnits + - rad + - radian, rad*, degree +* - areaUnits + - m^2 + - metre^2, m^2* +* - currencyUnits + - $ + - dollar, $, point +* - frequencyUnits + - Hz + - hertz, Hz* +* - intensityUnits + - dB + - dB, candela, cd* +* - jerkUnits + - m-per-s^3 + - m-per-s^3* +* - memorySizeUnits + - B + - byte, B +* - physicalLength + - m + - metre, m*, inch, foot, mile +* - speedUnits + - m-per-s + - m-per-s*, mph, kph +* - timeUnits + - s + - second, s*, day, minute, hour +* - volumeUnits + - m^3 + - metre^3, m^3* +* - weightUnits + - g + - gram, g*, pound, lb +`````` + +### A.1.2. Unit modifiers + +A unit modifier can be applied to SI base units to indicate a multiple or sub-multiple of the unit. +Unit symbols are modified by unit symbol modifiers, whereas +SI units that are not unit symbols are modified by unit modifiers. + +`````{list-table} SI unit modifiers +:widths: 20 20 50 +:header-rows: 1 + +* - Modifier + - Symbol modifier + - Description +* - deca + - da + - Multiple representing 10 to power 1 +* - hecto + - h + - Multiple representing 10 to power 2 +* - kilo + - k + - Multiple representing 10 to power 3 +* - mega + - M + - Multiple representing 10 to power 6 +* - giga + - G + - Multiple representing 10 to power 9 +* - tera + - T + - Multiple representing 10 to power 12 +* - peta + - P + - Multiple representing 10 to power 15 +* - exa + - E + - Multiple representing 10 to power 18 +* - zetta + - Z + - Multiple representing 10 to power 21 +* - yotta + - Y + - Multiple representing 10 to power 24 +* - deci + - d + - Submultiple representing 10 to power −1 +* - centi + - c + - Submultiple representing 10 to power -2 +* - milli + - m + - Submultiple representing 10 to power -3 +* - micro + - u + - Submultiple representing 10 to power -6 +* - nano + - n + - Submultiple representing 10 to power −9 +* - pico + - p + - Submultiple representing 10 to power −12 +* - femto + - f + - Submultiple representing 10 to power −15 +* - atto + - a + - Submultiple representing 10 to power −18 +* - zepto + - z + - Submultiple representing 10 to power −21 +* - yocto + - y + - Submultiple representing 10 to power −24 +`````` + +### A.1.3. Value classes + +HED has very strict rules about what characters are allowed in various elements of the HED +schema, HED tags, and the substitutions made for `#` placeholders. +These rules are encoded in the schema using value classes. +When a node name extension or placeholder substitution is given a particular value class, +that name or substituted value can only contain the characters allowed for by that value class. + +```{Warning} +**Note**: A placeholder `#` specification may include multiple value class attributes. + +Tools check the value in question against the union of an element's `valueClass` allowed +characters and any additional characters allowed by a particular unit type. + +``` + +The allowed characters for a value class are specified in the definition of each value class. +The HED validator and other HED tools may hardcode information about +behavior of certain value classes (for example the `numericClass` value class). + +(value-class-character-table-anchor)= +`````{list-table} Allowed characters for value classes. +:widths: 20 50 +:header-rows: 1 + +* - Value class + - Allowed characters +* - dateTimeClass + - `digits` `T` `:` `-` +* - nameClass + - `alphanumeric` `-` `_` +* - numericClass + - `digits` `.` `-` `+` `E` `e` +* - posixPath + - As yet unspecified +* - textClass + - `alphanumeric` `blank` `+` `-` `:` `;` `.` `/` `(` `)` `?` ` *` `%` ` $` `@` `^` `_` +`````` + +````{admonition} Notes on rules for allowed characters in the HED schema. +:class: tip + +1. Commas or single quotes are not allowed in any values with the exception of +the Prologue, Epilogue, or term descriptions in the HED schema. +These characters are not allowed in substitutions for `#` placeholders. +2. Date-times should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss. +3. Any variation on the full form of ISO8601 date-time is allowed. +4. The `nameClass` is for schema nodes and labels. +5. Values of `numericClass` must be equivalent to a valid floating point value. +6. Scientific notation is supported with the `numericClass`. +7. The `textClass` is for descriptions, mainly for use with the `Description` tag or schema element descriptions. +8. The `posixPath` class is as yet unspecified and currently allows any characters except commas. + +```` + + +### A.1.4. Schema attributes + +The type of schema element that a schema attribute may apply to is indicated by +its schema type property values. +Tools hardcode processing based on the schema attribute name. +Only the schema attributes listed in the following table can be handled by current HED tools. + + +`````{list-table} Schema attributes (* indicates attribute has a value). +:widths: 20 15 45 +:header-rows: 1 + +* - Attribute + - Target + - Description +* - `allowedCharacter`* + - valueClass + - Specifies a character used in values of this class. +* - `conversionFactor` + - unit, unitModifier + - Multiplicative factor to multiply by to convert to default units.
+ (Added in version 8.1.0.) +* - `defaultUnits`* + - unitClass + - Specifies units to use if placeholder value has no units. +* - `extensionAllowed` + - node + - A tag can have unlimited levels of child nodes added. +* - `recommended` + - node + - Event-level HED strings should include this tag. +* - `relatedTag`* + - node + - A HED tag closely related to this HED tag. +* - `requireChild` + - node + - A child of this node must be included in the HED tag. +* - `required` + - node + - Event-level HED string must include this tag. +* - `SIUnit` + - unit + - This unit represents an SI unit and can be modified. +* - `SIUnitModifier` + - unitModifier + - Modifier applies to base units. +* - `SIUnitSymbolModifier` + - unitModifier + - Modifier applies to unit symbols. +* - `suggestedTag`* + - node + - Tag could be included with this HED tag. +* - `tagGroup` + - node + - Tag can only appear inside a tag group. +* - `takesValue` + - node # + - Placeholder (#)should be replaced by a value. +* - `topLevelTagGroup` + - node + - Tag (or its descendants) can be in a top-level tag group. +* - `unique` + - node + - Tag or its descendants can only occur once in
+ an event-level HED string. +* - `unitClass`* + - node # + - Unit class this replacement value belongs to. +* - `unitPrefix` + - unit + - Unit is a prefix (e.g., $ in the currency units). +* - `unitSymbol` + - unit + - Tag is an abbreviation representing a unit. +* - `valueClass`* + - node # + - Type of value this is. +`````` + +The `allowedCharacter` attribute should appear separately for each individual character to be allowed. +However, the following group designations are allowed as values for this attribute: +- `letters` designates upper and lower case alphabetic characters. +- `blank` indicates a space is an allowed character. +- `digits` indicates the digits 0-9 may be used in the value. +- `alphanumeric` indicates `letters` and `digits` + +If placeholder (`#`) has a `unitClass`, but the replacement value for the placeholder +does not have units, tools may assume the value has `defaultUnits` if the unit class has them. +For example, the `timeUnits` has the attribute `defaultUnits=s` in HED versions >=8.0.0. +Tools may assume that tag `Duration/3` is equivalent to `Duration/3 s` because `Duration` has +`defaultUnits` of `s`. + +The `extensionAllowed` tag indicates that descendents of this node may be extended by annotators. +However, any node that has a placeholder (`#`) child cannot be extended, +regardless of the `extensionAllowed` attribute, +since the node's single child is always interpreted as a user-supplied value. + +Tags with the `required` or `unique` attributes cannot appear in definitions. + +In addition to the attributes listed above, some schema attributes have been deprecated +and are no longer supported in HED, although they are still present in earlier versions of +the schema. The following table lists these. + +`````{list-table} Schema attributes deprecated for versions >=8.0.0 (* indicates attribute has a value). +:widths: 20 15 45 +:header-rows: 1 + +* - Schema attribute + - Target + - Description +* - `default` + - node # + - Indicates a default value used if no value is provided. +* - `position`* + - node + - Indicates where this tag should appear during display. +* - `predicateType` + - node + - Indicates the relationship of the node to its parent. +`````` + +The `default` attribute was not implemented in existing tools. +The attribute is not used in HED-3G. Only the `defaultUnits` for the unit class +will be implemented going forward. + +The `position` attribute was used to assist annotation tools, which sought to +display required and recommend tags before others. +The position attribute value is an integer and the order can start at 0 or 1. +Required or recommended tags without this attribute or with negative position +were to be shown after the others in canonical ordering. +The tagging strategy of HED versions >= 8.0.0 using decomposition +and definitions does not permit this type of ordering. +The `position` attribute is not used for HED versions >= 8.0.0. + +The `predicateType` attribute was introduced in HED-2G to facilitate mapping to OWL or RDF. +It was needed because the HED-2G schema had a mixture of children +that were properties and subclasses. +The possible values of `predicateType` were `propertyOf`, `subclassOf`, or `passThrough` +to indicate which role each child node had with respect to its parent. +In HED versions >= 8.0.0, the parent-child relationship MUST be `subclassOf` to allow search generality. +The attribute is ignored by tools. + + +### A.1.5. Schema properties + +The `property` elements apply to schema attribute elements to indicate how and +where these attributes apply to other elements in the schema. +Their meanings are hard-coded into the schema processors. +The following is a list of schema attribute properties. + +`````{list-table} Summary of schema attribute properties for HED Version >= 8.0.0. +:widths: 20 50 +:header-rows: 1 + +* - Property + - Description +* - `boolProperty` + - A schema attribute's value is either true or false.
Presence indicates true, absence false. +* - `unitClassProperty` + - A schema attribute only applies to unit classes. +* - `unitModifierProperty` + - A schema attribute only applies to unit modifiers. +* - `unitProperty` + - A schema attribute only applies to units. +* - `valueClassProperty` + - A schema attribute only applies to value classes. +`````` + +The element that a schema attribute can apply to is controlled by the +`unitClassProperty`, `unitModifierProperty`, `unitModifierProperty`, `unitProperty`, and `valueClassProperty` schema properties. +A schema attribute that doesn't have one of these properties only +applies to node elements in the schema section. + +The `boolProperty` controls the form of the schema attribute. + +````{admonition} Format for schema attributes. +:class: tip + +- **Schema attributes with the `boolProperty`:** + - In `.xml`, appear as a `` element with the property, but no +`` in an `` section of the schema element. + - In `.mediawiki`, the attribute has the `{name}` in the element's specification line. + - In either case, presence of the property indicates true and absence indicates false. +

+ +- **Schema attributes without the `boolProperty`:** + - In `.xml`, appear with both `` and `` in the `` section of the schema element. + - In `.mediawiki`, the schema element has the `{name =value}` in the element's specification line. + - These schema attributes may appear multiple times in an element with different values if appropriate. + +```` + + + +## A.2. Mediawiki file format The rules for creating a valid `.mediawiki` specification of a HED schema are given below. -The format is line-oriented, meaning that all information about an individual entity should be on a -single line. Empty lines and lines containing only blanks are ignored. +The format is line-oriented, meaning that all information about an individual entity +should be on a single line. +Empty lines and lines containing only blanks are ignored. -### A.1.1. Overall file layout +### A.2.1. Overall file layout ````{admonition} Overall layout of a HED MEDIAWIKI schema file. @@ -38,9 +433,7 @@ epilogue ``` ```` - - -### A.1.2. The *header-line* +### A.2.2. The *header-line* The first line of the `.mediawiki` file should be a _header-line_ that starts with the keyword `HED` followed by a blank-separated list of name-value pairs. @@ -57,7 +450,7 @@ keyword `HED` followed by a blank-separated list of name-value pairs. - optional - Name of library used in XML file names. - The value should only have alphabetic characters. + The value should only have lowercase alphabetic characters. * - version - required - A valid semantic version number of the schema. @@ -66,133 +459,154 @@ keyword `HED` followed by a blank-separated list of name-value pairs. - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance". * - xsi - optional - - xsi:noNamespaceSchemaLocation points to XSD file. + - xsi:noNamespaceSchemaLocation points to an XSD file. + ```` -The `xsi` attribute is required if `xmlns:xsi` is given. -The `library` and `version` values are used to form the official xml file name and appear as attributes -in the `` root of the `.xml` file`.` The versions of the schema that use XSD validation to -verify the format (versions 8.0.0 and above) have `xmlns:xsi` and `xsi:noNamespaceSchemaLocation` attributes. +The following example gives a sample *header-line* for standard schema version 8.0.0 in `.mediawiki` format. -````{admonition} **Example:** Version 8.0.0 of the HED MEDIAWIKI schema. +````{admonition} **Example:** Sample *header-line* for version 8.0.0 in .mediawiki format. ```moin HED version="8.0.0" ``` - ```` -The version line must be the first line of the `.mediawiki` file. The schema -`.mediawiki` file is `HED-schema-8.0.0.mediawiki` found in -[https://github.com/hed-standard/hed-specification/tree/master/hedwiki](https://github.com/hed-standard/hed-specification/tree/master/hedwiki). - -````{admonition} **Example:** Version 8.0.0 of the standard HED XML schema. +The schema `.mediawiki` file specified in this example is named `HED8.0.0.mediawiki` and can be found in the +[**standard_schema/hedwiki**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema/hedwiki) +directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) GitHub repository. -```xml - -``` -```` +The versions of the schema that use XSD validation to verify the format (versions 8.0.0 and above) have `xmlns:xsi` and `xsi:noNamespaceSchemaLocation` attributes. +The `xsi` attribute is required if `xmlns:xsi` is given. +The [**XSD file**](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.0.0.xsd) +allows validators to check the format of the `.xml` using standard XML validators. -The file name in `hedxml` in `hed-specification` is `HED8.0.0.xml`. +The following example shows a sample *header-line* for `testlib` library schema version 1.0.2 in `.mediawiki` format. -````{admonition} **Example:** Version 1.0.2 of HED test library in MEDIAWIKI format. +````{admonition} **Example:** Sample *header-line* for testlib library version 1.0.2 in .mediawiki format. ```moin -HED library="test" version="1.0.2" +HED library="testlib" version="1.0.2" ``` ```` -The resulting XML root is: +The `library` and `version` values are used to form the official file name `HED_testlib_1.0.2.mediawiki`. +The file is found in [**library_schemas/testlib/hedwiki**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/testlib/hedwiki) +directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) GitHub repository. -````{admonition} **Example:** Version 1.0.2 of HED test library schema in XML format. -```xml - -``` -```` +A warning is generated when unknown header-line attributes are translated as attributes of the `HED` line +during `.mediawiki` file validation. -The file name in `hedxml` in the HED schema library `test` is `HED_test_1.0.2.xml`. +### A.2.3. The prologue and epilogue -Unknown header-line attributes are translated as attributes of the `HED` root node of the -`.xml` version, but a warning is used when the `.mediawiki` file is validated. +The prologue is an optional paragraph of text appearing after the *header-line*. +The prologue is used by tools for help and display purposes. + +Early versions of HED use the prologue section to record a CHANGE_LOG as well as +information about the syntax and rules. +HED versions >= 8.0.0 include a separate change log file for released versions. + +Similar to the prologue section, the epilogue is an optional paragraph of text, +usually containing references and license information. +The epilogue appears directly before the ending line of the file. -### A.1.3. Schema section +Both the prologue and epilogue may contain commas and new lines in addition +to the characters specified by the [`textClass`](./Appendix_A.md#a13-value-classes). -The beginning of the HED specification is marked by the *start-line*: +### A.2.4. Schema sections + +The beginning of the actual specification of the HED vocabulary is marked by the *start-line*: ```moin !# start schema ``` -An arbitrary number of lines of informational text can be placed between the header-line -and the start-line. Older versions of HED have a CHANGE_LOG as well as information about -the syntax and rules. New versions of HED generate a separate change log file for released -versions. -The end of the main HED-specification is marked by the end-line: +The end of the main HED-specification is marked by the *end-line*: ```moin !# end schema ``` +A section separator is a line starting with `!#`. The section separator lines (`!# start schema`, `!# end schema`, `!# end hed`) must only -appear once in the file and must appear in that order within the file. A section separator -is a line starting with `!#`. +appear once in the file and must appear in that order within the file. + +The body of the HED specification is located between the `!# start schema` and `!# end schema` +section separators. +Each specification is a single line in the `.mediawiki` file. + +The three types of lines in the main specification section +are **top-nodes**, **normal-nodes**, and **placeholders**, respectively. + +Empty lines or lines containing only blanks are ignored. -The body of the HED specification consists of two types of lines: top-level node-specification -specifications and other node specifications. Each specification is a single line in the -`.mediawiki` file. Empty lines or lines containing only blanks are ignored. The basic format -for a node-specification is: +The basic format for a node-specification is: ```moin node-name {attributes}[description] ``` -Top-level node names are enclosed in triple single quotes (e.g., `'''Event'''`), while other -node names have at least one preceding asterisk (*) followed by a blank and then the name. -The number of asterisks indicates the level of the node in the subtree. HED-3G node names -can only contain alphanumeric characters, hyphens, and under-bars. They cannot contain blanks -and must be unique. HED (2G) and earlier versions allow blanks. Everything after the node -name must be contained within `` tags. Placeholder nodes have an empty node -name, but are followed by a `#` enclosed in `` tags. +Top node names are enclosed in triple single quotes (e.g., `'''Event'''`), +while other types of nodes have at least one preceding asterisk (*) +followed by a blank and then the name. + +The number of asterisks indicates the level of the node in the subtree. +The attributes are in curly braces (`{ }`) and the description is in square brackets (`[ ]`). + +Node names in HED versions >= 8.0.0 can only contain alphanumeric characters, +hyphens, and under-bars (i.e., they must be of type [`nameClass`](./Appendix_A.md#a13-value-classes). +They cannot contain blanks and must be unique. + +HED versions < 8.0.0 allow blanks in node names and also have some duplicate node names. +Use of HED versions < 8.0.0 is deprecated, although validators still support them at this time. + +For top nodes and normal nodes, everything after the node name must be contained within `` tags. +The `#` is included within the `` tags in placeholder nodes. -````{admonition} **Example:** Different types of HED node specifications. +````{admonition} **Example:** Different types of HED node specifications in .mediawiki format. -**Top-level:** +**Top node:** ```moin '''Property''' {extensionAllowed} [Subtree of properties.] ``` -**Normal-level:** +**Normal node:** ```moin ***** Duration {requireChild} [Time extent of something.] ``` -**Placeholder-level:** +**Placeholder node:** ```moin ****** # {takesValue, unitClass=time,valueClass=numericClass} ``` ```` -The *Duration* tag of this example is at the fifth level below the root of its subtree. -The tag: *Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Duration* -is the long form. The placeholder in the example is the node directly below *Duration* +The `Duration` tag of this example is at the fifth level below the root (top node) of its subtree. +The tag: `Property/Data-property/Data-value/Spatiotemporal-value/Temporal-value/Duration` +is the long form. The placeholder in the example is the node directly below `Duration` in the hierarchy. -### A.1.4. Other sections +### A.2.5. Auxiliary sections After the line marking the end of the schema (`!# end schema`), the `.mediawiki` file contains -the unit class specifications, unit modifier specifications, value class specification, -the schema attribute specifications, and property specifications. All of these sections are +the unit class definitions, unit modifier definitions, value class definitions, +the schema attribute definitions, and property definitions. All of these sections are required starting with HED version 8.0.0 and must be given in this order. -Unit classes specify the kind of units are allowed to be used with a value that is provided -for a `#` value. The unit class specification section starts with `'''Unit classes'''` and -lists the type of unit at the first level and the specific units at the second level. +#### A.2.5.1. Unit classes and units -````{admonition} **Example:** Part of the HED unit class specification for time. +Unit classes specify the types of units allowed to be used with a value +substituted for a `#` placeholder. + +The unit class specification section starts with `'''Unit classes'''` and +lists the types of units (the unit classes) at the first level +and the specific units corresponding to those unit classes at the second level. + +````{admonition} **Example:** Part of the HED unit class for time in .mediawiki format. ```moin '''Unit classes''' @@ -202,54 +616,74 @@ lists the type of unit at the first level and the specific units at the second l ``` ```` -The unit classes can be modified by SI (International System Units) sub-multiples -and super-multiples. All unit modifiers are at level 1 of the `.mediawiki` -file. Unit modifiers have either the `SIUnitModifer` or the `SIUnitSymbolModifer` -to indicate whether they are regular modifiers or symbol modifiers. +#### A.2.5.2. Unit modifiers + +The SI units can be modified by SI (International System Units) sub-multiples +and multiples. All unit modifiers are at level 1 of the `.mediawiki` file. + -````{admonition} **Example:** Part of the HED unit modifier specification. +````{admonition} **Example:** Part of the HED unit modifier in .mediawiki format. ```moin '''Unit modifiers''' -* deca {SIUnitModifier} [SI unit multiple for 10^1] -* da {SIUnitSymbolModifier} [SI unit multiple for 10^1] +* deca {SIUnitModifier} [SI unit multiple for 10 raised to power 1] +* da {SIUnitSymbolModifier} [SI unit multiple for 10 raised to power 1] ``` ```` -Units that have the `SIUnit` attribute can be modified by any unit modifier -that has the `SIUnitModifier`. So for example, `second` and `decasecond` are -valid time units as are `seconds` and `decaseconds`. Similarly, units that -have the `SIUnit` and `unitSymbol` modifiers can be modified with unit modifiers -that have the `SIUnitSymbolModifier` attribute. +A unit must have the `SIUnit` attribute in order to be used with modifiers. +If the unit has both the `SIUnit` and `unitSymbol` attributes, +then it only can be used with `SIUnitSymbolModifier` modifiers. +If the unit has only the `SIUnit` attribute, +then it only can be used with the `SIUnitModifer`. + +For example the unit `second` is an `SIUnit` but not a symbol, +so `second`, `seconds`, `decasecond` and `decaseconds` are all valid units. + +The unit `s` is both a `SIUnit` and a `unitSymbol`, so `s` and `das` are valid units. +Note that rules about pluralization do not apply to unit symbols. + -Value attributes give rules about what kind of value is allowed to be substituted +#### A.2.5.3. Value classes + +Value classes give rules about what kind of value is allowed to be substituted for `#` placeholder tags. -````{admonition} **Example:** Part of the HED value class specification. +````{admonition} **Example:** Part of the HED value class for date-time in .mediawiki format. ```moin '''Value classes''' -* posixPath {allowedCharacter=/,allowedCharacter=:}[Posix path specification.] +* dateTimeClass {allowedCharacter=digits,allowedCharacter=T,allowedCharacter=-,allowedCharacter=:}[Should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss.] ``` ```` -The schema attributes specify other characteristics about how particular tags may be used in -annotation. These attributes allow validators and other tools to process tag strings based + +#### A.2.5.4. Schema attributes + +The schema attributes specify other characteristics about how +particular tags may be used in annotation. +These attributes allow validators and other tools to process tag strings based on the HED schema specification, thus avoiding hard-coding particular behavior. -````{admonition} **Example:** Part of the HED schema attribute specification. +````{admonition} **Example:** HED schema attributes allowedChaaracter and defaultUnits in .mediawiki format. ```moin '''Schema attributes''' -* allowedCharacter {valueClassProperty}[Attribute of value classes specifying a special character that is allowed in expressing the value of a placeholder.] -* defaultUnits {unitClassProperty}[Attribute of unit classes specifying the default units for a tag.] +* allowedCharacter {valueClassProperty}[Value may contain this character.] +* extensionAllowed {boolProperty}[This schema node may be extended.] ``` ```` -Notice that in the above example, the schema attributes, themselves have attributes referred to as -*HED schema properties*. These schema properties are listed in the `Properties` section of the -schema. +The schema attributes, themselves, have attributes referred to as*schema properties*. +These schema properties are listed in the `Properties` section of the schema. +The example indicates that `allowedCharacter` is associated with value classes, +while `defaultUnits` is associated with unit classes. + +#### A.2.5.5. Schema properties -````{admonition} **Example:** Part of the HED schema property specification. +Properties apply only to schema attributes. +The following example defines the `valueClassProperty` in `.mediawiki` format. + +````{admonition} **Example:** HED schema property valueClassProperty in .mediawiki format. ```moin '''Properties''' @@ -257,7 +691,11 @@ schema. ``` ```` -## A.2. XML file format +## A.3. XML file format + +This section describes details of the XML schema format. + +### A.3.1. Overall file layout The XML schema file format has a header, prologue, main schema, definitions, and epilogue sections. The general layout is as follows: @@ -304,13 +742,49 @@ sections. The general layout is as follows: ``` ```` -The `xxx` and `xxx` elements are meant to be treated -as opaque as far as schema processing goes. In earlier versions of HED the prologue section -contained a Change Log for the schema as well as some basic documentation of syntax. +### A.3.2. The header + +The `HED` node is the root node of the XML schema. + +````{admonition} **Example:** Header for Version 8.0.0 of the standard HED XML schema. + +```xml + +``` +```` + +The file name corresponding to this example is `HED8.0.0.xml`. +The file is found in the [**standard_schema/hedxml**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema/hedxml) +directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) GitHub repository. + +Library schemas must include the `library` attribute with the library name +in their header line as shown in the following example. + +````{admonition} **Example:** Version 1.0.2 of HED testlib library schema in .xml format. +```xml + +``` +```` + + +The `library` and `version` values are used to form the official xml file name `HED_testlib_1.0.2.xml`. +The file is found in [**library_schemas/testlib/hedxml**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/testlib/hedxml) +directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) GitHub repository. + +Unknown header-line attributes are translated as attributes of the `HED` root node of the +`.xml` version, but a warning is issued when the `.mediawiki` file is validated. + +### A.3.3. The prologue and epilogue + +The `...` and `...` elements +are meant to be treated as opaque as far as schema processing goes. + +HED versions < 8.0.0 contained a Change Log for the HED schema in the prologue section +as well as some basic documentation of syntax. The epilogue section contained additional metadata to be ignored during processing. -The following subsections give a more detailed description of the format of these sections. -### A.2.1. The schema section + +### A.3.4. The schema section The schema section of the HED XML document consists of an arbitrary number of `` elements enclosed in a single `` element. @@ -345,16 +819,23 @@ The `` element text must conform to the rules for naming HED schema nodes. It corresponds to the _node-name_ in the `mediawiki` specification and must not be empty. A `#` value is used to represent value place-holder elements. -The `` element has the text contained in the square brackets `[]` in the -`.mediawiki` node specification. If the `.mediawiki` specification is missing or has an -empty `[]`, the `` element is omitted. +The `` element has the text contained in the square brackets `[ ]` in the +`.mediawiki` node specification. +If the `.mediawiki` description is missing or has an +empty `[ ]`, the `` element is omitted. The optional `` elements are derived from the attribute list contained in curly -braces `{}` of the `.mediawiki` specification. An `` element has a single non-empty -`` child element whose text value corresponds to the node-name of attribute in the -corresponding `.mediawiki` file. If the attribute does not have the `boolProperty`, +braces `{ }` of the `.mediawiki` specification. +An `` element has a single non-empty `` child element whose text +value corresponds to the node-name of attribute in the corresponding `.mediawiki` file. +If the attribute does not have the `boolProperty`, then the `` element should also have one or more child `` elements -giving the value(s) of the attribute. **Example:** The `requireChild` attribute represents a boolean value. In the `.mediawiki` representation this attribute appears as `{requireChild}` if present and is omitted if absent. +giving the value(s) of the attribute. + +**Example:** The `requireChild` attribute represents a boolean value. In the `.mediawiki` representation this attribute appears as `{requireChild}` if present and is omitted if absent. + +The format of the XML attributes was changed with HED versions > 8.0.0. +The old version is deprecated, but still supported for validation. ````{admonition} The requireChild attribute represents a boolean value. @@ -376,17 +857,10 @@ giving the value(s) of the attribute. **Example:** The `requireChild` attribute ``` ```` -The `suggestedTag` attribute has a valid HED tag value. In the mediawiki representation -this attribute is omitted if absent and appears when present as shown in this example. - -````{admonition} The suggestedTag attribute has a valid HED tag value. -```moin -{suggestedTag=Sweet,suggestedTag=Gustatory-attribute/Salty} -``` -```` - -The `suggestedTag` attribute is meant to be used by tagging tools to suggest additional tags +**Example:** +The `suggestedTag` is a schema attribute that has a value. +The attribute is meant to be used by tagging tools to suggest additional tags that a user might want to include. Notice that the `suggestedTag` values are valid HED tags in any form (short, long, or intermediate). @@ -414,29 +888,26 @@ in any form (short, long, or intermediate). ``` ```` -### A.2.2. Unit classes +### A.3.5. Auxiliary sections -The valid HED-3G unit classes are defined in the `` section of the XML -schema file, and valid HED-3G unit modifiers are defined in the `` -section. These sections follow a format similar to the `` element in the `` -section: +The auxiliary sections define various aspects of behavior of various types of elements in the schema. -````{admonition} XML layout of the unit class definitions. -```xml - - ... - ... - ... - -``` -```` +#### A.3.5.1. Unit classes + +The unit classes are defined in the `` section of the XML +schema file, and the unit modifiers are defined in the `` +section. These sections follow a format similar to the `` element in the `` +section. -The `` elements have a required ``, an optional `` -and an arbitrary number of additional `` child elements. These `` elements -describe properties of the unit class rather than of individual unit types. In addition, -`` elements may have an arbitrary number of `` child elements. +The `` elements have a required ``, +an optional ``, +and an arbitrary number of additional `` child elements. +These `` elements describe properties of the unit class rather +than of individual unit types. +In addition, `` elements may have an arbitrary number +of `` child elements as shown in the following example. -````{admonition} XML layout of the unit class definitions. +````{admonition} Example XML layout of the unit class definitions. ```xml time @@ -466,393 +937,97 @@ describe properties of the unit class rather than of individual unit types. In a ``` ```` -### A.2.3. Value classes +#### A.3.5.2. Unit modifiers + +Unit modifiers are defined in the `` section of the XML schema file. +The following shows the layout of an example unit modifier definitions: + +````{admonition} Example XML layout of the unit modifier definition +```xml + + + + deca + SI unit multiple representing 10^1. + + SIUnitModifier + + + conversionFactor + 10.0 + + + . . . + +``` +```` + + +#### A.3.5.3 Value classes Value classes are defined in the `` section of the XML schema file. These sections follow a format similar to the `` element in the ``: -````{admonition} XML layout of the unit class definitions. +````{admonition} Example XML layout of the unit class definitions. ```xml - ... - ... - ... + + dateTimeClass + Should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss. + + allowedCharacter + digits + T + - + : + + ``` ```` -### A.2.4. Schema attributes +#### A.3.5.4. Schema attributes The `` section specifies the allowed attributes of the other elements including the ``, ``, ``, and `` elements. The specifications of individual attributes are given in `` elements. -````{admonition} XML layout of the schema attribute definitions. +````{admonition} Example XML layout of the schema attribute definitions. ```xml - ... - ... - ... - + + allowedCharacter + Value may contain this character. + + valueClassProperty + + + + extensionAllowed + This schema node may be extended. + + boolProperty + + + . . . + ``` ```` -The individual `` elements have the following format: - -````{admonition} XML layout of the schema attribute definitions. -```xml - - allowedCharacter - An attribute of value classes indicating a special character that is allowed in expressing the value of that placeholder. - - valueClassProperty - - -``` -```` +#### A.3.5.5. Schema properties -## A.3. Schema sections +The following is an example of the layout of the `valueClassProperty` in `.xml` format. -This section gives information about how the various auxiliary sections of the HED -schema are used to specify the behavior of the schema elements. - -### A.3.1. Schema properties - -The `property` elements indicate where various schema attributes apply. -Their meanings are hard-coded into the schema processors. The following is a list of schema -attribute properties. - -`````{list-table} Summary of unit classes and units in HED 8.0.0 (* indicates unit symbol). -:widths: 20 50 -:header-rows: 1 - -* - Property - - Description -* - boolProperty - - Indicates schema attribute values are either true or false. -* - unitClassProperty - - Indicates schema attribute only applies to unit classes. -* - unitModifierProperty - - Indicates schema attribute only applies to unit modifiers. -* - valueClassProperty - - Indicates the schema attribute only applies to value classes. -* - textClass - - Alphanumeric characters, blank,
- +, -, :, ;, ., /, (, ), ?, *, %, $, @, ^, _ -`````` - - -````{admonition} Notes on rules for allowed characters in the HED schema. -:class: tip - -1. Schema attributes with the `boolProperty` have a `` node but no -`` node in the XML. -Presence indicates true. -2. Schema attributes without the `boolProperty` have both `` and -`` nodes in the XML. - -```` - - -A given schema attribute can only apply to one type of element (`node`, `unitClassDefinition`, -`unitModifierDefinition` or `unit`). Attributes that don’t have one of `unitClassProperty`, -`unitClassProperty` or `unitProperty` are assumed to apply to `node` elements. - -### A.3.2. Schema attributes - -As mentioned in the previous section schema attributes can only apply to one -type of element in the schema as indicated by their property values. -Tools hardcode processing based on the schema attribute name. Only the schema -attributes listed in the following table can be handled by current HED tools. - - -`````{list-table} Schema attributes (* indicates attribute has a value). -:widths: 20 15 45 -:header-rows: 1 - -* - Attribute - - Target - - Description -* - allowedCharacter* - - valueClass - - Specifies a character used in values of this class. -* - defaultUnits* - - unitClass - - Specifies units to use if placeholder value has no units. -* - extensionAllowed - - node - - A tag can have unlimited levels of child nodes added. -* - recommended - - node - - Event-level HED strings should include this tag. -* - relatedTag* - - node - - A HED tag closely related to this HED tag. -* - requireChild - - node - - A child of this node must be included in the HED tag. -* - required - - node - - Event-level HED string must include this tag. -* - SIUnit - - unit - - This unit represents an SI unit and can be modified. -* - SIUnitModifier - - unitModifier - - Modifier applies to base units. -* - SIUnitSymbolModifier - - unitModifier - - Modifier applies to unit symbols. -* - suggestedTag* - - node - - Tag could be included with this HED tag. -* - tagGroup - - node - - Tag can only appear inside a tag group. -* - takesValue - - node # - - Placeholder (#)should be replaced by a value. -* - topLevelTagGroup - - node - - Tag (or its descendants) can be in a top-level tag group. -* - unique - - node - - Tag or its descendants can only occur once in
- an event-level HED string. -* - unitClass* - - node # - - Unit class this replacement value belongs to. -* - unitPrefix - - unit - - Unit is a prefix (e.g., $ in the currency units). -* - unitSymbol - - unit - - Tag is an abbreviation representing a unit. -* - valueClass* - - node # - - Type of value this is. -`````` - -Normally the allowed characters are listed individually as values of the `allowedCharacter` -attribute. However, the word `letters` designates upper and lower case alphabetic characters -are allowed. Further, the word `blank` indicates a space is an allowed character, and the -word `digits` indicates the digits 0-9 may be used in the value. - -If placeholder (`#`) has a `unitClass`, but the replacement value for the placeholder -does not have units, tools use the value of `defaultUnits` if the unit class has them. -For example, the `timeUnits` has the attribute `defaultUnits=s` in HED 8.0.0. The tag -`Duration/3` is assumed to be equivalent to `Duration/3 s` because `Duration` has -`defaultUnits` of `s`. - -The `extensionAllowed` tag indicates that descendents of this node may be extended by -annotators. However, any tag that has a placeholder (`#`) child cannot be extended, -regardless of `extensionAllowed` since it single child is always interpreted as a -user-supplied value. - -Tags with the 'required' or 'unique' attributes cannot appear in definitions. - -In addition to the attributes listed above, some schema attributes have been deprecated -and are no longer supported in HED, although they are still present in earlier versions of -the schema. The following table lists these. - -`````{list-table} Schema attributes (* indicates attribute has a value). -:widths: 20 15 45 -:header-rows: 1 - -* - Schema attribute - - Target - - Description -* - default - - node # - - Indicates a default value used if no value is provided. -* - position - - node - - Indicates where this tag should appear during display. -* - predicateType - - node - - Indicates the relationship of the node to its parent. -`````` - -The `default` attribute was not implemented in existing tools. -The attribute is not used in HED-3G. Only the `defaultUnits` for the unit class -will be implemented going forward. - -The `position` attribute was used to assist annotation tools, which sought to -display required and recommend tags before others. The position attribute value -is an integer and the order can start at 0 or 1. Required or recommended -tags without this attribute or with negative position will be shown after the -others in canonical ordering. The tagging strategy of HED-3G using decomposition -and definitions. The `position` attribute is not used for HED-3G. - -The `predicateType` attribute was introduced in HED-2G to facilitate mapping -to OWL or RDF. It was needed because the HED-2G schema had a mixture of children -that were properties and subclasses. The possible values of `predicateType` -were `propertyOf`, `subclassOf`, or `passThrough` to indicate which role each -child node had with respect to its parent. The schema vocabulary redesign of -HED-3G eliminated this issue. The attribute is ignored by tools. - -### A.3.3. Value classes - -HED has very strict rules about what characters are allowed in various elements of the HED -schema, HED tags and the substitutions made for `#` placeholders. These rules are encoded in -the schema using value classes. When a node name or placeholder substitution is given a -particular value class, that name or substituted value can only contain the characters allowed -for that value class. - -The allowed characters for a value class are specified in the definition -of each value class. The HED validator and other HED tools may hardcode information about -behavior of certain value classes (for example the `numericClass` value class). -**HED does not allow commas or single quotes in any of its values.** - -`````{list-table} Rules for value classes. -:widths: 20 50 -:header-rows: 1 - -* - Value class - - Allowed characters -* - dateTimeClass - - digits, T, :, - -* - nameClass - - alphabetic characters, - -* - numericClass - - digits, ., -, +, E, e -* - posixPath - - As yet unspecified -* - textClass - - Alphanumeric characters, blank,
- +, -, :, ;, ., /, (, ), ?, *, %, $, @, ^, _ -`````` - -````{admonition} Notes on rules for allowed characters in the HED schema. -:class: tip - -1. Commas are not allowed in any values. -2. Date-times should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss. -3. Any variation on the full form of ISO8601 date-time is allowed. -4. The name class is for schema nodes and labels. -5. Values that have a value class of `numericClass` must be valid fixed point of floating point values. -6. Scientific notation is supported with the `numericClass`. -7. The text class is for descriptions, mainly for use with the *Description/* tag. -8. The posix path class is yet unspecified and currently allows any characters besides commas. - -```` - -### A.3.4. HED unit classes - -Unit classes allow annotators to express the units of values in a consistent way. -The plurals of the various units are not explicitly listed, but are allowed as HED -tools uses standard pluralize functions to expand the list of allowed units. However, -Unit symbols represent abbreviated versions of units and cannot be pluralized. - -Nodes with the `SIUnit` modifier may be prefixed with multiple or sub-multiple modifiers. -If the SI unit does not also have the `unitSymbol` attribute, then multiples and sub-multiples -with the `SIUnitModifier` attribute are used for the expansion. On the other hand, -units with both `SIUnit` and `SIUnitModifier` attributes are expanded using -multiples and sub-multiples having the `SIUnitSymbolModifier` attribute. - -Note that some units such as byte are designated as SI units, although they are not -part of the standard. - - -`````{list-table} Unit classes and units in HED 8.0.0 (* indicates unit symbol). -:widths: 20 10 40 -:header-rows: 1 - -* - Unit class - - Default units - - Units -* - accelerationUnits - - m-per-s^2 - - m-per-s^2* -* - angleUnits - - rad - - radian, rad*, degree -* - areaUnits - - m^2 - - metre^2, m^2* -* - currencyUnits - - $ - - dollar, $, point -* - frequencyUnits - - Hz - - hertz, Hz* -* - intensityUnits - - dB - - dB, candela, cd* -* - jerkUnits - - m-per-s^3 - - m-per-s^3* -* - memorySizeUnits - - B - - byte, B -* - physicalLength - - m - - metre, m*, inch, foot, mile -* - speedUnits - - m-per-s - - m-per-s*, mph, kph -* - timeUnits - - s - - second, s*, day, minute, hour -* - volumeUnits - - m^3 - - metre^3, m^3* -* - weightUnits - - g - - gram, g*, pound, lb -`````` - -### A.3.5. HED unit modifiers - -The unit modifiers are can be applied to SI base units to indicate multiples or -sub-multiples of the unit. Unit symbols are modified by unit symbol modifiers, whereas -non symbol SI units are modified by unit modifiers. - -`````{list-table} Unit modifiers (* indicates unit symbol modifier). -:widths: 20 50 -:header-rows: 1 +````{admonition} Example XML layout of the schema property definitions. +```xml -* - Schema attribute - - Description -* - deca, da* - - SI unit multiple representing 10^1 -* - hecto, h* - - SI unit multiple representing 10^2 -* - kilo, k* - - SI unit multiple representing 10^3 -* - mega, M* - - SI unit multiple representing 10^6 -* - giga, G* - - SI unit multiple representing 10^9 -* - tera, T* - - SI unit multiple representing 10^12 -* - peta, P* - - SI unit multiple representing 10^15 -* - exa, E* - - SI unit multiple representing 10^18 -* - zetta, Z* - - SI unit multiple representing 10^21 -* - yotta, Y* - - SI unit multiple representing 10^24 -* - deci, d* - - SI unit submultiple representing 10^−1 -* - centi, c* - - SI unit submultiple representing 10^−2 -* - milli, m* - - SI unit submultiple representing 10^−3 -* - micro, u* - - SI unit submultiple representing 10^−6 -* - nano, n* - - SI unit submultiple representing 10^−9 -* - pico, p* - - SI unit submultiple representing 10^−12 -* - femto, f* - - SI unit submultiple representing 10^−15 -* - atto, a* - - SI unit submultiple representing 10^−18 -* - zepto, z* - - SI unit submultiple representing 10^−21 -* - yocto, y* - - SI unit submultiple representing 10^−24 -`````` + + . . . + + valueClassProperty + Indicates that the schema attribute is meant to be applied to value classes. + + +``` +```` \ No newline at end of file diff --git a/docs/source/Appendix_B.md b/docs/source/Appendix_B.md index bb17168e..4426dcf5 100644 --- a/docs/source/Appendix_B.md +++ b/docs/source/Appendix_B.md @@ -2,144 +2,332 @@ This appendix summarizes the error codes used by HED validators and other tools. -HED tools for users (i.e., annotators and analysts) are mainly concerned with -HED validation errors relating to incorrectly annotated events.(See -[Chapter B.1: HED validation errors](#b1-hed-validation-errors) -for a listing.) These tools assume that the HED schema are error-free and that schema errors -can only occur due to failure to locate or read a HED schema. (See -[Chapter B.2: Schema validation errors](#b2-schema-validation-errors) for a listing.) - -HED schema developers are mainly concerned with errors and inconsistencies in the -schema itself. -(See [Chapter B.2: Schema validation errors](Appendix_B.md#b2-schema-validation-errors) -for a listing.) +HED-compliant tools may assume that it if a HED annotation has been properly validated, +it will comply with the rules of the HED specification. +Annotators and analysts are mainly concerned with +HED validation errors relating to incorrectly annotated events. +See [**B.1: HED validation errors**](#b1-hed-validation-errors) +for a listing of errors keyed to the HED specification. + +HED-compliant tools assume that the HED schemas available on the +[**hed-standard/hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository +are error-free, and that schema errors can only occur due to failure to locate or read a HED schema. + +HED schema developers are mainly concerned with errors and inconsistencies in the schema itself. +Schemas under development should be validated at all stages of development. +See [**B.2: Schema validation errors**](#b2-schema-validation-errors) for a listing +of errors keyed to the HED specification. + ## B.1. HED validation errors -**HED_CHARACTER_INVALID**: HED string contains an invalid character. - ~ HED uses ANSI encoding and does not support UTF-8. - ~ Different parts of a HED string have different rules for acceptable characters as outlined in -[Chapter 3.3: Allowed names and values](03_Schema.md#33-allowed-names-and-values). +### CHARACTER_INVALID + +A HED string contains an invalid character. + +**a.** The HED string contains a UTF-8 character. + +**b.** An extension or a value substituted for a `#` is not allowed by its value class. + +**Notes:** +- HED uses ANSI encoding and does not support UTF-8. +- Different parts of a HED string have different rules for acceptable characters. + +See +[**3.2.4 Tags that take values**](03_HED_formats.md#324-tags-that-take-values) and +[**3.2.5: Tag extensions**](03_HED_formats.md#325-tag-extensions) for +an explanation of the rules for tag values and extensions. -**HED_COMMA_MISSING**: HED tag groups and tags must be separated with commas. - ~ Commas missing between two HED tags are generally detected as invalid HED tags, +### COMMA_MISSING + +HED tag groups and tags must be separated with commas. +In the following `A`, `B`, `C`, and `D` represent HED expressions. + +**a.** Two tag groups are not separated by commas: (`A`, `B`)(`C`, `D`). +**b.** A tag and a tag group are not separated by commas: `A`(`B`,`D`). + +**Note:** Commas missing between two HED tags are generally detected as invalid HED tags, rather than as missing commas. -**HED_DEF_EXPAND_INVALID**: An expanded definition does not match the actual definition. - ~ A *Def-expand* tag label may not correspond to a definition. - ~ The tags within a *Def-expand* may not match the corresponding definition. - -**HED_DEF_UNMATCHED**: A HED *Def/* label cannot be matched to a definition name. - ~ A *Def* tag label cannot be correctly matched to a definition name because the -definition is missing or defined multiple times. - -**HED_DEF_VALUE_INVALID**: A *Def/* label value is missing or has incorrect format or value. -~ A *Def/* tag value is a schema node name. -~ A *Def/* tag value does not meet the requirements associated with the placeholder in -its definition tag group. -~ A *Def/* tag has a value, but its corresponding *Definition* does not have a placeholder. -~ A *Def/* tag does not have a value, but its corresponding *Definition* has a value. - -**HED_DEFINITION_INVALID**: The *Definition* syntax is incorrect or nested. - ~ A definition name is invalid or already appears as a schema node. - ~ A definition's enclosing tag group contains another *Definition/* tag. - ~ A definition contains *Def/* or *Def-expand/* tags. - ~ A definition that includes a placeholder (`#`) does not have exactly two `#` characters: -one after the definition name and one in the definition tag-group body. - ~ A definition has placeholders (`#`) in incorrect positions. - -**HED_LIBRARY_UNMATCHED:** A tag starting with *name:* does not have an associated library. - ~ A tag that starts with *name:* is interpreted as a library schema nickname name, but no -corresponding library schema has been defined. - -**HED_NODE_NAME_EMPTY:** An empty tag was detected in a HED string. - ~ A tag has extra slashes at beginning, end, or within a tag (implying empty node names). - ~ A HED string starts or ends with a slash. - ~ A HED tag contains consecutive slashes (as this implies a missing term name within a HED tag). - -**HED_ONSET_OFFSET_ERROR:** An *Onset* or *Offset* tag is used incorrectly. - ~ An *Onset* or *Offset* tag appears without being grouped with a defined name -(using a *Def-expand/* tag group or a *Def/* ). - ~ An *Offset* tag appears before an *Onset* tag with the same name (or name/value). - ~ An *Offset* tag of a given name appears after a previous *Offset* tag without the -appearance of an intervening *Onset* of the same name. - ~ An *Onset* tag group either lacks an internal tag group or has more than one internal -tag group. **Note:** if the *Onset* tag group's definition is in expanded form, -the *Def-expand* will be an additional internal tag group. - -**HED_PARENTHESES_MISMATCH:** A HED string has unmatched open and closed parentheses. - ~ A HED string does not have the same number of open and closed parentheses. - ~ Open and closed parentheses are not correctly nested. - -**HED_PLACEHOLDER_INVALID:** A `#` is missing or appears in a place that it should not. - ~ A JSON sidecar has a placeholder (`#`) in the HED dictionary for a categorical column. - ~ A JSON sidecar does not have exactly one placeholder (`#`) in each HED string representing a value column. - ~ A placeholder (`#`) is used but its parent in the schema does not have a placeholder child. - -**HED_REQUIRED_TAG_MISSING:** An event-level annotation missing a required tag. - ~ An assembled event string does not contain all tags that have the *required* schema attribute. - -**HED_SIDECAR_KEY_MISSING:** (WARNING) A categorical value is missing HED tags in sidecar. - ~ The events file column has a HED dictionary in the JSON sidecar but the categorical -value does not have a key in the sidecar dictionary. - -**HED_STYLE_WARNING:** (WARNING) An extension or label does not follow HED naming conventions. -~ A tag name does not start with a capital letter with the remainder lower case. - -**HED_TAG_EMPTY:** Extra commas or empty parentheses indicate empty tags. - ~ A HED string has multiple consecutive commas (ignoring white space). - ~ A HED string begins or ends with a comma (which implies an empty HED tag). - ~ A tag group is empty (i.e., empty parentheses are not allowed). - -**HED_TAG_EXTENDED:** (WARNING) HED tag represents an extension from the schema. - ~ This tag represents an extension of the HED schema. (Often such tags are really -spelling errors and not meant to extend the schema.) - -**HED_TAG_GROUP_ERROR:** A tag does not have its required tag group behavior. - ~ A tag has `tagGroup` or `topLevelTagGroup` attribute but is not in an appropriate tag group. - ~ A tag with the `topLevelTagGroup` attribute appears in same tag group as other tags with the `topLevelTagGroup` attribute. - -**HED_TAG_INVALID:** The tag is not valid in this schema. - ~ The tag has incorrect format for compliance with this schema. - ~ The tag is used as a tag extension or placeholder value while appearing elsewhere in the schema. - ~ The tag value is a schema node name. - -**HED_TAG_NOT_UNIQUE:** A HED tag appears multiple times. - ~ A HED tag with *unique* attribute appears more than once in an event-level HED string. - -**HED_TAG_REPEATED:** HED tags cannot be repeated in the same tag group or level. - ~ HED strings are not ordered, so *(B, C)* is equivalent to *(B, C)*. - ~ *(A, (A, B))* is not a duplicate. - ~ *(A, (B, C), A)* and *(A, (B, C), (C, B))* are duplicates. - -**HED_TAG_REQUIRES_CHILD:** A HED tag requires an additional ending node. - ~ The tag has the *requireChild* schema attribute but does not have a child. - -**HED_TILDES_UNSUPPORTED:** The tilde notation is no longer supported. - ~ The **tilde syntax is no longer supported** for any version of HED. - Annotators should replace the syntax *(A ~ B ~ C)* with *(A, (B, C))*. - ~ The tilde (`~`) is considered an invalid character in all versions of the schema. - -**HED_UNITS_DEFAULT_USED:** (WARNING) A HED tag value is missing units. - ~ If the corresponding unit class has default units, those are assumed. - -**HED_UNITS_INVALID:** HED tag value has incorrect or invalid units. - ~ A HED tag has a value with units that are invalid or not of the -correct unit class for the tag. - ~ A typical mistake is to use unit modifiers with units that are not SI units. - -**HED_VALUE_INVALID:** The value substituted for a placeholder (`#`) is not valid. - ~ A tag value is incompatible with the specified value class. - ~ A tag value with no value class is assumed to be a label and may contain invalid characters. - -**HED_VERSION_DEPRECATED:** (WARNING) The HED version is deprecated. - ~ It is strongly recommended that a current version be used as these deprecated -versions may not be supported in the future. - ~ Deprecated versions can be found in -[https://github.com/hed-standard/hed-specification/tree/master/hedxml/deprecated](https://github.com/hed-standard/hed-specification/tree/master/hedxml/deprecated). - -**HED_VERSION_WARNING:** (WARNING) The HED version number or HED schema was not provided or was invalid, so the latest version is used. +See [**3.2.7.3. Empty tags and groups**](./03_HED_formats.md#3273-empty-tags-and-groups) +for an explanation of the rules for empty tags. + +See also [**TAG_EMPTY**](./Appendix_B.md#tag_empty). + + +### DEF_EXPAND_INVALID + +**a.** A `Def-expand` tag's name does not correspond to a definition. +**b.** A `Def-expand` is missing an expected placeholder value or has an unexpected placeholder value. +**c.** A `Def-expand` has a placeholder value of incorrect format or units for definition. +**d.** The tags within a `Def-expand` do not match the corresponding definition. +**e.** A `Def-expand` tag group is missing its inner tag group. +**f.** A `Def-expand` tag group has extra tags or groups. + + +See [**3.2.8.2. The Def and Def-expand tags**](./03_HED_formats.md#3282-def-and-def-expand-tags) +for an explanation of the rules for `Def-expand` and +[**5.2. Using definition**](./05_Advanced_annotation.md#52-using-definitions) +for more details and examples. + + +### DEF_INVALID + +**a.** A `Def` tag's name does not correspond to a definition. +**b.** A `Def` tag is missing an expected placeholder value or has an unexpected placeholder value. +**c.** A `Def` has a placeholder value of incorrect format or units for definition. + +See [**3.2.8.2. The Def and Def-expand tags**](./03_HED_formats.md#3282-def-and-def-expand-tags) +for an explanation of the rules for `Def` and +[**5.2. Using definition**](./05_Advanced_annotation.md#52-using-definitions) +for more details and examples. + + +### DEFINITION_INVALID +A **definition** is a tag group containing a `Definition` tag and a single tag group with +the definition's contents. + +**a.** A `Definition` tag does not appear in a tag group at the top level in an annotation. +**b.** A definition's enclosing tag group is missing the inner tag group (.i.e., the definition's contents). +**c.** A definition's enclosing tag group contains more than a `Definition` tag and an inner group. +**d.** A definition's inner tag group contains `Definition`, `Def` or `Def-expand` tags. +**e.** A definition that includes a placeholder (`#`) does not have exactly two `#` characters. +**f.** A definition has placeholders (`#`) in incorrect positions. +**g.** Definitions of the same name appear with and without a `#`. +**h.** Multiple `Definition` tags with same name are encountered. +**i.** A tag with a `required` or `unique` attribute appears in a definition. +**j.** A definition appears in an unexpected place such as an events file. + +See [**3.2.8.1. The Definition tag**](./03_HED_formats.md#3281-the-definition-tag) +for an explanation of the rules for definitions. +See also [**5.1. Creating definitions**](./05_Advanced_annotation.md#51-creating-definitions) +and [**5.2. Using definitions**](./05_Advanced_annotation.md#52-using-definitions) +for more details and examples of definition syntax. + +### NODE_NAME_EMPTY + +**a.** A tag has one or more forward slashes (`/`) at beginning or end (ignoring whitespace). +**b.** A tag contains consecutive forward slashes (ignoring whitespace). + +See [**3.2.3 Tag forms**](./03_HED_formats.md#322-tag-forms) for more information. + +### ONSET_OFFSET_ERROR + +Note: For the purpose of `Onset`/`Offset` matching, `Def` or `Def-expand` tags with +different placeholder substitutions are considered to be different. + +**a.** An `Onset` or `Offset` tag does not appear in a tag group. +**b.** An `Onset` or `Offset` tag appears in a nested tag group (not a top-level tag group). +**c.** An `Onset` or `Offset` tag is not grouped with exactly one `Def` tag or `Def-expand-group`. +**d.** An `Onset` group has more than one additional tag group. +**e.** An `Offset` appears with one or more tags or additional tag groups. +**f.** An `Offset` tag appears before an `Onset` tag associated with the same definition. +**g.** An `Offset` tag associated with a given definition appears after a previous `Offset` tag. +without the appearance of an intervening `Onset` of the same name. +**h.** An `Onset` tag group with has tags besides the anchor `Def` or `Def-expand-group` +that are not in a tag group. +**i.** An `Onset` or an `Offset` with a given `Def` or `Def-expand-group` anchor appears in the same +event marker with another `Onset` or `Offset` that uses the same anchor. + + +**Note:** if the `Onset` tag group's definition is in expanded form, +the `Def-expand` will be an additional internal tag group. + +See [**3.2.8.3 Onset and Offset tags**](./03_HED_formats.md#3283-onset-and-offset-tags) +for a specification of the required behavior of `Onset` and `Offset`. + +[**5.3.1. Using Onset and Offset**](./05_Advanced_annotation.md#531-using-onset-and-offset) +in Chapter 5 gives examples of usage and additional details. + +### PARENTHESES_MISMATCH + +**a.** A HED string does not have the same number of open and closed parentheses. +**b.** The open and closed parentheses are not correctly nested in the HED string. + +See [**3.2.7.1. Parentheses and order**](./03_HED_formats.md#3271-parenthesis-and-order) +for the rules for parentheses in HED. + +### PLACEHOLDER_INVALID + +**a.** A `#` appears in a place that it should not (such as in the `HED` column of an events file). +**b.** A JSON sidecar has a placeholder (`#`) in the HED dictionary for a categorical column. +**c.** A JSON sidecar does not have exactly one placeholder (`#`) in each HED string representing a value column. +**d.** A placeholder (`#`) is used in JSON sidecar or definition, but its parent in the schema does not have a placeholder child. + +See [**3.2.4. Tags that take values**](./03_HED_formats.md#324-tags-that-take-values) +and [**3.2.9.1. Sidecar entries**](./03_HED_formats.md#3291-sidecar-entries) for +information on the use of placeholders in HED. + +### REQUIRED_TAG_MISSING + +**a.** An event-level annotation does not have a tag corresponding to a node with the `required` +schema attribute. + + +**Note:** +An assembled event string must include all tags having the *required* schema attribute. + +See [**3.2.10.2. Event-level processing**](./03_HED_formats.md#32102-event-level-processing) for +additional information on the `required` tag. + +### SIDECAR_INVALID + +**a.** The `"HED"` key is not a second-level dictionary key. +**b.** An annotation entry is provided for `n/a`. + +See [**3.2.9.2. Sidecar validation**](./03_HED_formats.md#3292-sidecar-validation) for a +general explanation of sidecar requirements. + +### SIDECAR_KEY_MISSING* +(WARNING) + +**a.** A value in a categorical column does not have an expected entry in a sidecar. + +**Note:** This warning is only triggered if the categorical column in which the value +appears does have HED annotations. + +See [**3.2.9. Sidecars**](./03_HED_formats.md#329-sidecars) for a +general explanation of sidecar requirements. + +### STYLE_WARNING* + +(WARNING) +**a.** An extension or label does not follow HED naming conventions. + +See [**3.1.3. Naming conventions**](./03_HED_formats.md#313-naming-conventions) +for an explanation of HED naming conventions. + +### TAG_EMPTY +**a.** A HED string has extra commas or parentheses separated by only white space, indicating empty tags. +**b.** A HED string begins or ends with a comma (ignoring white space), indicating an empty string. +**c.** A tag group is empty (i.e., empty parentheses are not allowed). + +See [**3.2.7.3. Empty tags and groups**](./03_HED_formats.md#3273-empty-tags-and-groups) +for the rules on empty tags and groups. + +### TAG_EXPRESSION_REPEATED + +**a.** A tag is repeated in the same tag group or level. + +Suppose `A`, `B`, and `C` represent HED expressions. +HED strings are not ordered, so (`B`, `C`) is equivalent to (`B`, `C`). +Thus, (`A`, (`A`, `B`)) is not a duplicate, but +(`A`, (`B`, `C`), `A`) and (`A`, (`B`, `C`), (`C`, `B`)) are duplicates. + +See [**3.2.7.4. Repeated expressions**](./03_HED_formats.md#3274-repeated-expressions) +for additional information on the rules for duplication. + +### TAG_EXTENDED* +(WARNING) + +**a.** A tag represents an extension from the schema. + +**Note:** Often such extensions are really spelling errors and not meant to extend the schema. + +**Note:** Annotators are discouraged from extending the schema unless absolutely necessary. +If an extension tag is needed, annotators should consider posting an +[**issue**](https://github.com/hed-standard/hed-schemas/issues) +explaining the tag extension so that an addition to the respective schema might be +considered. + +See [**3.2.5 Tag extensions**](./03_HED_formats.md#325-tag-extensions) +for additional information on the tag extension rules. + +### TAG_EXTENSION_INVALID + +**a.** A tag extension term is already in the schema. +**b.** A tag extension term does not comply with rules for schema nodes. + +See [**3.2.5 Tag extensions**](./03_HED_formats.md#325-tag-extensions) +for additional information on the tag extension rules. + +### TAG_GROUP_ERROR + +**a.** A tag has `tagGroup` or `topLevelTagGroup` attribute, but is not enclosed in parentheses. +**b.** A tag with the `topLevelTagGroup` does not appear at a HED tag group at the top level in an assembled HED annotation. +**c.** Multiple tags with the `topLevelTagGroup` attribute appear in the same top-level tag group. + +See [**3.2.7.2. Tag group attributes**](./03_HED_formats.md#3272-tag-group-attributes) +for additional information on the rules for group errors due to schema attributes. + +### TAG_INVALID + +**a.** The tag is not valid in the schema it is associated with. + +See [**3.2.2. Tag forms**](./03_HED_formats.md#322-tag-forms) for a discussion +of tag forms and their relationship to the HED schema. + +### TAG_NOT_UNIQUE + +**a.** A tag with `unique` attribute appears more than once in an event-level HED string. + +See [**3.2.10.2. Event-level processing**](./03_HED_formats.md#32102-event-level-processing) for +additional information on the `unique` tag. + +### TAG_PREFIX_INVALID + +**a.** A tag starting with *name:* does not have an associated schema. +**b.** A tag prefix has invalid characters. + +See [**3.2.6. Tag prefixes**](./03_HED_formats.md#326-tag-prefixes) and +[**7. Library schema**](./07_Library_schemas.md) for additional information +on using multiple schemas in annotation. + +### TAG_REQUIRES_CHILD + +**a.** A tag has the `requireChild` schema attribute but does not have a child. + +See [**3.2.4. Tags that take values**](03_HED_formats.md#324-tags-that-take-values) +for an explanation of the `requireChild` attribute. + +### TILDES_UNSUPPORTED + +The tilde notation is not supported. + +**a.** The **tilde syntax is no longer supported** for any version of HED. + Annotators should replace the syntax (`A` ~ `B` ~ `C`) with (`A`, (`B`, `C`)). +**b.** The tilde (`~`) is considered an invalid character in all versions of the schema. + +### UNITS_INVALID + +**a.** A tag has a value with units that are invalid or not of the +correct unit class for the tag. +**b.** A unit modifier is applied to units that are not SI units. + + +### UNITS_MISSING* +(WARNING) + +**a.** A tag that takes value and has a unit class does not have units. + +See [**3.2.4 Tags that take values**](./03_HED_formats.md#324-tags-that-take-values) +for more information. + +### VALUE_INVALID + +**a.** The value substituted for a placeholder (`#`) is not valid. +**b.** A tag value is incompatible with the specified value class. +**c.** A tag value with no value class is assumed to be a text and contains invalid characters. +**d.** The units are not separated from the value by a single blank. + +See [**3.2.4 Tags that take values**](./03_HED_formats.md) for more information. + +### VERSION_DEPRECATED* +(WARNING) + +**a.** The HED schema version being used as been deprecated. + +It is strongly recommended that a current schema version be used as these deprecated +versions may not be supported in the future. Deprecated versions can be found in the +[**standard_schema/hedxml/deprecated**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema/hedxml/deprecated) subdirectory +or the corresponding subdirectory for individual library schemas in +the [**hed-standard/hed-schemas**](https://github.com/hed-standard/hed-schemas) +GitHub repository. + +**Note:** Support for versions of the schema less than 8.0.0 is being phased out. +If you are using a deprecated version, you may need to switch to an earlier version +of the HED validators. ## B.2. Schema validation errors @@ -150,47 +338,75 @@ occur in the construction of the XML version or that are detected by XML validat when the planned XSD validation is implemented start with HED_XML. -### B.2.2. General validation schema errors +### B.2.1. General validation errors + +#### LIBRARY_NAME_INVALID + +**a.** The specified library name is not alphabetic or lowercase. -**HED_SCHEMA_ATTRIBUTE_INVALID:** An attribute not defined in the appropriate schema section. - ~ The `unitClass` attribute must be defined in the `unitClassDefinitions` section of the schema. - ~ A `unitClass` attribute has an invalid suffix because it is not a plural or unit modifier. - ~ A `valueClass` attribute must be defined in the `valueClassDefinitions` section of the schema. - ~ An schema attribute is not defined in the `schemaAttributeDefinitions` section. +#### SCHEMA_ATTRIBUTE_INVALID -**HED_SCHEMA_CHARACTER_INVALID:** The specification contains an invalid character. +**a.** An attribute is used in the schema, but is not defined in the schema attribute section. +**b.** A schema attribute is applied to the incorrect type (e.g., an element with the unit definition does appear +under an appropriate unit class). -**HED_SCHEMA_DUPLICATE_NODE:** A schema node name appears in the schema more than once. +**Note:** +- A `unitClass` attribute must be defined in the `unitClassDefinitions` section of the schema. +- A `valueClass` attributes must be defined in the `valueClassDefinitions` section of the schema. +- A `schemaAttribute` must be defined in the `schemaAttributeDefinitions` section of the schema. -**HED_SCHEMA_HEADER_INVALID:** The schema header is invalid. - ~ The head has invalid characters or format. - ~ The header has unrecognized attributes. +#### SCHEMA_CHARACTER_INVALID -**HED_SCHEMA_NODE_NAME_INVALID:** Schema node name is empty or contains invalid characters. +**a.** The specification contains an invalid character for the section in which it appears. -**HED_SCHEMA_REQUIRED_SECTION_MISSING:** A required schema section is missing. - ~ The required sections (corresponding to the schema, unit classes, unit modifiers, value classes, schema attributes, and properties) are not in the correct order. - ~ Required schema sections may be empty, but still be given. +#### SCHEMA_DUPLICATE_NODE -**HED_SCHEMA_VERSION_INVALID:** The schema version in the HED line or element is invalid. - ~ A HED version specification does not have the correct syntax for the schema file format. - ~ A HED schema version does not comply with semantic versioning. +**a.** A schema node name appears in the schema more than once. +#### SCHEMA_HEADER_INVALID -### B.2.3. Format-specific schema errors. +**a.** The schema header has invalid characters or format. +**b.** The schema header has unrecognized attributes. -**HED_WIKI_DELIMITERS_INVALID:** Delimiters used in the wiki are invalid. - ~ Schema line content after node name is not enclosed with `` delimiters. - ~ A line has unmatched or multiple ``, `[ ]`, or `{ }` delimiters. +#### SCHEMA_SECTION_MISSING -**HED_WIKI_LINE_START_INVALID:** Start of body line not `'''` or `*`. +**a.** A required schema section is missing. +**b.** The required sections (corresponding to the schema, unit classes, unit modifiers, value classes, +schema attributes, and properties) are not in the correct order and hence not detected. -**HED_WIKI_SEPARATOR_INVALID:** Required wiki section separator is missing or misplaced. - ~ A required schema separator is missing. (The required separators are: `!# start schema`, `!# end schema`, and `!# end hed`.) +**Note:** Required schema sections may be empty, but still be given. -**HED_XML_SYNTAX_INVALID:** XML syntax or does not comply with specified XSD. +#### SCHEMA_VERSION_INVALID -### B.3. Schema loading errors +**a.** The schema version in the HED line or element is invalid. +**b.** A HED version specification does not have the correct syntax for the schema file format. +**c.** A HED schema version does not comply with semantic versioning. + + +### B.2.2. Mediawiki format errors + +#### WIKI_DELIMITERS_INVALID + +**a.** Delimiters used in the wiki are invalid. +**b.** Schema line content after node name is not enclosed with `` delimiters. +**c.** A line has unmatched or multiple ``, `[ ]`, or `{ }` delimiters. + +#### WIKI_LINE_START_INVALID + +**a.** Start of body line not `'''` or `*`. + +#### WIKI_SEPARATOR_INVALID + +**a.** Required wiki section separator is missing or misplaced. +**b.** A required schema separator is missing. (The required separators are: `!# start schema`, `!# end schema`, and `!# end hed`.) + +### B.2.3. XML format errors + +#### XML_SYNTAX_INVALID + +**a.** XML syntax or does not comply with specified XSD. + +### B.2.4 Schema loading errors Schema loading errors can occur because the file is inaccessible or is not proper XML. Schema loading errors are handled in different ways by the Python and JavaScript tools. @@ -209,11 +425,10 @@ BIDS validator users do not always have unrestricted access to the Internet during the validation process. The HED JavaScript tools have a fallback of the loading of the specified schema fails. The validator loads an internal copy of the most recent version of the HED schema and loads it. However, it -also reports a **HED_SCHEMA_LOAD_FAILED** issue to alert the user that the schema used +also reports a `SCHEMA_LOAD_FAILED` issue to alert the user that the schema used for validation may not be the one designated in the dataset. However, validation will continue with the fallback schema. If the fallback schema stored with the HED validator fails to load, -the **HED_SCHEMA_LOAD_FAILED** issue will also be reported and no additional +the `SCHEMA_LOAD_FAILED` issue will also be reported and no additional HED validation will occur. - diff --git a/docs/source/HedResources.md b/docs/source/HedResources.md index 8ae1aced..3eb18896 100644 --- a/docs/source/HedResources.md +++ b/docs/source/HedResources.md @@ -5,7 +5,7 @@ Explanation of the history, development, and motivation for third generation HED: -> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2021). +> Robbins, K., Truong, D., Jones, A., Callanan, I., & Makeig, S. (2022). > Building FAIR functionality: Annotating events in time series data using Hierarchical Event Descriptors (HED). > Neuroinformatics Special Issue Building the NeuroCommons. Neuroinformatics https://doi.org/10.1007/s12021-021-09537-4. > [https://link.springer.com/article/10.1007/s12021-021-09537-4](https://link.springer.com/article/10.1007/s12021-021-09537-4). diff --git a/docs/source/UnderDiscussion.md b/docs/source/UnderDiscussion.md new file mode 100644 index 00000000..0750ab7d --- /dev/null +++ b/docs/source/UnderDiscussion.md @@ -0,0 +1,6 @@ +# Under discussion + +The sections here are proposed and are not part of the HED specification. + + +## Square brackets \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/CHARACTER_INVALID.json b/docs/source/_static/data/error_tests/CHARACTER_INVALID.json new file mode 100644 index 00000000..92f454fb --- /dev/null +++ b/docs/source/_static/data/error_tests/CHARACTER_INVALID.json @@ -0,0 +1,178 @@ + [ + { + "error_code": "CHARACTER_INVALID", + "name": "character-invalid-utf-8", + "description": "The HED string contains a UTF-8 character.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Description/This is a ʰ bad character" + ], + "passes": [ + "Red, Blue, Description/Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "show": "Red, Label/a ʰ bad" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "show": "Red, Label/Good" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Label/a ʰ bad"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Label/Temp"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "show": "Red, Label/a ʰ bad", + "ball": "Def/Acc/4.5 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "show", "Description/a ʰ good"], + [ 5.0, 0, "ball", "Blue"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "show": "Red, Label/a" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "show", "Description/goodness"] + ] + } + ] + } + } + }, + { + "error_code": "CHARACTER_INVALID", + "name": "character-invalid-#-value-class", + "description": "An extension or a value substituted for a `#` is not allowed by its value class.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": ["Acceleration/banana", "Def/Acc/apple3, Blue"], + "passes": ["Acceleration/3.4 m-per-s^2", "Def/Acc/10.1 m-per-s^2"] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Acceleration/6.8 m-per-s^2", + "ball": "Def/Acc/5.433 m-per-s^2, Blue" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Acceleration/banana"], + [ 5.5, 0, "Def/Acc/apple3, Blue"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Acceleration/6.8 m-per-s^2"], + [ 5.5, 0, "Def/Acc/5.433 m-per-s^2, Blue"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7 m-per-s^2, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/COMMA_MISSING.json b/docs/source/_static/data/error_tests/COMMA_MISSING.json new file mode 100644 index 00000000..aec6f6af --- /dev/null +++ b/docs/source/_static/data/error_tests/COMMA_MISSING.json @@ -0,0 +1,192 @@ +[ + { + "error_code": "COMMA_MISSING", + "name": "comma-missing-tag-groups", + "description": "Two tag groups are not separated by commas: (A, B)(C, D).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Red, Blue)(Green, (Yellow))", + "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)" + ], + "passes": [ + "(Red, Blue), (Green, (Yellow))", + "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue)(Green, (Yellow))", + "ball": "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, ( Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Red, Blue)(Green, (Yellow))"], + [ 5.5, 0, "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Red, Blue), (Green, (Yellow))"], + [ 5.5, 0, "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red, Blue)(Green, (Yellow))", + "ball": "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"], + [ 6.0, 0, "n/a", "(Blue, Green)(Blue, Red)"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, ( Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "(Green, Def/MyColor),(Red)"] + ] + } + ] + } + } + }, + { + "error_code": "COMMA_MISSING", + "name": "comma-missing-tag-and-group", + "description": "A tag and a tag group are not separated by commas: A(B,D).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red, Blue(Green, (Yellow))", + "(Def/MyColor, Onset)Def/Acc/3.5 m-per-s^2" + ], + "passes": [ + "Red, (Green, (Yellow))", + "(Def/MyColor, Onset),Def/Acc/3.5 m-per-s^2" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red(Green, (Yellow))", + "ball": "(Def/MyColor, Onset)Def/Acc/3.5 m-per-s^2" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red, (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),Def/Acc/3.5 m-per-s^2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red(Green, (Yellow))"], + [ 5.5, 0, "(Def/MyColor, Onset)Def/Acc/3.5 m-per-s^2"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, (Green, (Yellow))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red(Green, (Yellow))", + "ball": "(Def/MyColor, Onset)Def/Acc/3.5 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"], + [ 6.0, 0, "n/a", "(Green, Yellow)Red"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red, (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),Def/Acc/3.5 m-per-s^2" } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/DEFINITION_INVALID.json b/docs/source/_static/data/error_tests/DEFINITION_INVALID.json new file mode 100644 index 00000000..e0e11df1 --- /dev/null +++ b/docs/source/_static/data/error_tests/DEFINITION_INVALID.json @@ -0,0 +1,803 @@ +[ + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-tag-group", + "description": "A Definition tag does not appear in a tag group at the top level in an annotation.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Definition/Apple, (Blue)), ((Definition/Blech, (Red)))", + "Definition/Blech, (Red)" + ], + "passes": [ + "(Definition/Blech, (Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue)), ((Definition/Blech, (Red)))", + "def2": "Definition/Blech, (Red)" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Blech, (Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue)), ((Definition/Blech, (Red)))", + "def2": "Definition/Blech, (Red)" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/MyColor, Def/Apple"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue))", + "def2": "(Definition/Blech, (Red))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/MyColor, Def/Apple"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-missing-inner-group", + "description": "A definition's enclosing tag group is missing the inner tag group (.i.e., the definition's contents).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple)" + } + } + }, + { + "defs": { + "HED": { + "def2": "(Definition/Blech/#, ())" + } + } + } + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple), ((Definition/Blech, (Red)))", + "def2": "(Definition/Blech/#, ())" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/MyColor, Def/Apple"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue))", + "def2": "(Definition/Blech, (Red))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/MyColor, Def/Apple"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-multiple-definition-tags", + "description": "A definition's enclosing tag group contains more than a `Definition` tag and an inner group.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, Definition/Banana, (Blue))", + "def2": "(Definition/Blech, (Red), Definition/Banana1)", + "def3": "(Definition/Blech1, (Red), Blue)" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue))", + "def2": "((Red), Definition/Blech)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, Definition/Banana, (Blue))", + "def2": "(Definition/Blech, (Red), Definition/Banana1)", + "def3": "(Definition/Blech1, (Red), Blue)" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple, Def/Banana"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue))", + "def2": "((Red), Definition/Blech)" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech, Def/Apple"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-inner-group-defs", + "description": "A definition's inner tag group contains `Definition`, `Def` or `Def-expand` tags.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Definition/Banana, Blue))", + "def2": "(Definition/Blech, (Red, Def/Apple))" + } + } + } + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Label/a"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Definition/Banana, (Blue)))", + "def2": "(Definition/Blech, ((Red), Def/MyColor))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple, Def/Banana"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Blue))", + "def2": "((Red), Definition/Blech)" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech, Def/Apple"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-bad-number-of-placeholders", + "description": "A definition that includes a placeholder (`#`) does not have exactly two `#` characters.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#, Description/#))", + "def2": "(Definition/Blech/#, (Red))" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech/#, (Red, Label/#))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#, Description/#))", + "def2": "(Definition/Blech/#, (Red))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple/3, Def/Blech/might"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech/#, (Red, Label/#))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech/5, Def/Apple/4"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-placeholder-incorrect-of-positions", + "description": "A definition has placeholders (`#`) in incorrect positions.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Label/#))", + "def2": "(Definition/Blech/#, (Red, #))" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Label/Blue))", + "def2": "(Definition/Blech/#, (Label/#, Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Label/#))", + "def2": "(Definition/Blech/#, (Red, #))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple, Def/Blech/might"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech/#, (Red, Label/#))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech/5, Def/Apple/4"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-placeholder-conflict", + "description": "Definitions of the same name appear with and without a `#`.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Label/#))", + "def2": "(Definition/Apple/#, (Red, #))" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Blech/#, (Label/#))", + "def2": "(Definition/Apple, (Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Label/#))", + "def2": "(Definition/Apple/#, (Red, #))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple/3, Def/Apple"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech, (Red))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech, Def/Apple/4"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-invalid-multiple-definitions", + "description": "Multiple `Definition` tags with same name are encountered.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#, Description/#))", + "def2": "(Definition/Apple/#, (Label/#))", + "def3": "(Definition/MyColor, (Blue))" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/ThisIsALabel, Description/#))", + "def2": "(Definition/Apple2/#, (Label/#))", + "def3": "(Definition/MyColor2, (Blue))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#, Description/#))", + "def2": "(Definition/Apple/#, (Label/#))", + "def3": "(Definition/MyColor, (Blue))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple/3, Def/Blech/might"], + [ 5.0, 0, "Def/MyColor"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech/#, (Red, Label/#))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech/5, Def/Apple/4"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-has-unique-or-required-tag", + "description": "A tag with a required or unique attribute appears in a definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Event-context, Item, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Event-context, Red))", + "def2": "(Definition/Banana/#, (Label/#))" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Red))", + "def2": "(Definition/Banana/#, (Label/#))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Event-context, Red))", + "def2": "(Definition/Banana/#, (Label/#))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple, Def/Banana/might"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple, (Red))", + "def2": "(Definition/Banana/#, (Label/#))" } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple, Def/Banana/might"] + ] + } + ] + } + } + }, + { + "error_code": "DEFINITION_INVALID", + "name": "definition-not-allowed-here", + "description": "A definition appears in an unexpected place such as an events file.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Event-context, Item, (Label/Pie)))"], + "tests": { + "string_tests": { + "fails": [ + "Red, Blue, (Definition/myDef, (Label/Red, Blue))" + ], + "passes": [ + "Red, Blue" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red, Blue, (Definition/myDef, (Label/Red, Blue))", + "ball": "Def/Acc/4.5 m-per-s^2" + } + } + } + ], + "passes": [ + { + "defs": { + "HED": { + "face": "(Definition/myDef, (Label/Red, Blue)), (Definition/myDef2, (Label/Red, Blue))", + "ball": "(Definition/myDef1, (Label/Red, Blue))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Definition/myDef, (Label/Red, Green))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, Blue, Def/MyColor"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red, Blue, (Definition/myDef, (Label/Red, Blue))", + "ball": "Def/Acc/4.5 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/myDef, Red"] + ] + } + ], + "passes": [ + { + "sidecar": { + "defs": { + "HED": { + "def1": "(Definition/Apple/#, (Label/#))", + "def2": "(Definition/Blech/#, (Red, Label/#))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Blech/5, Def/Apple/4"] + ] + } + ] + } + } + } +] diff --git a/docs/source/_static/data/error_tests/DEF_EXPAND_INVALID.json b/docs/source/_static/data/error_tests/DEF_EXPAND_INVALID.json new file mode 100644 index 00000000..d13923fa --- /dev/null +++ b/docs/source/_static/data/error_tests/DEF_EXPAND_INVALID.json @@ -0,0 +1,585 @@ +[ + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-invalid-name-not-definition", + "description": "A `Def-expand` tag's name does not correspond to a definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc2/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "(Def-expand/MyColor2, (Label/Pie))" + ], + "passes": [ + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc2/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/MyColor2, (Label/Pie))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/MyColor, (Label/Pie))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc2/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/MyColor2, (Label/Pie))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/MyColor, (Label/Pie))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc2/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/MyColor2, (Label/Pie)))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"], + [ 5.0, 0, "ball", "(Def-expand/Junk, (Label/Red))"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/MyColor, (Label/Pie))" + } + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/MyColor, (Label/Pie))"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-invalid-missing-placeholder", + "description": "A `Def-expand` is missing an expected placeholder value or has an unexpected placeholder value.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc, (Acceleration, Red))", + "(Def-expand/Acc/4.5/3, (Acceleration, Red))", + "(Def-expand/MyColor2/4, (Label/Pie))" + ], + "passes": [ + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc, (Acceleration, Red))", + "ball": "(Def-expand/Acc/4.5/3, (Acceleration, Red))", + "circle": "(Def-expand/MyColor2/4, (Label/Pie))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc, (Acceleration, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5/3, (Acceleration, Red))"], + [ 6.5, 0, "(Def-expand/MyColor2/4, (Label/Pie))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc, (Acceleration, Red))", + "ball": "(Def-expand/Acc/4.5/3, (Acceleration, Red))", + "circle": "(Def-expand/MyColor2/4, (Label/Pie))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face"," (Def-expand/Acc, (Acceleration, Red))"], + [ 5.5, 0, "ball","(Def-expand/Acc/4.5/3, (Acceleration, Red))"], + [ 5.6, 0, "circle","(Def-expand/Acc/4.5/3, (Acceleration, Red))"], + [ 6.5, 0, "n/a", "(Def-expand/MyColor2/4, (Label/Pie))"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"], + [ 5.0, 0, "ball", "(Def-expand/MyColor, (Label/Pie))"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-invalid-bad-placeholder-units", + "description": "A `Def-expand` has a placeholder value of incorrect format or units for definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc/Make-me, (Acceleration/Make-me, Red))", + "(Def-expand/Acc/4.5 m, (Acceleration/4.5 m, Red))", + "(Def-expand/Acc/4.5m-per-s^2, (Acceleration/4.5m-per-s^2, Red))" + ], + "passes": [ + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/Make-me, (Acceleration/Make-me, Red))", + "ball": "(Def-expand/Acc/4.5 m, (Acceleration/4.5 m, Red))", + "square": "(Def-expand/Acc/4.5m-per-s^2, (Acceleration/4.5m-per-s^2, Red))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/Make-me, (Acceleration/Make-me, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m, (Acceleration/4.5 m, Red))"], + [ 6.3, 0, "(Def-expand/Acc/4.5m-per-s^2, (Acceleration/4.5m-per-s^2, Red))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/Make-me, (Acceleration/Make-me, Red))", + "ball": "(Def-expand/Acc/4.5 m, (Acceleration/4.5 m, Red))", + "square": "(Def-expand/Acc/4.5m-per-s^2, (Acceleration/4.5m-per-s^2, Red))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "(Def-expand/Acc/Make-me, (Acceleration/Make-me, Red))"], + [ 5.5, 0, "ball", "(Def-expand/Acc/4.5 m, (Acceleration/4.5 m, Red))"], + [ 6.3, 0, "square", "(Def-expand/Acc/4.5m-per-s^2, (Acceleration/4.5m-per-s^2, Red))"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "(Def-expand/Acc/5.5 m-per-s^2, (Acceleration/5.5 m-per-s^2, Red))"], + [ 5.5, 0, "ball", "(Def-expand/Acc/5.5 m-per-s^2, (Acceleration/5.5 m-per-s^2, Red))"], + [ 6.5, 0, "n/a", "n/a"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-invalid-tags-not-in-definition", + "description": "The tags within a Def-expand do not match the corresponding definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/6, Red))", + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Blue))", + "(Def-expand/MyColor, (Label/Cake))" + ], + "passes": [ + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/6, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Blue))", + "square": "(Def-expand/MyColor, (Label/Cake))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/6, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Blue))"], + [ 6.3, 0, "(Def-expand/MyColor, (Label/Cake))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/6, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Blue))", + "square": "(Def-expand/MyColor, (Label/Cake)))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/6, Red))"], + [ 5.5, 0, "ball", "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Blue))"], + [ 6.3, 0, "square", "(Def-expand/MyColor, (Label/Cake))"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "(Def-expand/Acc/6.5 m-per-s^2, (Acceleration/6.5 m-per-s^2, Red))"], + [ 5.5, 0, "ball", "(Def-expand/Acc/8.5 m-per-s^2, (Acceleration/8.5 m-per-s^2, Red))"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-missing-inner-group", + "description": "A Def-expand is missing its inner group containing the definition.", + "schema": "8.1.0", + "definitions": [ + "(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Event-context, Item, (Label/Pie)))" + ], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc/5.4 m-per-s^2)" + ], + "passes": [ + "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, Red)", + "ball": "(Def-expand/Acc/4.5 m-per-s^2)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))", + "ball": "Red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, Red)"], + [5.4, 0, "(Def-expand/Acc/5.4 m-per-s^2)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2)", + "ball": "Blue" + } + } + }, + "events": [ + ["onset", "duration", "event_code", "HED"], + [4.5, 0, "ball", "Def/Acc, (Def-expand/Acc/4.5 m-per-s^2)"], + [5.4, 0, "n/a", "Green"], + [6.4, 0, "face", "n/a"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))", + "ball": "(Acceleration/4.5 m-per-s^2, Blue), Def/MyColor" + } + } + }, + "events": [ + ["onset", "duration", "event_code", "HED"], + [4.5, 0, "face", "n/a"], + [6.5, 0, "ball", "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_EXPAND_INVALID", + "name": "def-expand-has-extras", + "description": "A Def-expand has extra tags or groups.", + "schema": "8.1.0", + "definitions": [ + "(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Event-context, Item, (Label/Pie)))" + ], + "tests": { + "string_tests": { + "fails": [ + "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), Blue)", + "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), (Blue, Green), Black)" + ], + "passes": [ + "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), Blue)", + "ball": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), (Blue, Green), Black)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))", + "ball": "Red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), Blue)"], + [5.4, 0, "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), (Blue, Green), Black)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), Blue)", + "ball": "Blue" + } + } + }, + "events": [ + ["onset", "duration", "event_code", "HED"], + [4.5, 0, "ball", "Def/Acc, (Def-expand/Acc/4.5 m-per-s^2)"], + [5.4, 0, "n/a", "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red), Blue)"], + [6.4, 0, "face", "n/a"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))", + "ball": "(Acceleration/4.5 m-per-s^2, Blue), Def/MyColor" + } + } + }, + "events": [ + ["onset", "duration", "event_code", "HED"], + [4.5, 0, "face", "n/a"], + [6.5, 0, "ball", "(Def-expand/Acc/5.4 m-per-s^2, (Acceleration/5.4 m-per-s^2, Red))"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/DEF_INVALID.json b/docs/source/_static/data/error_tests/DEF_INVALID.json new file mode 100644 index 00000000..826298ff --- /dev/null +++ b/docs/source/_static/data/error_tests/DEF_INVALID.json @@ -0,0 +1,292 @@ +[ + { + "error_code": "DEF_INVALID", + "name": "def-invalid-name", + "description": "A `Def` tag's name does not correspond to a definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Apple2, Green", + "Def/Acc2/4.5", + "Def/Acc" + ], + "passes": [ + "Def/Acc/4.5 m-per-s^2" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Apple2, Green", + "ball": "Def/Acc2/4.5, Def/Acc/3.2 m-per-s^2" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/4.5 m-per-s^2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Apple2, Green"], + [ 5.5, 0, "Def/Acc2/4.5 m-per-s^2"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/4.5 m-per-s^2"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Apple2, Green", + "ball": "Def/Acc2/4.5, Def/Acc/3.2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "Def/Apple2, Green"], + [ 5.5, 0, "face", "Def/Acc2/4.5 m-per-s^2"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/4.5 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_INVALID", + "name": "def-invalid-missing-placeholder", + "description": "A `Def` tag is missing an expected placeholder value or has an unexpected placeholder value.", + "schema": "8.1.0", + "definitions":["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc, (Def/Acc/4.5 m-per-s^2, Red)", + "Def/MyColor/Blue" + ], + "passes": [ + "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc, (Def/Acc/4.5 m-per-s^2, Red)", + "ball": "(Def/MyColor/Blue, Green)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/4.5 m-per-s^2, Red", + "ball": "(Acceleration/4.5 m-per-s^2, Red), Def/MyColor" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc, (Def/Acc/4.5 m-per-s^2, Red)"], + [ 5.4, 0, "Def/MyColor/Blue, Green"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc, (Def/Acc/4.5 m-per-s^2, Red)", + "ball": "(Def/MyColor/Blue, Green)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "Def/Acc, (Def/Acc/4.5 m-per-s^2, Red)"], + [ 5.4, 0, "n/a", "Def/MyColor/Blue, Green"], + [ 6.4, 0, "face", "n/a"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/4.5 m-per-s^2, Red", + "ball": "(Acceleration/4.5 m-per-s^2, Red), Def/MyColor" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Def/Acc/5.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)"], + [ 6.5, 0, "ball", "n/a"] + ] + } + ] + } + } + }, + { + "error_code": "DEF_INVALID", + "name": "def-invalid-bad-placeholder-units", + "description": "A `Def` has a placeholder value of incorrect format or units for definition.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc/baloney, (Def/Acc/4.5 m-per-s^2, Red)", + "Def/Acc/3 m", + "Def/Acc/4m-per-s^2", + "Def/MyColor/Redish" + ], + "passes": [ + "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/baloney, (Def/Acc/4.5 m-per-s^2, Red)", + "ball": "Def/Acc/3 m", + "square": "Def/Acc/4m-per-s^2", + "triangle": "Def/MyColor/Redish" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def/Acc/4.5 m-per-s^2, Red)", + "ball": "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/baloney, (Def/Acc/4.5 m-per-s^2, Red)"], + [ 5.0, 0, "Def/Acc/3 m"], + [ 6.3, 0, "Def/Acc/4m-per-s^2"], + [ 7.2, 0, "Def/MyColor/Redish"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/baloney, (Def/Acc/4.5 m-per-s^2, Red)", + "ball": "Def/Acc/3 m", + "square": "Def/Acc/4m-per-s^2", + "triangle": "Def/MyColor/Redish" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "Def/Acc/baloney, (Def/Acc/4.5 m-per-s^2, Red)"], + [ 5.0, 0, "face", "Def/Acc/3 m"], + [ 6.3, 0, "n/a", "Def/Acc/4m-per-s^2"], + [ 7.2, 0, "square", "Def/MyColor/Redish"] + + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/Acc/4.5 m-per-s^2, Red)", + "ball": "Def/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/NODE_NAME_EMPTY.json b/docs/source/_static/data/error_tests/NODE_NAME_EMPTY.json new file mode 100644 index 00000000..79087803 --- /dev/null +++ b/docs/source/_static/data/error_tests/NODE_NAME_EMPTY.json @@ -0,0 +1,198 @@ +[ + { + "error_code": "NODE_NAME_EMPTY", + "name": "node-name-empty-forward-slashes", + "description": "A tag has one or more forward slashes (`/`) at beginning or end (ignoring whitespace).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "//Blue, Green", + "Def/Acc/4.5//", + "Def/Acc/4.5/", + "/ /Def/Acc/4.5 ms/" + ], + "passes": [ + "Label/Red, Informational-property/Label/Blue" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "//Blue, Green", + "ball": "Def/Acc/4.5//", + "square": "Def/Acc/4.5/", + "test": "/ /Def/Acc/4.5 ms/" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Informational-property/Label/Num1", + "ball": "Informational-property/Label/Num2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "//Blue, Green"], + [ 4.5, 0, "Def/Acc/4.5//"], + [ 4.5, 0, "Def/ /Acc/4.5 ms/"], + [ 7.2, 0, "/ /Def/Acc/4.5 ms/"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Informational-property/Label/Num1"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "//Blue, Green", + "ball": "Def/Acc/4.5//", + "square": "Def/Acc/4.5/", + "test": "/ /Def/Acc/4.5 ms/" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "//Blue, Green"], + [ 4.5, 0, "face", "Def/Acc/4.5//"], + [ 4.5, 0, "n/a", "Def/ /Acc/4.5 ms/"], + [ 7.2, 0, "n/a", "/ /Def/Acc/4.5 ms/"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Informational-property/Label/Num1", + "ball": "Informational-property/Label/Num2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "NODE_NAME_EMPTY", + "name": "node-name-empty-forward-consecutive", + "description": "A tag contains consecutive forward slashes (ignoring whitespace).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Informational-property/ /Label/Num1", + "Def/Acc//4.5" + ], + "passes": [ + "Informational-property/Label/Num1" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Informational-property/ /Label/Num1", + "ball": "Def/Acc//4.5" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Informational-property/Label/Num1", + "ball": "Def/Acc/4.5" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Informational-property/ /Label/Num1"], + [ 5.7, 0, "Def/Acc//4.5"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Informational-property/Label/Num1"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Informational-property/ /Label/Num1", + "ball": "Def/Acc//4.5 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7 m-per-s^2, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/ONSET_OFFSET_ERROR.json b/docs/source/_static/data/error_tests/ONSET_OFFSET_ERROR.json new file mode 100644 index 00000000..c90c180a --- /dev/null +++ b/docs/source/_static/data/error_tests/ONSET_OFFSET_ERROR.json @@ -0,0 +1,750 @@ +[ + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-not-tag-group", + "description": "An Onset or Offset tag does not appear in a tag group.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Onset, Red", + "Offset, Def/Acc/5.4 m-per-s^2" + ], + "passes": [ + "(Onset, Def/Acc/5.4 m-per-s^2)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Onset, Red", + "ball": "Offset, Def/Acc/5.4 m-per-s^2" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/Acc/5.4 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Onset, Red"], + [ 4.8, 0, "(Onset, MyColor)"], + [ 5.0, 0, "Offset, MyColor"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Onset, (Def-expand/MyColor, (Label/Pie)), (Red))"], + [ 5.5, 0, "(Onset, Def/Acc/5.4 m-per-s^2)"], + [ 6.3, 0, "(Offset, Def/Acc/5.4 m-per-s^2)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Onset, Red", + "ball": "Offset, Def/Acc/5.4 m-per-s^2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "Onset, Red"], + [ 4.8, 0, "n/a", "(Onset/MyColor)"], + [ 5.0, 0, "face", "Offset, MyColor"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/Acc/5.4 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 5.5, 0, "n/a","(Onset, Def/Acc/5.4 m-per-s^2)"], + [ 6.3, 0, "n/a","(Offset, Def/Acc/5.4 m-per-s^2)"], + [ 8.5, 0, "face", "Blue"], + [ 9.0, 0, "n/a", "Green, ((Def-expand/MyColor, (Label/Pie)), Onset)"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-nested-group", + "description": "An Onset or Offset tag appears in a nested tag group (not a top-level tag group).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "((Onset, Def/MyColor), Red)" + ], + "passes": [ + "(Onset, Def/MyColor), Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "((Onset, Def/MyColor), Red)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor), Red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "((Onset, Def/MyColor), Red)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Onset, Def/MyColor), Red"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "((Onset, Def/MyColor), Red)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "n/a", "((Onset, Def/MyColor), Red)"], + [ 5.0, 0, "face", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor), Red" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "n/a", "(Onset, Def/MyColor), Red"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-wrong-number-of-defs", + "description": "An Onset or Offset tag is not grouped with exactly one Def-expand tag group or a Def tag.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Onset, (Red))" + ], + "passes": [ + "(Onset, Def/MyColor, (Red))", + "(Onset, (Def-expand/MyColor, (Label/Pie)), (Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Onset, (Red))", + "ball": "(Onset, Def/MyColor, Def/Acc/4.3 m-per-s^2)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor, (Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Onset, (Red))"], + [ 5.5, 0, "(Onset, Def/MyColor, Def/Acc/4.3 m-per-s^2)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Onset, Def/MyColor, (Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, (Red))", + "ball": "(Onset, Def/MyColor, Def/Acc/4.3 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Green, Def/MyColor"], + [ 5.0, 0, "n/a", "(Onset, (Yellow))"], + [ 6.0, 0, "ball", "n/a"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor, (Red))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "n/a", "(Onset, Def/MyColor, (Blue))"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-error-onset-has-more-groups", + "description": "An Onset group has more than one additional tag group.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Onset, Def/MyColor, (Red), (Blue))", + "((Def-expand/MyColor, (Label/Pie)), (Green), (Red), Onset)" + ], + "passes": [ + "(Onset, Def/MyColor)", + "((Def-expand/MyColor, (Label/Pie)), (Red), Onset)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor, (Red), (Blue))", + "ball": "((Def-expand/MyColor, (Label/Pie)), (Green), (Yellow), Onset)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), (Green, (Yellow)), Onset)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Onset, Def/MyColor, (Red), (Blue))"], + [ 5.5, 0, "((Def-expand/MyColor, (Label/Pie)), (Green), ((Yellow)), Onset)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Onset, Def/MyColor)"], + [5.0, 0, "((Def-expand/MyColor, (Label/Pie)), (Green, (Yellow)), Onset)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "((Def-expand/MyColor, (Label/Pie)), (Green), ((Yellow)), Onset)", + "ball": "(Onset, Def/MyColor, (Red), (Blue))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"], + [ 6.0, 0, "n/a", "(Def/MyColor, (Red), (Blue), Onset)"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), (Green, (Yellow)), Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "((Def-expand/MyColor, (Label/Pie)), (Green, (Yellow)), Onset)"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-offset-has-groups", + "description": "An Offset appears with one or more tags or additional tag groups.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Offset, Def/MyColor, Red)", + "((Def-expand/MyColor, (Label/Pie)), Offset, (Red))" + ], + "passes": [ + "(Offset, Def/MyColor)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), Onset)", + "square": "(Offset, Def/MyColor, (Red))", + "circle": "((Def-expand/MyColor, (Label/Pie)), Offset, Blue)" + + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), Onset)", + "square": "(Offset, Def/MyColor)", + "circle": "((Def-expand/MyColor, (Label/Pie)), Offset)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Onset, Def/MyColor)"], + [ 4.8, 0, "(Offset, Def/MyColor, (Red))"], + [ 4.9, 0, "(Onset, Def/MyColor, (Red))"], + [ 5.5, 0, "((Def-expand/MyColor, (Label/Pie)), (Green), Offset)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Onset, Def/MyColor)"], + [ 4.8, 0, "(Offset, Def/MyColor)"], + [ 4.9, 0, "(Onset, Def/MyColor, (Red))"], + [ 5.5, 0, "((Def-expand/MyColor, (Label/Pie)), Offset)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), Onset)", + "square": "(Offset, Def/MyColor, (Red))", + "circle": "((Def-expand/MyColor, (Label/Pie)), Offset, Blue)" + + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "n/a"], + [ 4.8, 0, "square", "n/a"], + [ 4.9, 0, "ball", "Green"], + [ 5.5, 0, "((Def-expand/MyColor, (Label/Pie)), Offset, Blue)", "Orange"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Onset, Def/MyColor)", + "ball": "((Def-expand/MyColor, (Label/Pie)), Onset)", + "square": "(Offset, Def/MyColor)", + "circle": "((Def-expand/MyColor, (Label/Pie)), Offset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "n/a"], + [ 4.8, 0, "square", "n/a"], + [ 4.9, 0, "ball", "Green"], + [ 5.5, 0, "((Def-expand/MyColor, (Label/Pie)), Offset, Blue)", "Orange"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-mismatch", + "description": "An Offset tag associated with a given definition appears after a previous Offset tag without the appearance of an intervening Onset of the same name.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor, Offset)"], + [ 6.5, 0, "Red, (Def/MyColor, Offset)"], + [ 5.5, 0, "(Def/MyColor, Offset)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor, Onset)"], + [ 5.5, 0, "(Def/MyColor, Offset)"], + [ 6.5, 0, "Red"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, Onset)", + "ball": "(Def/MyColor, Offset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "ball", "Red, Blue"], + [ 4.8, 0, "ball", "Red, Blue"], + [ 5.0, 0, "face", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, Onset)", + "ball": "(Def/MyColor, Offset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-extra tags", + "description": "An Onset tag group with has tags besides the anchor Def or Def-expand that are not in a tag group.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def/MyColor, Blue, Green, Onset)" + ], + "passes": [ + "(Def/MyColor, (Blue), Onset)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def/MyColor, Blue, Green, Onset)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def/MyColor, (Blue), Onset)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor, Blue, (Green), Onset)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor, (Blue), Onset)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, Blue, Green, Onset)", + "ball": "Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "((Blue, Green), Def/MyColor, Onset)", + "ball": "(Def/Acc/7, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "ONSET_OFFSET_ERROR", + "name": "onset-offset-error-duplicated-onset-or-offset", + "description": "An Onset or an Offset with a given Def or Def-expand anchor appears in the same event marker with another Onset or Offset that uses the same anchor.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, (Green), Onset)", + "ball": "Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "(Def/MyColor, (Blue), Onset)"], + [ 5.0, 0, "ball", "Green"] + ] + }, + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, (Green), Onset)", + "ball": "(Def/MyColor, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "(Def/MyColor, Offset)"], + [ 5.0, 0, "ball", "(Def/MyColor, Offset)"] + ] + }, + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor, (Green), Onset)", + "ball": "(Def/MyColor, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "(Def/MyColor, Offset)"], + [ 5.0, 0, "ball", "(Def/MyColor, Offset)"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "((Blue, Green), Def/MyColor, Onset)", + "ball": "(Def/MyColor, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/PARENTHESES_MISMATCH.json b/docs/source/_static/data/error_tests/PARENTHESES_MISMATCH.json new file mode 100644 index 00000000..80a34653 --- /dev/null +++ b/docs/source/_static/data/error_tests/PARENTHESES_MISMATCH.json @@ -0,0 +1,191 @@ +[ + { + "error_code": "PARENTHESES_MISMATCH", + "name": "parentheses-mismatch-unmatched-parentheses", + "description": "A HED string does not have the same number of open and closed parentheses.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def/MyColor, (Blue, (Yellow)), Red))", + "((Red, ((Blue, Green), Yellow))", + "((Red, ((Blue), Green)), (Yellow)" + ], + "passes": [ + "(Def/Acc/5.3 m-per-s^2, (Red))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def/MyColor, (Blue, (Yellow)), Red))", + "ball": "(Red, ((Blue, Green), Yellow))", + "square": "(Red, ((Blue), Green)), (Yellow)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def/Acc/5.3 m-per-s^2, (Red))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor, (Blue, (Yellow)), Red))"], + [ 5.5, 0, "(Red, ((Blue, Green), Yellow))"], + [ 6.3, 0, "(Red, ((Blue), Green)), (Yellow)"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def/Acc/5.3 m-per-s^2, (Red))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "PARENTHESES_MISMATCH", + "name": "parentheses-mismatch-incorrect-nesting", + "description": "The open and closed parentheses are not correctly nested in the HED string.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def/MyColor)), (Blue, (Yellow)), (Red)", + ")(Def/MyColor)), (Blue, (Yellow)), (Red))" + ], + "passes": [ + "(Def/Acc/5.3 m-per-s^2, (Red))", + "(((((Def/Acc/5.3 m-per-s^2, (Red))))))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Def/MyColor)), (Blue, (Yellow)), (Red)", + "ball": ")(Def/MyColor)), (Blue, (Yellow)), (Red))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def/Acc/5.3 m-per-s^2, (Red))", + "ball": "(((((Def/Acc/5.3 m-per-s^2, (Red))))))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/MyColor)), (Blue, (Yellow)), (Red)"], + [ 5.5, 0, ")(Def/MyColor)), (Blue, (Yellow)), (Red))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Def/Acc/5.3 m-per-s^2, (Red))"], + [ 5.5, 0, "(((((Def/Acc/5.3 m-per-s^2, (Red))))))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/MyColor)), (Blue, (Yellow)), (Red)", + "ball": ")(Def/MyColor)), (Blue, (Yellow)), (Red))" } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "),Red, (((Def/MyColor)))"], + [ 5.0, 0, "ball", "(Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Def/Acc/5.3 m-per-s^2, (Red))", + "ball": "(((((Def/Acc/5.3 m-per-s^2, (Red))))))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, ((Def/MyColor))"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/PLACEHOLDER_INVALID.json b/docs/source/_static/data/error_tests/PLACEHOLDER_INVALID.json new file mode 100644 index 00000000..f3fb8697 --- /dev/null +++ b/docs/source/_static/data/error_tests/PLACEHOLDER_INVALID.json @@ -0,0 +1,325 @@ +[ + { + "error_code": "PLACEHOLDER_INVALID", + "name": "placeholder-invalid-misplaced", + "description": "A `#` appears in a place that it should not (such as in the `HED` column of an event file outside a definition).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Label/#", + "Def/Acc/# m-per-s^2" + ], + "passes": [ + "Label/This-label" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Label/#", + "ball": "Def/Acc/# m-per-s^2" + } + } + } + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Label/#"], + [ 5.0, 0, "Def/Acc/# m-per-s^2"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Label/This-label"], + [ 6.0, 0, "(Def/Acc/3.5 m-per-s^2)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/Acc/#"], + [ 5.0, 0, "ball", "Label/#"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "PLACEHOLDER_INVALID", + "name": "placeholder-invalid-#-in-categorical-column", + "description": "A JSON sidecar has a placeholder (`#`) in the HED dictionary for a categorical column.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Label/#", + "ball": "Def/Acc/# m-per-s^2" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Label/This-label", + "ball": "(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Label/#", + "ball": "Def/Acc/#" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "PLACEHOLDER_INVALID", + "name": "placeholder-invalid-json-value-column", + "description": "A JSON sidecar does not have exactly one placeholder (`#`) in each HED string representing a value column.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "trial": { + "HED": "Def/Acc/# m-per-s^2, Label #" + }, + "memory": { + "HED": "Blue, Red" + } + } + ], + "passes": [ + { + "trial": { + "HED": "Def/Acc/# m-per-s^2" + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "trial": { + "HED": "Def/Acc/#, Label #" + }, + "memory": { + "HED": "Blue, Red" + } + }, + "events": + [ + ["onset", "duration", "trial", "memory", "HED"], + [ 4.5, 0, "3", "4","Red, Def/MyColor"], + [ 5.0, 0, "2","6", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "trial": { + "HED": "Def/Acc/#, Label/Trial" + }, + "memory": { + "HED": "Blue, Red, Label/#" + } + }, + "events": + [ + ["onset", "duration", "trial", "memory", "HED"], + [ 4.5, 0, "5", "4", "Green"], + [ 5.0, 0, "3", "2","Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "PLACEHOLDER_INVALID", + "name": "placeholder-invalid-json-#-misplaced", + "description": "A placeholder (`#`) is used in JSON sidecar or definition, but its parent in the schema does not have a placeholder child.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "trial": { + "HED": "Sensory-event/#" + }, + "defs": { + "def1": "(Definition/Blech/#, (Red, Blue/#))" + } + } + ], + "passes": [ + { + "trial": { + "HED": "Label/#" + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "trial": { + "HED": "Sensory-event/#" + }, + "defs": { + "def1": "(Definition/Blech/#, (Red, Blue/#))" + } + }, + "events": + [ + ["onset", "duration", "trial","HED"], + [ 4.5, 0, "3", "Red, Def/MyColor"], + [ 5.0, 0, "2", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "trial": { + "HED": "Sensory-event, Label/#" + }, + "defs": { + "def1": "(Definition/Blech/#, (Red, Label/#))" + } + }, + "events": + [ + ["onset", "duration", "trial","HED"], + [ 4.5, 0, "3", "Blue"], + [ 5.0, 0, "2", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/REQUIRED_TAG_ERROR.json b/docs/source/_static/data/error_tests/REQUIRED_TAG_ERROR.json new file mode 100644 index 00000000..c4c6bbba --- /dev/null +++ b/docs/source/_static/data/error_tests/REQUIRED_TAG_ERROR.json @@ -0,0 +1,62 @@ +[ + { + "error_code": "REQUIRED_TAG_ERROR", + "name": "required-tag-missing", + "description": "An event-level annotation does not have a tag corresponding to a node with the `required` schema attribute. (Note this is deprecated so no tests.)", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + } + } + }, + { + "error_code": "REQUIRED_TAG_ERROR", + "name": "required-tag-in-definition", + "description": "A required tag appears in a definition", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + } + }, + "combo_tests": { + "fails": [ + ], + "passes": [ + ] + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/SIDECAR_INVALID.json b/docs/source/_static/data/error_tests/SIDECAR_INVALID.json new file mode 100644 index 00000000..003c1d80 --- /dev/null +++ b/docs/source/_static/data/error_tests/SIDECAR_INVALID.json @@ -0,0 +1,186 @@ +[ + { + "error_code": "SIDECAR_INVALID", + "name": "sidecar-invalid-key-at-wrong-level", + "description": "The HED key is not a second-level dictionary key.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "temp": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + } + }, + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "temp": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + }, + { + "sidecar": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + }, + "events": + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, Def/MyColor"], + [ 5.0, 0, "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "SIDECAR_INVALID", + "name": "sidecar-invalid-na-annotated", + "description": "An annotation entry is provided for `n/a`.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue),(Green, (Yellow))", + "n/a": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red, Blue),(Green, (Yellow))", + "n/a": "(Def/MyColor, Onset), (Def/Acc/3.5 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "n/a", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/SIDECAR_KEY_MISSING.json b/docs/source/_static/data/error_tests/SIDECAR_KEY_MISSING.json new file mode 100644 index 00000000..eabc0caa --- /dev/null +++ b/docs/source/_static/data/error_tests/SIDECAR_KEY_MISSING.json @@ -0,0 +1,68 @@ +[ + { + "error_code": "SIDECAR_KEY_MISSING", + "name": "sidecar-key-missing", + "description": "A value in a categorical column does not have an expected entry in a sidecar.", + "warning": true, + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "square", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7 m-per-s^2, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/STYLE_WARNING.json b/docs/source/_static/data/error_tests/STYLE_WARNING.json new file mode 100644 index 00000000..e1cb5fd0 --- /dev/null +++ b/docs/source/_static/data/error_tests/STYLE_WARNING.json @@ -0,0 +1,96 @@ +[ + { + "error_code": "STYLE_WARNING", + "name": "style-warning-bad-naming-style", + "description": "An extension or label does not follow HED naming conventions.", + "warning": true, + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red/red_blech" + ], + "passes": [ + "Blue/Blueish" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red/red_blech", + "ball": "Blue/blueish" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red/Red-blech", + "ball": "Blue/Blueish" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red/red_blech"], + [ 5.0, 0, "Blue/blueish"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red/Red-blech"], + [ 5.0, 0, "Blue/Blueish"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red/red_blech", + "ball": "Blue/blueish" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red/Red-blech", + "ball": "Blue/Blueish" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_EMPTY.json b/docs/source/_static/data/error_tests/TAG_EMPTY.json new file mode 100644 index 00000000..447a6dfd --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_EMPTY.json @@ -0,0 +1,296 @@ +[ + { + "error_code": "TAG_EMPTY", + "name": "tag-empty-extra-commas-or-parentheses", + "description": "A HED string has extra commas or parentheses separated by only white space.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red, , , Green", + "(, Red, Green), Blue", + "(Red, , Green), Blue", + "(Red, Green,), Blue", + "(Red, Green), Blue," + ], + "passes": [ + "(Red, Blue), Green" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "square": "Red, , , Green", + "test": "(, Red, Green), Blue", + "pine": "(Red, , Green), Blue", + "apple": "(Red, Green,), Blue" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red, Blue", + "ball": "Def/Acc/4.5 m-per-s^2, Def/Acc/3.2 m-per-s^2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 5.5, 0, "Red, , , Green"], + [ 7.5, 0, "(, Red, Green), Blue"], + [ 8.2, 0, "(Red, , Green), Blue"], + [ 9.1, 0, "(Red, Green,), Blue"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Red, (Blue, Green)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "square": "Red, , , Green", + "test": "(, Red, Green), Blue", + "pine": "(Red, , Green), Blue", + "apple": "(Red, Green,), Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "test", "Red, Def/MyColor"], + [ 5.0, 0, "apple", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red, Green", + "ball": "Def/Acc/4.5 m-per-s^2, Def/Acc/3.2" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_EMPTY", + "name": "tag-empty-begin-end-comma", + "description": "A HED string begins or ends with a comma (ignoring white space).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ", Blue,Def/Acc/3.2 m-per-s^2", + "(Blue, Green),Yellow,", + ",,(Blue, Green),Yellow," + ], + "passes": [ + "(Red, Blue), Green" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": ", Blue,Def/Acc/3.2 m-per-s^2", + "ball": "(Blue, Green),Yellow,", + "square": ",,(Blue, Green),Yellow," + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red, Blue", + "ball": "Def/Acc/4.5 m-per-s^2, Def/Acc/3.2 m-per-s^2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, ", (Blue, Green),Yellow,"], + [ 5.5, 0, ",,(Blue, Green),Yellow,"], + [ 6.5, 0, ", Blue,Def/Acc/3.2 m-per-s^2"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Red, (Blue, Green)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": ", Blue,Def/Acc/3.2", + "ball": "(Blue, Green),Yellow,", + "square": ",,(Blue, Green),Yellow," + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_EMPTY", + "name": "tag-empty-empty-parentheses", + "description": "A tag group is empty (i.e., empty parentheses are not allowed).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Red, (), (Blue), ((Green)))", + "((( ))), Red" + ], + "passes": [ + "(Red, ( Blue ), ((Green)))", + "(((Def/Acc/3.5 m-per-s^2)))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Red, (), (Blue), ((Green)))", + "ball": "((( ))), Red" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, ( Blue ), ((Green)))", + "ball": "(((Def/Acc/3.5 m-per-s^2)))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Red, (), (Blue), ((Green)))"], + [ 5.5, 0, "((( ))), Red"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Red, ( Blue ), ((Green)))"], + [ 5.5, 0, "(((Def/Acc/3.5 m-per-s^2)))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red, (), (Blue), ((Green)))", + "ball": "((( ))), Red" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red, ( Blue ), ((Green)))", + "ball": "(((Def/Acc/3.5 m-per-s^2)))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_EXPRESSION_REPEATED.json b/docs/source/_static/data/error_tests/TAG_EXPRESSION_REPEATED.json new file mode 100644 index 00000000..fe08362a --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_EXPRESSION_REPEATED.json @@ -0,0 +1,101 @@ +[ + { + "error_code": "TAG_EXPRESSION_REPEATED", + "name": "tag-expression-repeated-same-level", + "description": "A tag is repeated in the same tag group or level.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red, (Blue), Red, Green", + "(Red, Blue, (Green)), (Red, Blue, (Green))", + "Red, (((Blue, Green, (Yellow)), Red, (Blue, Green, (Yellow)))" + ], + "passes": [ + "Red, (Blue, Red)", + "(Red, Blue, (Green)), (Red, Blue, ((Green)))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red, (Blue), Red, Green", + "ball": "(Red, Blue, (Green)), (Red, Blue, (Green))", + "square": "Red, (((Blue, Green, (Yellow)), Red, (Blue, Green, (Yellow)))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red, (Blue, Red)", + "ball": "(Red, Blue, (Green)), (Red, Blue, ((Green)))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, (Blue), Red, Green"], + [ 5.5, 0, "(Red, Blue, (Green)), (Red, Blue, (Green))"], + [ 6.5, 0, "Red, (((Blue, Green, (Yellow)), Red, (Blue, Green, (Yellow)))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, (Blue, Red)"], + [ 5.5, 0, "(Red, Blue, (Green)), (Red, Blue, ((Green)))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red, (Blue), Red, Green", + "ball": "(Red, Blue, (Green)), (Red, Blue, (Green))", + "square": "Red, (((Blue, Green, (Yellow)), Red, (Blue, Green, (Yellow)))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red, (Blue, Red)", + "ball": "(Red, Blue, (Green)), (Red, Blue, ((Green)))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_EXTENDED.json b/docs/source/_static/data/error_tests/TAG_EXTENDED.json new file mode 100644 index 00000000..63479cc3 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_EXTENDED.json @@ -0,0 +1,103 @@ +[ + { + "error_code": "TAG_EXTENDED", + "name": "tag-extended-extension", + "description": "A tag represents an extension from the schema.", + "warning": true, + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Red-color/Red/Big-red, Blue/Nice-blue),(Green, (Yellow))", + "Sensory-presentation/Visual-presentation/Nice-yellow", + "Red-color/Red/Redish", + "Red-color/Red/Redish/More-redish", + "((Green/Greenish))", + "Red/1red", + "Red/Red--2red" + ], + "passes": [ + "Red-color/Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Red-color/Red/Big-red, Blue/Nice-blue),(Green, (Yellow))", + "ball": "Sensory-presentation/Visual-presentation/Nice-yellow", + "square": "((Green/Greenish))", + "triangle": "Red/1red", + "catwalk": "Red/Red--2red" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red-color/Red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Red-color/Red/Big-red, Blue/Nice-blue),(Green, (Yellow))"], + [ 5.5, 0, "Sensory-presentation/Visual-presentation/Nice-yellow"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Red-color/Red"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Red-color/Red/Big-red/Bigger-red, Blue/Nice-blue),(Green, (Yellow))", + "ball": "Sensory-presentation/Visual-presentation/Nice-yellow" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7 m-per-s^2, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_EXTENSION_INVALID.json b/docs/source/_static/data/error_tests/TAG_EXTENSION_INVALID.json new file mode 100644 index 00000000..328d6037 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_EXTENSION_INVALID.json @@ -0,0 +1,199 @@ +[ + { + "error_code": "TAG_EXTENSION_INVALID", + "name": "tag-extension-invalid-duplicate", + "description": "A tag extension term is already in the schema.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red-color/Red/DarkRed, Sensory-presentation/Red", + "Sensory-presentation/Red/Redish" + ], + "passes": [ + "Red-color/Red/Redish", + "((Green/Greenish))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red-color/Red/DarkRed, Sensory-presentation/Red", + "ball": "Sensory-presentation/Red/Redish" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red-color/Red/Redish", + "ball": "((Green/Greenish))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red-color/Red/DarkRed, Sensory-presentation/Red"], + [ 5.5, 0, "Sensory-presentation/Red/Redish"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Red-color/Red"], + [ 5.5, 0, "((Green))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red-color/Red/DarkRed, Sensory-presentation/Red", + "ball": "Sensory-presentation/Red/Redish" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red-color/Red", + "ball": "Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_EXTENSION_INVALID", + "name": "tag-extension-invalid-bad-node-name", + "description": "A tag extension term does not comply with rules for schema nodes.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red/Red$2", + "Red/R#d" + ], + "passes": [ + "Red-color/Red", + "((Green))", + "Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red/Red$2", + "ball": "Red/R#d" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Red-color/Red/Redish", + "ball": "Red-color/Red/Redish/More-redish", + "square": "((Green/Greenish))", + "triangle": "Red/1red", + "catwalk": "Red/Red--2red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red/Red$2"], + [ 5.5, 0, "Red/R#d"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Red-color/Red/Redish"], + [ 5.5, 0, "Red-color/Red/Redish/More-redish"], + [ 6.5, 0, "((Green/Greenish))"], + [ 7.5, 0, "Red/1red"], + [ 8.2, 0, "Red/Red--2red"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red/Red$2", + "ball": "Red/R#d" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red/Redish-like", + "ball": "Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_GROUP_ERROR.json b/docs/source/_static/data/error_tests/TAG_GROUP_ERROR.json new file mode 100644 index 00000000..91275722 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_GROUP_ERROR.json @@ -0,0 +1,250 @@ +[ + { + "error_code": "TAG_GROUP_ERROR", + "name": "tag-group-error-missing", + "description": "A tag has tagGroup or topLevelTagGroup attribute, but is not enclosed in parentheses.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Definition, (Red)", + "Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)", + "Onset" + ], + "passes": [ + "(Definition/Blech, (Red))", + "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "((Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset)" + ] + }, + "sidecar_tests":{ + "fails": [ + { + "event_code": { + "HED": { + "face": "Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))", + "ball": "((Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)"], + [ 5.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red))"], + [ 5.5, 0, "((Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset)"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)", + "ball": "(Def-expand/Acc/4.5 m-per-s^2, (Acceleration/4.5 m-per-s^2, Red)), Onset" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_GROUP_ERROR", + "name": "tag-group-error-not-top-level", + "description": "A tag with the topLevelTagGroup does not appear at a HED tag group at the top level in an assembled HED annotation.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "((Def/Acc/3.0 m-per-s^2, Onset))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "(Def/Acc/3.0 m-per-s^2, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_GROUP_ERROR", + "name": "multiple-top-level-tags-in-same-group", + "description": "Multiple tags with the topLevelTagGroup attribute appear in the same top-level tag group. (Delay and Duration are allowed to be in the same topLevelTagGroup).", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Def/MyColor, Onset, Event-context)", + "(Event-context, Red, Offset)" + ], + "passes": [ + "(Def/MyColor, Onset)" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "(Def/Acc/3.0 m-per-s^2, Onset, Event-context)" + } + } + } + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, (Event-context, Def/MyColor, Onset)"], + [ 5.0, 0, "Green"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red, (Event-context, Def/MyColor)"], + [ 5.0, 0, "Green"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "(Def/Acc/3.0 m-per-s^2, Onset, Event-context)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, (Def/MyColor, Event-context, Event-context)"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "(Def/Acc/3.0 m-per-s^2, Onset)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue, (Event-context, Label/Red)"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_INVALID.json b/docs/source/_static/data/error_tests/TAG_INVALID.json new file mode 100644 index 00000000..3e609cb9 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_INVALID.json @@ -0,0 +1,98 @@ +[ + { + "error_code": "TAG_INVALID", + "name": "tag-invalid-in-schema", + "description": "The tag is not valid in the schema it is associated with.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Brown-color/Red", + "Property/Sensory-event", + "Sensory-event/Baloney" + ], + "passes": [ + "Brown-color/Brown" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Brown-color/Red", + "ball": "Property/Sensory-event", + "square": "Sensory-event/Baloney" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Brown-color/Brown" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Brown-color/Red"], + [ 5.5, 0, "Property/Sensory-event"], + [ 5.5, 0, "Sensory-event/Baloney"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Brown-color/Brown"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Brown-color/Red", + "ball": "Property/Sensory-event", + "square": "Sensory-event/Baloney" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue/Apples" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_NOT_UNIQUE.json b/docs/source/_static/data/error_tests/TAG_NOT_UNIQUE.json new file mode 100644 index 00000000..0088e7a6 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_NOT_UNIQUE.json @@ -0,0 +1,90 @@ +[ + { + "error_code": "TAG_NOT_UNIQUE", + "name": "tag-not-unique", + "description": "A tag with unique attribute appears more than once in an event-level HED string.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Event-context, (Red, Blue)), (Event-context, (Green, Yellow))" + ], + "passes": [ + "(Event-context, (Red, Blue))" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Event-context, (Red, Blue)), (Event-context, (Green, Yellow))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Event-context, (Red, Blue))" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Event-context, (Red, Blue)), (Event-context, (Green, Yellow))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Event-context, (Red, Blue))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Event-context, (Red, Blue)), (Event-context, (Green, Yellow))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Event-context, (Red, Blue))", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "(Event-context, (Red, Blue))"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_PREFIX_INVALID.json b/docs/source/_static/data/error_tests/TAG_PREFIX_INVALID.json new file mode 100644 index 00000000..2e8ca8c2 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_PREFIX_INVALID.json @@ -0,0 +1,187 @@ +[ + { + "error_code": "TAG_PREFIX_INVALID", + "name": "tag-prefix-invalid-no-schema", + "description": "A tag starting with name: does not have an associated schema.", + "schema": ["8.1.0", "sc:score_1.0.0"], + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "ts:Red, Blue", + "(ts:Red, (sc:Sleep-modulator))" + ], + "passes": [ + "sc:Sleep-modulator" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "ts:Red, Blue", + "ball": "(ts:Red, (sc:Sleep-modulator))" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "sc:Sleep-modulator" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "ts:Red, Blue"], + [ 5.5, 0, "(ts:Red, (sc:Sleep-modulator))"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "sc:Sleep-modulator"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "ts:Red, Blue", + "ball": "(ts:Red, (sc:Sleep-modulator))" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue, sc:Sleep-modulator" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue, sc:Sleep-modulator"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "TAG_PREFIX_INVALID", + "name": "tag-prefix-invalid-characters", + "description": "A tag prefix has invalid characters.", + "schema": ["8.1.0", "sc:score_1.0.0"], + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "sc2:Sleep-modulator, Red", + "sca:Sleep-modulator, Red" + ], + "passes": [ + "Blue", + "sc:Sleep-modulator, Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "sc1:Sleep-modulator, Red", + "ball": "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "sc1:Sleep-modulator, Red"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Red, Blue), (Green, (Yellow))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "sc1:Sleep-modulator, Red", + "ball": "(Def/MyColor, Onset)(Def/Acc/3.5 m-per-s^2)" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2, sc:Sleep-modulator", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TAG_REQUIRES_CHILD.json b/docs/source/_static/data/error_tests/TAG_REQUIRES_CHILD.json new file mode 100644 index 00000000..aef960f9 --- /dev/null +++ b/docs/source/_static/data/error_tests/TAG_REQUIRES_CHILD.json @@ -0,0 +1,97 @@ +[ + { + "error_code": "TAG_REQUIRES_CHILD", + "name": "tag-requires-child-no-child", + "description": "A tag has the requireChild schema attribute but does not have a child.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "(Blue, Description)", + "Label, Red" + ], + "passes": [ + "(Blue, Description/Yes this is a description., (Red))", + "Label/Redish, Red" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "(Blue, Description)", + "ball": "Label, Red" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Blue, Description/Yes this is a description., (Red))", + "ball": "Label/Redish, Red" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Blue, Description)"], + [ 5.0, 0, "Label, Red"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "(Blue, Description/Yes this is a description., (Red))"], + [ 5.0, 0, "Label/Redish, Red"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "(Blue, Description)", + "ball": "Label, Red" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Label/Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/TILDES_UNSUPPORTED.json b/docs/source/_static/data/error_tests/TILDES_UNSUPPORTED.json new file mode 100644 index 00000000..8b8939f7 --- /dev/null +++ b/docs/source/_static/data/error_tests/TILDES_UNSUPPORTED.json @@ -0,0 +1,95 @@ +[ + { + "error_code": "TILDES_UNSUPPORTED", + "name": "tildes-unsupported", + "description": "The tilde syntax is no longer supported for any version of HED.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Red ~ Blue", + "Red, Blue ~ Green ~ Yellow" + ], + "passes": [ + "Red, Blue" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Red ~ Blue", + "ball": "Red, Blue ~ Green ~ Yellow" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "(Red, Blue), (Green, (Yellow))", + "ball": "(Def/MyColor, Onset),(Def/Acc/3.5 m-per-s^2)" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Red ~ Blue"], + [ 5.0, 0, "Red, Blue ~ Green ~ Yellow"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "(Red, Blue), (Green, (Yellow))"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Red ~ Blue", + "ball": "Red, Blue ~ Green ~ Yellow" + } + } + }, + "events": + [ + ["onset", "duration", "event_code", "HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Blue ~ Green ~ Yellow"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/UNITS_INVALID.json b/docs/source/_static/data/error_tests/UNITS_INVALID.json new file mode 100644 index 00000000..7f41e075 --- /dev/null +++ b/docs/source/_static/data/error_tests/UNITS_INVALID.json @@ -0,0 +1,188 @@ +[ + { + "error_code": "UNITS_INVALID", + "name": "units-invalid-for-unit-class", + "description": "A tag has a value with units that are invalid or not of the correct unit class for the tag.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc/3 s", + "Data-maximum/3 ms" + ], + "passes": [ + "Distance/4 km" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/3 s", + "ball": "Data-maximum/3 ms" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Distance/4 km", + "ball": "Angle/4 degrees" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/3 s"], + [ 5.5, 0, "Data-maximum/3 ms"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Distance/4 km"], + [ 5.0, 0, "Angle/4 degrees"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/3 s", + "ball": "Data-maximum/3 ms" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "UNITS_INVALID", + "name": "units-invalid-si-units", + "description": "A unit modifier is applied to units that are not SI units.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Distance/3 kfeet", + "Distance/3 kmeters" + ], + "passes": [ + "Distance/3 kilometres" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Distance/3 kfeet", + "ball": "Distance/3 kmeters" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Distance/3 kilometres" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Distance/3 kfeet"], + [ 5.0, 0, "Distance/3 kmeters"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Distance/3 kilometres"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Distance/3 kfeet", + "ball": "Distance/3 kmeters" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/UNITS_MISSING.json b/docs/source/_static/data/error_tests/UNITS_MISSING.json new file mode 100644 index 00000000..6be7f418 --- /dev/null +++ b/docs/source/_static/data/error_tests/UNITS_MISSING.json @@ -0,0 +1,97 @@ +[ + { + "error_code": "UNITS_MISSING", + "name": "units-missing-on-node-with-unit-class", + "description": "A tag that takes value and has a unit class does not have units.", + "warning": true, + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc/3", + "Acceleration/4.5" + ], + "passes": [ + "Distance/4 km" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/3", + "ball": "Acceleration/4.5" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Distance/4 km", + "ball": "Angle/4 degrees" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/3"], + [ 5.5, 0, "Acceleration/4.5"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Distance/4 km"], + [ 5.0, 0, "Angle/4 degrees"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/3", + "ball": "Acceleration/4.5" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7 m-per-s^2, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/VALUE_INVALID.json b/docs/source/_static/data/error_tests/VALUE_INVALID.json new file mode 100644 index 00000000..01b94bf8 --- /dev/null +++ b/docs/source/_static/data/error_tests/VALUE_INVALID.json @@ -0,0 +1,363 @@ +[ + { + "error_code": "VALUE_INVALID", + "name": "value-invalid-#-substitution", + "description": "The value substituted for a placeholder (`#`) is not valid.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc/MyMy", + "Distance/4mxxx" + ], + "passes": [ + "Def/Acc/3.4 m-per-s^2", + "Distance/4 m" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/MyMy", + "ball": "Distance/4mxxx" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/3.4 m-per-s^2", + "ball": "Distance/4 m" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/MyMy"], + [ 5.0, 0, "Distance/4mxxx"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/3.4 m-per-s^2"], + [ 5.0, 0, "Distance/4 m"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Def/Acc/MyMy", + "ball": "Distance/4mxxx" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "VALUE_INVALID", + "name": "value-invalid-incompatible-value-class", + "description": "A tag value is incompatible with the specified value class.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Statistical-accuracy/1max1" + ], + "passes": [ + "Statistical-accuracy/0.677" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Statistical-accuracy/1max1" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Statistical-accuracy/0.677" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Statistical-accuracy/1max1"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Statistical-accuracy/0.677"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Statistical-accuracy/1max1" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "VALUE_INVALID", + "name": "value-invalid-value-class-missing", + "description": "A tag value with no value class is assumed to be a text and contains invalid characters.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Collection/[x]" + ], + "passes": [ + "Collection/This-collection" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Collection/[x]" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Collection/This-collection" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [4.5, 0, "Collection/[x]"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Collection/This-collection"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + }, + { + "error_code": "VALUE_INVALID", + "name": "value-invalid-blank-missing", + "description": "The units are not separated from the value by a single blank.", + "schema": "8.1.0", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + "Def/Acc/5m-per-s^2" + ], + "passes": [ + "Def/Acc/5 m-per-s^2" + ] + }, + "sidecar_tests": { + "fails": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/5m-per-s^2" + } + } + } + ], + "passes": [ + { + "event_code": { + "HED": { + "face": "Def/Acc/5 m-per-s^2" + } + } + } + ] + }, + "event_tests": { + "fails": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/5m-per-s^2"] + ] + ], + "passes": [ + [ + ["onset", "duration", "HED"], + [ 4.5, 0, "Def/Acc/5 m-per-s^2"] + ] + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/data/error_tests/VERSION_DEPRECATED.json b/docs/source/_static/data/error_tests/VERSION_DEPRECATED.json new file mode 100644 index 00000000..4b147e00 --- /dev/null +++ b/docs/source/_static/data/error_tests/VERSION_DEPRECATED.json @@ -0,0 +1,68 @@ +[ + { + "error_code": "VERSION_DEPRECATED", + "name": "version-deprecated", + "warning": true, + "description": "The HED schema version being used as been deprecated.", + "schema": "8.0.0-beta.1", + "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], + "tests": { + "string_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "sidecar_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "event_tests": { + "fails": [ + ], + "passes": [ + ] + }, + "combo_tests": { + "fails": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/banana", + "ball": "Def/Acc/apple3, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Red, Def/MyColor"], + [ 5.0, 0, "ball", "Green"] + ] + } + ], + "passes": [ + { + "sidecar": { + "event_code": { + "HED": { + "face": "Acceleration/5 m-per-s^2", + "ball": "Def/Acc/7, Blue" + } + } + }, + "events": + [ + ["onset", "duration", "event_code","HED"], + [ 4.5, 0, "face", "Blue"], + [ 5.0, 0, "ball", "Green, Def/MyColor"] + ] + } + ] + } + } + } +] \ No newline at end of file diff --git a/docs/source/_static/images/croppedWideLogo.png b/docs/source/_static/images/croppedWideLogo.png new file mode 100644 index 00000000..2f011f9c Binary files /dev/null and b/docs/source/_static/images/croppedWideLogo.png differ diff --git a/docs/source/_template/layout.html b/docs/source/_template/layout.html index 275d9d76..11b418ae 100644 --- a/docs/source/_template/layout.html +++ b/docs/source/_template/layout.html @@ -2,19 +2,18 @@ {% block menu %} {{ super() }} -

- HED resources: +

+ Other HED resources:

- {% endblock %} + {% endblock %} \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py index 5abda221..f2eaa6dd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,8 +25,8 @@ author = 'HED Working Group' # The full version, including alpha/beta/rc tags -release = '3.0.0' -version = '3.0.0' +release = '3.1.0' +version = '3.1.0' currentdir = os.path.abspath(os.path.dirname(__file__)) @@ -45,15 +45,14 @@ "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinx.ext.githubpages", - "sphinx.ext.napoleon", - "sphinx.ext.extlinks" + "sphinx.ext.napoleon" ] autosummary_generate = True autodoc_default_flags = ['members', 'inherited-members'] add_module_names = False myst_all_links_external = False -myst_heading_anchors = 2 +myst_heading_anchors = 5 myst_enable_extensions = ["deflist"] # Add any paths that contain templates here, relative to this directory. @@ -86,7 +85,7 @@ # Toc options 'collapse_navigation': True, 'sticky_navigation': True, - 'navigation_depth': 4, + 'navigation_depth': 5, 'includehidden': True, 'titles_only': False } diff --git a/docs/source/index.rst b/docs/source/index.rst index 3330f94c..a34326f6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,17 +1,37 @@ HED specification ================== +.. image:: _static/images/croppedWideLogo.png + :width: 220 + :alt: HedLogo + .. sidebar:: **Links** - * `PDF released version (V3.0.0) `_ + * `PDF released version (V3.1.0) `_ * `PDF working version `_ * `Specification source `_ - * `HED resources `_ + * `Stable specification source `_ + + * `HED resources `_ + + * `HED project homepage `_ + +| +| +| + +The HED specification document formalizes the syntax and behavior of +HED (Hierarchical Event Descriptors) vocabulary, annotations, and supporting tools. The specification supports three versions of the specification: + +- `develop `_ - development branch which is under discussion. +- `latest `_ - includes revisions approved by the HED Working Group but not released. +- `stable `_ - the latest released form. - * `HED project homepage `_ +For more information about HED see `The HED project homepage `_ and +the `HED resources page `_. .. toctree:: :maxdepth: 4 @@ -19,11 +39,11 @@ HED specification 01_Introduction.md 02_Terminology.md - 03_Schema.md + 03_HED_formats.md 04_Basic_annotation.md 05_Advanced_annotation.md - 06_Infrastructure.md - 07_Library_schema.md + 06_Infrastructure_and_tools.md + 07_Library_schemas.md Appendix_A.md Appendix_B.md diff --git a/hedspec/HEDSpecification_3_1_0.pdf b/hedspec/HEDSpecification_3_1_0.pdf new file mode 100644 index 00000000..fd55a7e3 Binary files /dev/null and b/hedspec/HEDSpecification_3_1_0.pdf differ diff --git a/prerelease/CHANGES.md b/prerelease/CHANGES.md deleted file mode 100644 index ae1e2f23..00000000 --- a/prerelease/CHANGES.md +++ /dev/null @@ -1,12 +0,0 @@ -## Changes proposed for 8.2.0 - -* Added `Property/Agent-property/Agent-trait/Race` and `Property/Agent-property/Agent-trait/Ethnicity`. -Did not specify any children or the takesValue child. Expect users are going to extend or use a `Label` until -a BIDS or another standard specifies details. -* Added `Relation/Logical-relation`, `Relation/Logical-relation/And`, and `Relation/Logical-relation/Or`. -* Updated the descriptions of the major `Relation` subgroups to include idea of focus. -* Added `Relation/Spatial-relation/Left-center-of` and `Relation/Spatial-relation/Right-center-of` -and updated the `relatedTags` of other spatial relationship tags. -* Added a `deprecated` schema attribute to indicate that this tag should no longer be used. - This boolean attribute was added to provide a schema evolution path without removing any tags. -* Corrected missing open parenthesis in description for `Relation/Connective-relation/Performed-using`. \ No newline at end of file diff --git a/prerelease/HED8.2.0.mediawiki b/prerelease/HED8.2.0.mediawiki deleted file mode 100644 index e3a1ede9..00000000 --- a/prerelease/HED8.2.0.mediawiki +++ /dev/null @@ -1,1295 +0,0 @@ -HED version="8.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://github.com/hed-standard/hed-specification/raw/master/hedxml/HED8.0.0.xsd" - -'''Prologue''' -This schema includes an xsd and requires unit class, unit modifier, value class, schema attribute and property sections. - -!# start schema - -'''Event''' {suggestedTag=Task-property}[Something that happens at a given time and (typically) place. Elements of this tag subtree designate the general category in which an event falls.] -* Sensory-event {suggestedTag=Task-event-role, suggestedTag=Sensory-presentation}[Something perceivable by the participant. An event meant to be an experimental stimulus should include the tag Task-property/Task-event-role/Experimental-stimulus.] -* Agent-action {suggestedTag=Task-event-role, suggestedTag=Agent}[Any action engaged in by an agent (see the Agent subtree for agent categories). A participant response to an experiment stimulus should include the tag Agent-property/Agent-task-role/Experiment-participant.] -* Data-feature {suggestedTag=Data-property}[An event marking the occurrence of a data feature such as an interictal spike or alpha burst that is often added post hoc to the data record.] -* Experiment-control [An event pertaining to the physical control of the experiment during its operation.] -* Experiment-procedure [An event indicating an experimental procedure, as in performing a saliva swab during the experiment or administering a survey.] -* Experiment-structure [An event specifying a change-point of the structure of experiment. This event is typically used to indicate a change in experimental conditions or tasks.] -* Measurement-event {suggestedTag=Data-property}[A discrete measure returned by an instrument.] - -'''Agent''' {suggestedTag=Agent-property}[Someone or something that takes an active role or produces a specified effect.The role or effect may be implicit. Being alive or performing an activity such as a computation may qualify something to be an agent. An agent may also be something that simulates something else.] -* Animal-agent [An agent that is an animal.] -* Avatar-agent [An agent associated with an icon or avatar representing another agent.] -* Controller-agent [An agent experiment control software or hardware.] -* Human-agent [A person who takes an active role or produces a specified effect.] -* Robotic-agent [An agent mechanical device capable of performing a variety of often complex tasks on command or by being programmed in advance.] -* Software-agent [An agent computer program.] - -'''Action''' {extensionAllowed}[Do something.] -* Communicate [Convey knowledge of or information about something.] -** Communicate-gesturally {relatedTag=Move-face, relatedTag=Move-upper-extremity}[Communicate nonverbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body.] -*** Clap-hands [Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval.] -*** Clear-throat {relatedTag=Move-face, relatedTag=Move-head}[Cough slightly so as to speak more clearly, attract attention, or to express hesitancy before saying something awkward.] -*** Frown {relatedTag=Move-face}[Express disapproval, displeasure, or concentration, typically by turning down the corners of the mouth.] -*** Grimace {relatedTag=Move-face}[Make a twisted expression, typically expressing disgust, pain, or wry amusement.] -*** Nod-head {relatedTag=Move-head}[Tilt head in alternating up and down arcs along the sagittal plane. It is most commonly, but not universally, used to indicate agreement, acceptance, or acknowledgement.] -*** Pump-fist {relatedTag=Move-upper-extremity}[Raise with fist clenched in triumph or affirmation.] -*** Raise-eyebrows {relatedTag=Move-face, relatedTag=Move-eyes}[Move eyebrows upward.] -*** Shake-fist {relatedTag=Move-upper-extremity}[Clench hand into a fist and shake to demonstrate anger.] -*** Shake-head {relatedTag=Move-head}[Turn head from side to side as a way of showing disagreement or refusal.] -*** Shhh {relatedTag=Move-upper-extremity}[Place finger over lips and possibly uttering the syllable shhh to indicate the need to be quiet.] -*** Shrug {relatedTag=Move-upper-extremity, relatedTag=Move-torso}[Lift shoulders up towards head to indicate a lack of knowledge about a particular topic.] -*** Smile {relatedTag=Move-face}[Form facial features into a pleased, kind, or amused expression, typically with the corners of the mouth turned up and the front teeth exposed.] -*** Spread-hands {relatedTag=Move-upper-extremity}[Spread hands apart to indicate ignorance.] -*** Thumbs-down {relatedTag=Move-upper-extremity}[Extend the thumb downward to indicate disapproval.] -*** Thumb-up {relatedTag=Move-upper-extremity}[Extend the thumb upward to indicate approval.] -*** Wave {relatedTag=Move-upper-extremity}[Raise hand and move left and right, as a greeting or sign of departure.] -*** Widen-eyes {relatedTag=Move-face, relatedTag=Move-eyes}[Open eyes and possibly with eyebrows lifted especially to express surprise or fear.] -*** Wink {relatedTag=Move-face, relatedTag=Move-eyes}[Close and open one eye quickly, typically to indicate that something is a joke or a secret or as a signal of affection or greeting.] -** Communicate-musically [Communicate using music.] -*** Hum [Make a low, steady continuous sound like that of a bee. Sing with the lips closed and without uttering speech.] -*** Play-instrument [Make musical sounds using an instrument.] -*** Sing [Produce musical tones by means of the voice.] -*** Vocalize [Utter vocal sounds.] -*** Whistle [Produce a shrill clear sound by forcing breath out or air in through the puckered lips.] -** Communicate-vocally [Communicate using mouth or vocal cords.] -*** Cry [Shed tears associated with emotions, usually sadness but also joy or frustration.] -*** Groan [Make a deep inarticulate sound in response to pain or despair.] -*** Laugh [Make the spontaneous sounds and movements of the face and body that are the instinctive expressions of lively amusement and sometimes also of contempt or derision.] -*** Scream [Make loud, vociferous cries or yells to express pain, excitement, or fear.] -*** Shout [Say something very loudly.] -*** Sigh [Emit a long, deep, audible breath expressing sadness, relief, tiredness, or a similar feeling.] -*** Speak [Communicate using spoken language.] -*** Whisper [Speak very softly using breath without vocal cords.] -* Move [Move in a specified direction or manner. Change position or posture.] -** Breathe [Inhale or exhale during respiration.] -*** Blow [Expel air through pursed lips.] -*** Cough [Suddenly and audibly expel air from the lungs through a partially closed glottis, preceded by inhalation.] -*** Exhale [Blow out or expel breath.] -*** Hiccup [Involuntarily spasm the diaphragm and respiratory organs, with a sudden closure of the glottis and a characteristic sound like that of a cough.] -*** Hold-breath [Interrupt normal breathing by ceasing to inhale or exhale.] -*** Inhale [Draw in with the breath through the nose or mouth.] -*** Sneeze [Suddenly and violently expel breath through the nose and mouth.] -*** Sniff [Draw in air audibly through the nose to detect a smell, to stop it from running, or to express contempt.] -** Move-body [Move entire body.] -*** Bend [Move body in a bowed or curved manner.] -*** Dance [Perform a purposefully selected sequences of human movement often with aesthetic or symbolic value. Move rhythmically to music, typically following a set sequence of steps.] -*** Fall-down [Lose balance and collapse.] -*** Flex [Cause a muscle to stand out by contracting or tensing it. Bend a limb or joint.] -*** Jerk [Make a quick, sharp, sudden movement.] -*** Lie-down [Move to a horizontal or resting position.] -*** Recover-balance [Return to a stable, upright body position.] -*** Sit-down [Move from a standing to a sitting position.] -*** Sit-up [Move from lying down to a sitting position.] -*** Stand-up [Move from a sitting to a standing position.] -*** Stretch [Straighten or extend body or a part of body to its full length, typically so as to tighten muscles or in order to reach something.] -*** Shudder [Tremble convulsively, sometimes as a result of fear or revulsion.] -*** Stumble [Trip or momentarily lose balance and almost fall.] -*** Turn [Change or cause to change direction.] -** Move-body-part [Move one part of a body.] -*** Move-eyes [Move eyes.] -**** Blink [Shut and open the eyes quickly.] -**** Close-eyes [Lower and keep eyelids in a closed position.] -**** Fixate [Direct eyes to a specific point or target.] -**** Inhibit-blinks [Purposely prevent blinking.] -**** Open-eyes [Raise eyelids to expose pupil.] -**** Saccade [Move eyes rapidly between fixation points.] -**** Squint [Squeeze one or both eyes partly closed in an attempt to see more clearly or as a reaction to strong light.] -**** Stare [Look fixedly or vacantly at someone or something with eyes wide open.] -*** Move-face [Move the face or jaw.] -**** Bite [Seize with teeth or jaws an object or organism so as to grip or break the surface covering.] -**** Burp [Noisily release air from the stomach through the mouth. Belch.] -**** Chew [Repeatedly grinding, tearing, and or crushing with teeth or jaws.] -**** Gurgle [Make a hollow bubbling sound like that made by water running out of a bottle.] -**** Swallow [Cause or allow something, especially food or drink to pass down the throat.] -***** Gulp [Swallow quickly or in large mouthfuls, often audibly, sometimes to indicate apprehension.] -**** Yawn [Take a deep involuntary inhalation with the mouth open often as a sign of drowsiness or boredom.] -*** Move-head [Move head.] -**** Lift-head [Tilt head back lifting chin.] -**** Lower-head [Move head downward so that eyes are in a lower position.] -**** Turn-head [Rotate head horizontally to look in a different direction.] -*** Move-lower-extremity [Move leg and/or foot.] -**** Curl-toes [Bend toes sometimes to grip.] -**** Hop [Jump on one foot.] -**** Jog [Run at a trot to exercise.] -**** Jump [Move off the ground or other surface through sudden muscular effort in the legs.] -**** Kick [Strike out or flail with the foot or feet. Strike using the leg, in unison usually with an area of the knee or lower using the foot.] -**** Pedal [Move by working the pedals of a bicycle or other machine.] -**** Press-foot [Move by pressing foot.] -**** Run [Travel on foot at a fast pace.] -**** Step [Put one leg in front of the other and shift weight onto it.] -***** Heel-strike [Strike the ground with the heel during a step.] -***** Toe-off [Push with toe as part of a stride.] -**** Trot [Run at a moderate pace, typically with short steps.] -**** Walk [Move at a regular pace by lifting and setting down each foot in turn never having both feet off the ground at once.] -*** Move-torso [Move body trunk.] -*** Move-upper-extremity [Move arm, shoulder, and/or hand.] -**** Drop [Let or cause to fall vertically.] -**** Grab [Seize suddenly or quickly. Snatch or clutch.] -**** Grasp [Seize and hold firmly.] -**** Hold-down [Prevent someone or something from moving by holding them firmly.] -**** Lift [Raising something to higher position.] -**** Make-fist [Close hand tightly with the fingers bent against the palm.] -**** Point [Draw attention to something by extending a finger or arm.] -**** Press {relatedTag=Push}[Apply pressure to something to flatten, shape, smooth or depress it. This action tag should be used to indicate key presses and mouse clicks.] -**** Push {relatedTag=Press}[Apply force in order to move something away. Use Press to indicate a key press or mouse click.] -**** Reach [Stretch out your arm in order to get or touch something.] -**** Release [Make available or set free.] -**** Retract [Draw or pull back.] -**** Scratch [Drag claws or nails over a surface or on skin.] -**** Snap-fingers [Make a noise by pushing second finger hard against thumb and then releasing it suddenly so that it hits the base of the thumb.] -**** Touch [Come into or be in contact with.] -* Perceive [Produce an internal, conscious image through stimulating a sensory system.] -** Hear [Give attention to a sound.] -** See [Direct gaze toward someone or something or in a specified direction.] -** Smell [Inhale in order to ascertain an odor or scent.] -** Taste [Sense a flavor in the mouth and throat on contact with a substance.] -** Sense-by-touch [Sense something through receptors in the skin.] -* Perform [Carry out or accomplish an action, task, or function.] -** Close [Act as to blocked against entry or passage.] -** Collide-with [Hit with force when moving.] -** Halt [Bring or come to an abrupt stop.] -** Modify [Change something.] -** Open [Widen an aperture, door, or gap, especially one allowing access to something.] -** Operate [Control the functioning of a machine, process, or system.] -** Play [Engage in activity for enjoyment and recreation rather than a serious or practical purpose.] -** Read [Interpret something that is written or printed.] -** Repeat [Make do or perform again.] -** Rest [Be inactive in order to regain strength, health, or energy.] -** Write [Communicate or express by means of letters or symbols written or imprinted on a surface.] -* Think [Direct the mind toward someone or something or use the mind actively to form connected ideas.] -** Allow [Allow access to something such as allowing a car to pass.] -** Attend-to [Focus mental experience on specific targets.] -** Count [Tally items either silently or aloud.] -** Deny [Refuse to give or grant something requested or desired by someone.] -** Detect [Discover or identify the presence or existence of something.] -** Discriminate [Recognize a distinction.] -** Encode [Convert information or an instruction into a particular form.] -** Evade [Escape or avoid, especially by cleverness or trickery.] -** Generate [Cause something, especially an emotion or situation to arise or come about.] -** Identify [Establish or indicate who or what someone or something is.] -** Imagine [Form a mental image or concept of something.] -** Judge [Evaluate evidence to make a decision or form a belief.] -** Learn [Adaptively change behavior as the result of experience.] -** Memorize [Adaptively change behavior as the result of experience.] -** Plan [Think about the activities required to achieve a desired goal. ] -** Predict [Say or estimate that something will happen or will be a consequence of something without having exact informaton.] -** Recognize [Identify someone or something from having encountered them before.] -** Respond [React to something such as a treatment or a stimulus.] -** Recall [Remember information by mental effort.] -** Switch-attention [Transfer attention from one focus to another.] -** Track [Follow a person, animal, or object through space or time.] - -'''Item''' {extensionAllowed}[An independently existing thing (living or nonliving).] -* Biological-item [An entity that is biological, that is related to living organisms.] -** Anatomical-item [A biological structure, system, fluid or other substance excluding single molecular entities.] -*** Body [The biological structure representing an organism.] -*** Body-part [Any part of an organism.] -**** Head [The upper part of the human body, or the front or upper part of the body of an animal, typically separated from the rest of the body by a neck, and containing the brain, mouth, and sense organs.] -***** Hair [The filamentous outgrowth of the epidermis.] -***** Ear [A sense organ needed for the detection of sound and for establishing balance.] -***** Face [The anterior portion of the head extending from the forehead to the chin and ear to ear. The facial structures contain the eyes, nose and mouth, cheeks and jaws.] -****** Cheek [The fleshy part of the face bounded by the eyes, nose, ear, and jaw line.] -****** Chin [The part of the face below the lower lip and including the protruding part of the lower jaw.] -****** Eye [The organ of sight or vision.] -****** Eyebrow [The arched strip of hair on the bony ridge above each eye socket.] -****** Forehead [The part of the face between the eyebrows and the normal hairline.] -****** Lip [Fleshy fold which surrounds the opening of the mouth.] -****** Nose [A structure of special sense serving as an organ of the sense of smell and as an entrance to the respiratory tract.] -****** Mouth [The proximal portion of the digestive tract, containing the oral cavity and bounded by the oral opening.] -****** Teeth [The hard bonelike structures in the jaws. A collection of teeth arranged in some pattern in the mouth or other part of the body.] -**** Lower-extremity [Refers to the whole inferior limb (leg and/or foot).] -***** Ankle [A gliding joint between the distal ends of the tibia and fibula and the proximal end of the talus.] -***** Calf [The fleshy part at the back of the leg below the knee.] -***** Foot [The structure found below the ankle joint required for locomotion.] -****** Big-toe [The largest toe on the inner side of the foot.] -****** Heel [The back of the foot below the ankle.] -****** Instep [The part of the foot between the ball and the heel on the inner side.] -****** Little-toe [The smallest toe located on the outer side of the foot.] -****** Toes [The terminal digits of the foot.] -***** Knee [A joint connecting the lower part of the femur with the upper part of the tibia.] -***** Shin [Front part of the leg below the knee.] -***** Thigh [Upper part of the leg between hip and knee.] -**** Torso [The body excluding the head and neck and limbs.] -***** Torso-back [The rear surface of the human body from the shoulders to the hips.] -***** Buttocks [The round fleshy parts that form the lower rear area of a human trunk.] -***** Torso-chest [The anterior side of the thorax from the neck to the abdomen.] -***** Gentalia [The external organs of reproduction.] -***** Hip [The lateral prominence of the pelvis from the waist to the thigh.] -***** Waist [The abdominal circumference at the navel.] -**** Upper-extremity [Refers to the whole superior limb (shoulder, arm, elbow, wrist, hand).] -***** Elbow [A type of hinge joint located between the forearm and upper arm.] -***** Forearm [Lower part of the arm between the elbow and wrist.] -***** Hand [The distal portion of the upper extremity. It consists of the carpus, metacarpus, and digits.] -****** Finger [Any of the digits of the hand.] -******* Index-finger [The second finger from the radial side of the hand, next to the thumb.] -******* Little-finger [The fifth and smallest finger from the radial side of the hand.] -******* Middle-finger [The middle or third finger from the radial side of the hand.] -******* Ring-finger [The fourth finger from the radial side of the hand.] -******* Thumb [The thick and short hand digit which is next to the index finger in humans.] -****** Palm [The part of the inner surface of the hand that extends from the wrist to the bases of the fingers.] -****** Knuckles [A part of a finger at a joint where the bone is near the surface, especially where the finger joins the hand.] -***** Shoulder [Joint attaching upper arm to trunk.] -***** Upper-arm [Portion of arm between shoulder and elbow.] -***** Wrist [A joint between the distal end of the radius and the proximal row of carpal bones.] -** Organism [A living entity, more specifically a biological entity that consists of one or more cells and is capable of genomic replication (independently or not).] -*** Animal [A living organism that has membranous cell walls, requires oxygen and organic foods, and is capable of voluntary movement.] -*** Human [The bipedal primate mammal Homo sapiens.] -*** Plant [Any living organism that typically synthesizes its food from inorganic substances and possesses cellulose cell walls.] -* Language-item {suggestedTag=Sensory-presentation}[An entity related to a systematic means of communicating by the use of sounds, symbols, or gestures.] -** Character [A mark or symbol used in writing.] -** Clause [A unit of grammatical organization next below the sentence in rank, usually consisting of a subject and predicate.] -** Glyph [A hieroglyphic character, symbol, or pictograph.] -** Nonword [A group of letters or speech sounds that looks or sounds like a word but that is not accepted as such by native speakers.] -** Paragraph [A distinct section of a piece of writing, usually dealing with a single theme.] -** Phoneme [A speech sound that is distinguished by the speakers of a particular language.] -** Phrase [A phrase is a group of words functioning as a single unit in the syntax of a sentence.] -** Sentence [A set of words that is complete in itself, conveying a statement, question, exclamation, or command and typically containing an explicit or implied subject and a predicate containing a finite verb.] -** Syllable [A unit of spoken language larger than a phoneme.] -** Textblock [A block of text.] -** Word [A word is the smallest free form (an item that may be expressed in isolation with semantic or pragmatic content) in a language.] -* Object {suggestedTag=Sensory-presentation}[Something perceptible by one or more of the senses, especially by vision or touch. A material thing.] -** Geometric-object [An object or a representation that has structure and topology in space.] -*** Pattern [An arrangement of objects, facts, behaviors, or other things which have scientific, mathematical, geometric, statistical, or other meaning.] -**** Dots [A small round mark or spot.] -**** LED-pattern [A pattern created by lighting selected members of a fixed light emitting diode array.] -*** 2D-shape [A planar, two-dimensional shape.] -**** Arrow [A shape with a pointed end indicating direction.]. -**** Clockface [The dial face of a clock. A location identifier based on clockface numbering or anatomic subregion.] -**** Cross [A figure or mark formed by two intersecting lines crossing at their midpoints.] -**** Dash [A horizontal stroke in writing or printing to mark a pause or break in sense or to represent omitted letters or words.] -**** Ellipse [A closed plane curve resulting from the intersection of a circular cone and a plane cutting completely through it, especially a plane not parallel to the base.] -***** Circle [A ring-shaped structure with every point equidistant from the center.] -**** Rectangle [A parallelogram with four right angles.] -***** Square [A square is a special rectangle with four equal sides.] -**** Single-point [A point is a geometric entity that is located in a zero-dimensional spatial region and whose position is defined by its coordinates in some coordinate system.] -**** Star [A conventional or stylized representation of a star, typically one having five or more points.] -**** Triangle [A three-sided polygon.] -*** 3D-shape [A geometric three-dimensional shape.] -**** Box [A square or rectangular vessel, usually made of cardboard or plastic.] -***** Cube [A solid or semi-solid in the shape of a three dimensional square.] -**** Cone [A shape whose base is a circle and whose sides taper up to a point.] -**** Cylinder [A surface formed by circles of a given radius that are contained in a plane perpendicular to a given axis, whose centers align on the axis.] -**** Ellipsoid [A closed plane curve resulting from the intersection of a circular cone and a plane cutting completely through it, especially a plane not parallel to the base. ] -***** Sphere [A solid or hollow three-dimensional object bounded by a closed surface such that every point on the surface is equidistant from the center.] -**** Pyramid [A polyhedron of which one face is a polygon of any number of sides, and the other faces are triangles with a common vertex.] -** Ingestible-object [Something that can be taken into the body by the mouth for digestion or absorption.] -** Man-made-object [Something constructed by human means.] -*** Building [A structure that has a roof and walls and stands more or less permanently in one place.] -**** Room [An area within a building enclosed by walls and floor and ceiling.] -**** Roof [A roof is the covering on the uppermost part of a building which provides protection from animals and weather, notably rain, but also heat, wind and sunlight.] -**** Entrance [The means or place of entry.] -**** Attic [A room or a space immediately below the roof of a building.] -**** Basement [The part of a building that is wholly or partly below ground level.] -*** Clothing [A covering designed to be worn on the body.] -*** Device [An object contrived for a specific purpose.] -**** Assistive-device [A device that help an individual accomplish a task.] -***** Glasses [Frames with lenses worn in front of the eye for vision correction, eye protection, or protection from UV rays.] -***** Writing-device [A device used for writing.] -****** Pen [A common writing instrument used to apply ink to a surface for writing or drawing.] -****** Pencil [An implement for writing or drawing that is constructed of a narrow solid pigment core in a protective casing that prevents the core from being broken or marking the hand.] -**** Computing-device [An electronic device which take inputs and processes results from the inputs.] -***** Cellphone [A telephone with access to a cellular radio system so it can be used over a wide area, without a physical connection to a network.] -***** Desktop-computer [A computer suitable for use at an ordinary desk.] -***** Laptop-computer [A computer that is portable and suitable for use while traveling.] -***** Tablet-computer [A small portable computer that accepts input directly on to its screen rather than via a keyboard or mouse.] -**** Engine [A motor is a machine designed to convert one or more forms of energy into mechanical energy.] -**** IO-device [Hardware used by a human (or other system) to communicate with a computer.] -***** Input-device [A piece of equipment used to provide data and control signals to an information processing system such as a computer or information appliance.] -****** Computer-mouse [A hand-held pointing device that detects two-dimensional motion relative to a surface.] -******* Mouse-button [An electric switch on a computer mouse which can be pressed or clicked to select or interact with an element of a graphical user interface.] -******* Scroll-wheel [A scroll wheel or mouse wheel is a wheel used for scrolling made of hard plastic with a rubbery surface usually located between the left and right mouse buttons and is positioned perpendicular to the mouse surface.] -****** Joystick [A control device that uses a movable handle to create two-axis input for a computer device.] -****** Keyboard [A device consisting of mechanical keys that are pressed to create input to a computer.] -******* Keyboard-key [A button on a keyboard usually representing letters, numbers, functions, or symbols.] -******** # {takesValue}[Value of a keyboard key.] -****** Keypad [A device consisting of keys, usually in a block arrangement, that provides limited input to a system.] -******* Keypad-key [A key on a separate section of a computer keyboard that groups together numeric keys and those for mathematical or other special functions in an arrangement like that of a calculator.] -******** # {takesValue}[Value of keypad key.] -****** Microphone [A device designed to convert sound to an electrical signal.] -****** Push-button [A switch designed to be operated by pressing a button.] -***** Output-device [Any piece of computer hardware equipment which converts information into human understandable form.] -****** Display-device [An output device for presentation of information in visual or tactile form the latter used for example in tactile electronic displays for blind people.] -******* Head-mounted-display [An instrument that functions as a display device, worn on the head or as part of a helmet, that has a small display optic in front of one (monocular HMD) or each eye (binocular HMD).] -******* LED-display [A LED display is a flat panel display that uses an array of light-emitting diodes as pixels for a video display.] -******* Computer-screen [An electronic device designed as a display or a physical device designed to be a protective meshwork.] -******** Screen-window [A part of a computer screen that contains a display different from the rest of the screen. A window is a graphical control element consisting of a visual area containing some of the graphical user interface of the program it belongs to and is framed by a window decoration.] -****** Auditory-device [A device designed to produce sound.] -******* Headphones [An instrument that consists of a pair of small loudspeakers, or less commonly a single speaker, held close to ears and connected to a signal source such as an audio amplifier, radio, CD player or portable media player.] -******* Loudspeaker [A device designed to convert electrical signals to sounds that can be heard.] -***** Recording-device [A device that copies information in a signal into a persistent information bearer.] -****** EEG-recorder [A device for recording electric currents in the brain using electrodes applied to the scalp, to the surface of the brain, or placed within the substance of the brain.] -****** File-storage [A device for recording digital information to a permanent media.] -****** MEG-recorder [A device for measuring the magnetic fields produced by electrical activity in the brain, usually conducted externally.] -****** Motion-capture [A device for recording the movement of objects or people.] -****** Tape-recorder [A device for recording and reproduction usually using magnetic tape for storage that can be saved and played back.] -***** Touchscreen [A control component that operates an electronic device by pressing the display on the screen.] -**** Machine [A human-made device that uses power to apply forces and control movement to perform an action.] -**** Measurement-device [A device in which a measure function inheres.] -***** Clock [A device designed to indicate the time of day or to measure the time duration of an event or action.] -****** Clock-face [A location identifier based on clockface numbering or anatomic subregion.] -**** Robot [A mechanical device that sometimes resembles a living animal and is capable of performing a variety of often complex human tasks on command or by being programmed in advance.] -**** Tool [A component that is not part of a device but is designed to support its assemby or operation.] -*** Document [A physical object, or electronic counterpart, that is characterized by containing writing which is meant to be human-readable.] -**** Letter [A written message addressed to a person or organization.] -**** Note [A brief written record.] -**** Book [A volume made up of pages fastened along one edge and enclosed between protective covers.] -**** Notebook [A book for notes or memoranda.] -**** Questionnaire [A document consisting of questions and possibly responses, depending on whether it has been filled out.] -*** Furnishing [Furniture, fittings, and other decorative accessories, such as curtains and carpets, for a house or room.] -*** Manufactured-material [Substances created or extracted from raw materials.] -**** Ceramic [A hard, brittle, heat-resistant and corrosion-resistant material made by shaping and then firing a nonmetallic mineral, such as clay, at a high temperature.] -**** Glass [A brittle transparent solid with irregular atomic structure.] -**** Paper [A thin sheet material produced by mechanically or chemically processing cellulose fibres derived from wood, rags, grasses or other vegetable sources in water.] -**** Plastic [Various high-molecular-weight thermoplastic or thermosetting polymers that are capable of being molded, extruded, drawn, or otherwise shaped and then hardened into a form.] -**** Steel [An alloy made up of iron with typically a few tenths of a percent of carbon to improve its strength and fracture resistance compared to iron.] -*** Media [Media are audo/visual/audiovisual modes of communicating information for mass consumption.] -**** Media-clip [A short segment of media.] -***** Audio-clip [A short segment of audio.] -***** Audiovisual-clip [A short media segment containing both audio and video.] -***** Video-clip [A short segment of video.] -**** Visualization [An planned process that creates images, diagrams or animations from the input data.] -***** Animation [A form of graphical illustration that changes with time to give a sense of motion or represent dynamic changes in the portrayal.] -***** Art-installation [A large-scale, mixed-media constructions, often designed for a specific place or for a temporary period of time.] -***** Braille [A display using a system of raised dots that can be read with the fingers by people who are blind.] -***** Image [Any record of an imaging event whether physical or electronic.] -****** Cartoon [A type of illustration, sometimes animated, typically in a non-realistic or semi-realistic style. The specific meaning has evolved over time, but the modern usage usually refers to either an image or series of images intended for satire, caricature, or humor. A motion picture that relies on a sequence of illustrations for its animation.] -****** Drawing [A representation of an object or outlining a figure, plan, or sketch by means of lines.] -****** Icon [A sign (such as a word or graphic symbol) whose form suggests its meaning.] -****** Painting [A work produced through the art of painting.] -****** Photograph [An image recorded by a camera.] -***** Movie [A sequence of images displayed in succession giving the illusion of continuous movement.] -***** Outline-visualization [A visualization consisting of a line or set of lines enclosing or indicating the shape of an object in a sketch or diagram.] -***** Point-light-visualization [A display in which action is depicted using a few points of light, often generated from discrete sensors in motion capture.] -***** Sculpture [A two- or three-dimensional representative or abstract forms, especially by carving stone or wood or by casting metal or plaster.] -***** Stick-figure-visualization [A drawing showing the head of a human being or animal as a circle and all other parts as straight lines.] -*** Navigational-object [An object whose purpose is to assist directed movement from one location to another.] -**** Path [A trodden way. A way or track laid down for walking or made by continual treading.] -**** Road [An open way for the passage of vehicles, persons, or animals on land.] -***** Lane [A defined path with physical dimensions through which an object or substance may traverse.] -**** Runway [A paved strip of ground on a landing field for the landing and takeoff of aircraft.] -*** Vehicle [A mobile machine which transports people or cargo.] -**** Aircraft [A vehicle which is able to travel through air in an atmosphere.] -**** Bicycle [A human-powered, pedal-driven, single-track vehicle, having two wheels attached to a frame, one behind the other.] -**** Boat [A watercraft of any size which is able to float or plane on water.] -**** Car [A wheeled motor vehicle used primarily for the transportation of human passengers.] -**** Cart [A cart is a vehicle which has two wheels and is designed to transport human passengers or cargo.] -**** Tractor [A mobile machine specifically designed to deliver a high tractive effort at slow speeds, and mainly used for the purposes of hauling a trailer or machinery used in agriculture or construction.] -**** Train [A connected line of railroad cars with or without a locomotive.] -**** Truck [A motor vehicle which, as its primary funcion, transports cargo rather than human passangers.] -** Natural-object [Something that exists in or is produced by nature, and is not artificial or man-made.] -*** Mineral [A solid, homogeneous, inorganic substance occurring in nature and having a definite chemical composition.] -*** Natural-feature [A feature that occurs in nature. A prominent or identifiable aspect, region, or site of interest.] -**** Field [An unbroken expanse as of ice or grassland.] -**** Hill [A rounded elevation of limited extent rising above the surrounding land with local relief of less than 300m.] -**** Mountain [A landform that extends above the surrounding terrain in a limited area.] -**** River [A natural freshwater surface stream of considerable volume and a permanent or seasonal flow, moving in a definite channel toward a sea, lake, or another river.] -**** Waterfall [A sudden descent of water over a step or ledge in the bed of a river.] -* Sound [Mechanical vibrations transmitted by an elastic medium. Something that can be heard.] -** Environmental-sound[Sounds occuring in the environment. An accumulation of noise pollution that occurs outside. This noise can be caused by transport, industrial, and recreational activities.] -*** Crowd-sound [Noise produced by a mixture of sounds from a large group of people.] -*** Signal-noise [Any part of a signal that is not the true or original signal but is introduced by the communication mechanism.] -** Musical-sound [Sound produced by continuous and regular vibrations, as opposed to noise.] -*** Tone [A musical note, warble, or other sound used as a particular signal on a telephone or answering machine.] -*** Instrument-sound [Sound produced by a musical instrument.] -*** Vocalized-sound [Musical sound produced by vocal cords in a biological agent.] -** Named-animal-sound [A sound recognizable as being associated with particular animals.] -*** Barking [Sharp explosive cries like sounds made by certain animals, especially a dog, fox, or seal.] -*** Bleating [Wavering cries like sounds made by a sheep, goat, or calf.] -*** Crowing [Loud shrill sounds characteristic of roosters.] -*** Chirping [Short, sharp, high-pitched noises like sounds made by small birds or an insects.] -*** Growling [Low guttural sounds like those that made in the throat by a hostile dog or other animal.] -*** Meowing [Vocalizations like those made by as those cats. These sounds have diverse tones and are sometimes chattered, murmured or whispered. The purpose can be assertive.] -*** Mooing [Deep vocal sounds like those made by a cow.] -*** Purring [Low continuous vibratory sound such as those made by cats. The sound expresses contentment.] -*** Roaring [Loud, deep, or harsh prolonged sounds such as those made by big cats and bears for long-distance communication and intimidation.] -*** Squawking [Loud, harsh noises such as those made by geese.] -** Named-object-sound [A sound identifiable as coming from a particular type of object.] -*** Alarm-sound [A loud signal often loud continuous ringing to alert people to a problem or condition that requires urgent attention.] -*** Beep [A short, single tone, that is typically high-pitched and generally made by a computer or other machine. ] -*** Buzz [A persistent vibratory sound often made by a buzzer device and used to indicate something incorrect.] -*** Ka-ching [The sound made by a mechanical cash register, often to designate a reward.] -*** Click [The sound made by a mechanical cash register, often to designate a reward.] -*** Ding [A short ringing sound such as that made by a bell, often to indicate a correct response or the expiration of time.] -*** Horn-blow [A loud sound made by forcing air through a sound device that funnels air to create the sound, often used to sound an alert.] -*** Siren [A loud, continuous sound often varying in frequency designed to indicate an emergency.] - -'''Property''' {extensionAllowed}[Something that pertains to a thing. A characteristic of some entity. A quality or feature regarded as a characteristic or inherent part of someone or something. HED attributes are adjectives or adverbs.] -* Agent-property {extensionAllowed}[Something that pertains to an agent.] -** Agent-state [The state of the agent.] -*** Agent-cognitive-state [The state of the cognitive processes or state of mind of the agent.] -**** Alert [Condition of heightened watchfulness or preparation for action.] -**** Anesthetized [Having lost sensation to pain or having senses dulled due to the effects of an anesthetic.] -**** Asleep [Having entered a periodic, readily reversible state of reduced awareness and metabolic activity, usually accompanied by physical relaxation and brain activity.] -**** Attentive [Concentrating and focusing mental energy on the task or surroundings.] -**** Distracted [Lacking in concentration because of being preoccupied.] -**** Awake [In a non sleeping state.] -**** Brain-dead [Characterized by the irreversible absence of cortical and brain stem functioning.] -**** Comatose [In a state of profound unconsciousness associated with markedly depressed cerebral activity.] -**** Drowsy [In a state of near-sleep, a strong desire for sleep, or sleeping for unusually long periods.] -**** Intoxicated [In a state with disturbed psychophysiological functions and responses as a result of administration or ingestion of a psychoactive substance.] -**** Locked-in [In a state of complete paralysis of all voluntary muscles except for the ones that control the movements of the eyes.] -**** Passive [Not responding or initiating an action in response to a stimulus.] -**** Resting [A state in which the agent is not exhibiting any physical exertion.] -**** Vegetative [A state of wakefulness and conscience, but (in contrast to coma) with involuntary opening of the eyes and movements (such as teeth grinding, yawning, or thrashing of the extremities).] -*** Agent-emotional-state [The status of the general temperament and outlook of an agent.] -**** Angry [Experiencing emotions characterized by marked annoyance or hostility.] -**** Aroused [In a state reactive to stimuli leading to increased heart rate and blood pressure, sensory alertness, mobility and readiness to respond.] -**** Awed [Filled with wonder. Feeling grand, sublime or powerful emotions characterized by a combination of joy, fear, admiration, reverence, and/or respect.] -**** Compassionate [Feeling or showing sympathy and concern for others often evoked for a person who is in distress and associated with altruistic motivation.] -**** Content [Feeling satisfaction with things as they are.] -**** Disgusted [Feeling revulsion or profound disapproval aroused by something unpleasant or offensive.] -**** Emotionally-neutral [Feeling neither satisfied nor dissatisfied.] -**** Empathetic [Understanding and sharing the feelings of another. Being aware of, being sensitive to, and vicariously experiencing the feelings, thoughts, and experience of another.] -**** Excited [Feeling great enthusiasm and eagerness.] -**** Fearful [Feeling apprehension that one may be in danger.] -**** Frustrated [Feeling annoyed as a result of being blocked, thwarted, disappointed or defeated.] -**** Grieving [Feeling sorrow in response to loss, whether physical or abstract.] -**** Happy [Feeling pleased and content.] -**** Jealous [Feeling threatened by a rival in a relationship with another individual, in particular an intimate partner, usually involves feelings of threat, fear, suspicion, distrust, anxiety, anger, betrayal, and rejection.] -**** Joyful [Feeling delight or intense happiness.] -**** Loving [Feeling a strong positive emotion of affection and attraction.] -**** Relieved [No longer feeling pain, distress, anxiety, or reassured.] -**** Sad [Feeling grief or unhappiness.] -**** Stressed [Experiencing mental or emotional strain or tension.] -*** Agent-physiological-state [Having to do with the mechanical, physical, or biochemical function of an agent.] -**** Healthy {relatedTag=Sick}[Having no significant health-related issues.] -**** Hungry {relatedTag=Sated, relatedTag=Thirsty}[Being in a state of craving or desiring food.] -**** Rested {relatedTag=Tired}[Feeling refreshed and relaxed.] -**** Sated {relatedTag=Hungry}[Feeling full.] -**** Sick {relatedTag=Healthy}[Being in a state of ill health, bodily malfunction, or discomfort.] -**** Thirsty {relatedTag=Hungry}[Feeling a need to drink.] -**** Tired {relatedTag=Rested}[Feeling in need of sleep or rest.] -*** Agent-postural-state [Pertaining to the position in which agent holds their body.] -**** Crouching [Adopting a position where the knees are bent and the upper body is brought forward and down, sometimes to avoid detection or to defend oneself.] -**** Eyes-closed [Keeping eyes closed with no blinking.] -**** Eyes-open [Keeping eyes open with occasional blinking.] -**** Kneeling [Positioned where one or both knees are on the ground.] -**** On-treadmill [Ambulation on an exercise apparatus with an endless moving belt to support moving in place.] -**** Prone [Positioned in a recumbent body position whereby the person lies on its stomach and faces downward.] -**** Sitting [In a seated position.] -**** Standing [Assuming or maintaining an erect upright position.] -**** Seated-with-chin-rest [Using a device that supports the chin and head.] -** Agent-task-role [The function or part that is ascribed to an agent in performing the task.] -*** Experiment-actor [An agent who plays a predetermined role to create the experiment scenario.] -*** Experiment-controller [An agent exerting control over some aspect of the experiment.] -*** Experiment-participant [Someone who takes part in an activity related to an experiment.] -*** Experimenter [Person who is the owner of the experiment and has its responsibility.] -** Agent-trait [A genetically, environmentally, or socially determined characteristic of an agent.] -*** Age [Length of time elapsed time since birth of the agent.] -**** # {takesValue, valueClass=numericClass} -*** Agent-experience-level [Amount of skill or knowledge that the agent has as pertains to the task.] -**** Expert-level {relatedTag=Intermediate-experience-level, relatedTag=Novice-level}[Having comprehensive and authoritative knowledge of or skill in a particular area related to the task.] -**** Intermediate-experience-level {relatedTag=Expert-level, relatedTag=Novice-level}[Having a moderate amount of knowledge or skill related to the task.] -**** Novice-level {relatedTag=Expert-level, relatedTag=Intermediate-experience-level} [Being inexperienced in a field or situation related to the task.] -*** Gender [Characteristics that are socially constructed, including norms, behaviors, and roles based on sex.] -*** Sex [Physical properties or qualities by which male is distinguished from female.] -**** Female [Biological sex of an individual with female sexual organs such ova.] -**** Male [Biological sex of an individual with male sexual organs producing sperm.] -**** Intersex [Having genitalia and/or secondary sexual characteristics of indeterminate sex.] -*** Ethnicity [Belong to a social group that has a common national or cultural tradition. Use with Label to avoid extension.] -*** Handedness [Individual preference for use of a hand, known as the dominant hand.] -**** Left-handed [Preference for using the left hand or foot for tasks requiring the use of a single hand or foot.] -**** Right-handed [Preference for using the right hand or foot for tasks requiring the use of a single hand or foot.] -**** Ambidextrous [Having no overall dominance in the use of right or left hand or foot in the performance of tasks that require one hand or foot.] -*** Race [Belonging to a group sharing physical or social qualities as defined within a specified society. Use with Label to avoid extension.] -* Data-property {extensionAllowed}[Something that pertains to data or information.] -** Data-marker [An indicator placed to mark something.] -*** Data-break-marker [An indicator place to indicate a gap in the data.] -*** Temporal-marker[An indicator placed at a particular time in the data.] -**** Onset {topLevelTagGroup}[Labels the start or beginning of something, usually an event.] -**** Offset {topLevelTagGroup}[Labels the time at which something stops.] -**** Pause [Indicates the temporary interruption of the operation a process and subsequently wait for a signal to continue.] -**** Time-out [A cancellation or cessation that automatically occurs when a predefined interval of time has passed without a certain event occurring.] -**** Time-sync [A synchronization signal whose purpose to help synchronize different signals or processes. Often used to indicate a marker inserted into the recorded data to allow post hoc synchronization of concurrently recorded data streams.] -** Data-resolution [Smallest change in a quality being measured by an sensor that causes a perceptible change.] -*** Printer-resolution [Resolution of a printer, usually expressed as the number of dots-per-inch for a printer.] -**** # {takesValue, valueClass=numericClass} -*** Screen-resolution [Resolution of a screen, usually expressed as the of pixels in a dimension for a digital display device.] -**** # {takesValue, valueClass=numericClass} -*** Sensory-resolution [Resolution of measurements by a sensing device.] -**** # {takesValue, valueClass=numericClass} -*** Spatial-resolution [Linear spacing of a spatial measurement.] -**** # {takesValue, valueClass=numericClass} -*** Spectral-resolution [Measures the ability of a sensor to resolve features in the electromagnetic spectrum.] -**** # {takesValue, valueClass=numericClass} -*** Temporal-resolution [Measures the ability of a sensor to resolve features in time.] -**** # {takesValue, valueClass=numericClass} -** Data-source-type [The type of place, person, or thing from which the data comes or can be obtained.] -*** Computed-feature[A feature computed from the data by a tool. This tag should be grouped with a label of the form Toolname_propertyName.] -*** Computed-prediction [A computed extrapolation of known data.] -*** Expert-annotation [An explanatory or critical comment or other in-context information provided by an authority.] -*** Instrument-measurement [Information obtained from a device that is used to measure material properties or make other observations.] -*** Observation [Active acquisition of information from a primary source. Should be grouped with a label of the form AgentID_featureName.] -** Data-value [Designation of the type of a data item.] -*** Categorical-value [Indicates that something can take on a limited and usually fixed number of possible values.] -**** Categorical-class-value [Categorical values that fall into discrete classes such as true or false. The grouping is absolute in the sense that it is the same for all participants.] -***** All {relatedTag=Some, relatedTag=None}[To a complete degree or to the full or entire extent.] -***** Correct {relatedTag=Wrong}[Free from error. Especially conforming to fact or truth.] -***** Explicit {relatedTag=Implicit}[Stated clearly and in detail, leaving no room for confusion or doubt.] -***** False {relatedTag=True}[Not in accordance with facts, reality or definitive criteria.] -***** Implicit {relatedTag=Explicit}[Implied though not plainly expressed.] -***** Invalid {relatedTag=Valid}[Not allowed or not conforming to the correct format or specifications.] -***** None {relatedTag=All, relatedTag=Some}[No person or thing, nobody, not any.] -***** Some {relatedTag=All, relatedTag=None}[At least a small amount or number of, but not a large amount of, or often.] -***** True {relatedTag=False}[Conforming to facts, reality or definitive criteria.] -***** Valid {relatedTag=Invalid}[Allowable, usable, or acceptable.] -***** Wrong {relatedTag=Correct}[Inaccurate or not correct.] -**** Categorical-judgment-value [Categorical values that are based on the judgment or perception of the participant such familiar and famous.] -***** Abnormal {relatedTag=Normal}[Deviating in any way from the state, position, structure, condition, behavior, or rule which is considered a norm.] -***** Asymmetrical {relatedTag=Symmetrical}[Lacking symmetry or having parts that fail to correspond to one another in shape, size, or arrangement.] -***** Audible {relatedTag=Inaudible}[A sound that can be perceived by the participant.] -***** Congruent {relatedTag=Incongruent}[Concordance of multiple evidence lines. In agreement or harmony.] -***** Complex {relatedTag=Simple}[Hard, involved or complicated, elaborate, having many parts.] -***** Constrained {relatedTag=Unconstrained}[Keeping something within particular limits or bounds.] -***** Disordered {relatedTag=Ordered}[Not neatly arranged. Confused and untidy. A structural quality in which the parts of an object are non-rigid.] -***** Familiar {relatedTag=Unfamiliar, relatedTag=Famous}[Recognized, familiar, or within the scope of knowledge.] -***** Famous {relatedTag=Familiar, relatedTag=Unfamiliar}[A person who has a high degree of recognition by the general population for his or her success or accomplishments. A famous person.] -***** Inaudible {relatedTag=Audible}[A sound below the threshold of perception of the participant.] -***** Incongruent {relatedTag=Congruent}[Not in agreement or harmony.] -***** Involuntary {relatedTag=Voluntary}[An action that is not made by choice. In the body, involuntary actions (such as blushing) occur automatically, and cannot be controlled by choice.] -***** Masked {relatedTag=Unmasked}[Information exists but is not provided or is partially obscured due to security, privacy, or other concerns.] -***** Normal {relatedTag=Abnormal}[Being approximately average or within certain limits. Conforming with or constituting a norm or standard or level or type or social norm.] -***** Ordered {relatedTag=Disordered}[Conforming to a logical or comprehensible arrangement of separate elements.] -***** Simple {relatedTag=Complex}[Easily understood or presenting no difficulties.] -***** Symmetrical {relatedTag=Asymmetrical}[Made up of exactly similar parts facing each other or around an axis. Showing aspects of symmetry.] -***** Unconstrained {relatedTag=Constrained}[Moving without restriction.] -***** Unfamiliar {relatedTag=Familiar,relatedTag=Famous}[Not having knowledge or experience of.] -***** Unmasked {relatedTag=Masked}[Information is revealed.] -***** Voluntary {relatedTag=Involuntary}[Using free will or design; not forced or compelled; controlled by individual volition.] -**** Categorical-level-value [Categorical values based on dividing a continuous variable into levels such as high and low.] -***** Cold {relatedTag=Hot}[Having an absence of heat.] -***** Deep {relatedTag=Shallow}[Extending relatively far inward or downward.] -***** High {relatedTag=Low, relatedTag=Medium}[Having a greater than normal degree, intensity, or amount.] -***** Hot {relatedTag=Cold}[Having an excess of heat.] -***** Large {relatedTag=Small}[Having a great extent such as in physical dimensions, period of time, amplitude or frequency.] -***** Liminal {relatedTag=Subliminal, relatedTag=Supraliminal}[Situated at a sensory threshold that is barely perceptible or capable of eliciting a response.] -***** Loud {relatedTag=Quiet}[Having a perceived high intensity of sound.] -***** Low {relatedTag=High}[Less than normal in degree, intensity or amount.] -***** Medium {relatedTag=Low, relatedTag=High}[Mid-way between small and large in number, quantity, magnitude or extent.] -***** Negative {relatedTag=Positive}[Involving disadvantage or harm.] -***** Positive {relatedTag=Negative}[Involving advantage or good.] -***** Quiet {relatedTag=Loud}[Characterizing a perceived low intensity of sound.] -***** Rough {relatedTag=Smooth}[Having a surface with perceptible bumps, ridges, or irregularities.] -***** Shallow {relatedTag=Deep}[Having a depth which is relatively low.] -***** Small {relatedTag=Large}[Having a small extent such as in physical dimensions, period of time, amplitude or frequency.] -***** Smooth {relatedTag=Rough}[Having a surface free from bumps, ridges, or irregularities.] -***** Subliminal {relatedTag=Liminal, relatedTag=Supraliminal}[Situated below a sensory threshold that is imperceptible or not capable of eliciting a response.] -***** Supraliminal {relatedTag=Liminal, relatedTag=Subliminal}[Situated above a sensory threshold that is perceptible or capable of eliciting a response.] -***** Thick {relatedTag=Thin}[Wide in width, extent or cross-section.] -***** Thin {relatedTag=Thick}[Narrow in width, extent or cross-section.] -**** Categorical-orientation-value [Value indicating the orientation or direction of something.] -***** Backward {relatedTag=Forward}[Directed behind or to the rear.] -***** Downward {relatedTag=Leftward,relatedTag=Rightward,relatedTag=Upward}[Moving or leading toward a lower place or level.] -***** Forward {relatedTag=Backward}[At or near or directed toward the front.] -***** Horizontally-oriented {relatedTag=Vertically-oriented}[Oriented parallel to or in the plane of the horizon.] -***** Leftward {relatedTag=Downward, relatedTag=Rightward,relatedTag=Upward}[Going toward or facing the left.] -***** Oblique {relatedTag=Rotated}[Slanting or inclined in direction, course, or position that is neither parallel nor perpendicular nor right-angular.] -***** Rightward {relatedTag=Downward, relatedTag=Leftward,relatedTag=Upward}[Going toward or situated on the right.] -***** Rotated [Positioned offset around an axis or center.] -***** Upward {relatedTag=Downward,relatedTag=Leftward,relatedTag=Rightward}[Moving, pointing, or leading to a higher place, point, or level.] -***** Vertically-oriented {relatedTag=Horizontally-oriented}[Oriented perpendicular to the plane of the horizon.] -*** Physical-value [The value of some physical property of something.] -**** Weight [The relative mass or the quantity of matter contained by something.] -***** # {takesValue, valueClass=numericClass, unitClass=weightUnits} -**** Temperature [A measure of hot or cold based on the average kinetic energy of the atoms or molecules in the system.] -***** # {takesValue, valueClass=numericClass, unitClass=temperatureUnits} -*** Quantitative-value [Something capable of being estimated or expressed with numeric values.] -**** Fraction [A numerical value between 0 and 1.] -***** # {takesValue, valueClass=numericClass} -**** Item-count [The integer count of something which is usually grouped with the entity it is counting. (Item-count/3, A) indicates that 3 of A have occurred up to this point.] -***** # {takesValue, valueClass=numericClass} -**** Item-index [The index of an item in a collection, sequence or other structure. (A (Item-index/3, B)) means that A is item number 3 in B.] -***** # {takesValue, valueClass=numericClass} -**** Item-interval [An integer indicating how many items or entities have passed since the last one of these. An item interval of 0 indicates the current item.] -***** # {takesValue, valueClass=numericClass} -**** Percentage [A fraction or ratio with 100 understood as the denominator.] -***** # {takesValue, valueClass=numericClass} -**** Ratio [A quotient of quantities of the same kind for different components within the same system.] -***** # {takesValue, valueClass=numericClass} -*** Statistical-value {extensionAllowed}[A value based on or employing the principles of statistics.] -**** Data-maximum [The largest possible quantity or degree.] -***** # {takesValue, valueClass=numericClass}[] -**** Data-mean [The sum of a set of values divided by the number of values in the set.] -***** # {takesValue, valueClass=numericClass} -**** Data-median [The value which has an equal number of values greater and less than it.] -***** # {takesValue, valueClass=numericClass} -**** Data-minimum [The smallest possible quantity.] -***** # {takesValue, valueClass=numericClass} -**** Probability [A measure of the expectation of the occurrence of a particular event.] -***** # {takesValue, valueClass=numericClass} -**** Standard-deviation [A measure of the range of values in a set of numbers. Standard deviation is a statistic used as a measure of the dispersion or variation in a distribution, equal to the square root of the arithmetic mean of the squares of the deviations from the arithmetic mean.] -***** # {takesValue, valueClass=numericClass} -**** Statistical-accuracy [A measure of closeness to true value expressed as a number between 0 and 1.] -***** # {takesValue, valueClass=numericClass} -**** Statistical-precision [A quantitative representation of the degree of accuracy necessary for or associated with a particular action.] -***** # {takesValue, valueClass=numericClass} -**** Statistical-recall [Sensitivity is a measurement datum qualifying a binary classification test and is computed by substracting the false negative rate to the integral numeral 1.] -***** # {takesValue, valueClass=numericClass} -**** Statistical-uncertainty [A measure of the inherent variability of repeated observation measurements of a quantity including quantities evaluated by statistical methods and by other means.] -***** # {takesValue, valueClass=numericClass} -*** Spatiotemporal-value [A property relating to space and/or time.] -**** Rate-of-change [The amount of change accumulated per unit time.] -***** Acceleration [Magnitude of the rate of change in either speed or direction. The direction of change should be given separately.] -****** # {takesValue, valueClass=numericClass, unitClass=accelerationUnits} -***** Frequency [Frequency is the number of occurrences of a repeating event per unit time.] -****** # {takesValue, valueClass=numericClass, unitClass=frequencyUnits} -***** Jerk-rate [Magnitude of the rate at which the acceleration of an object changes with respect to time. The direction of change should be given separately.] -****** # {takesValue, valueClass=numericClass, unitClass=jerkUnits} -***** Sampling-rate [The number of digital samples taken or recorded per unit of time.] -****** # {takesValue, unitClass=frequencyUnits} -***** Refresh-rate [The frequency with which the image on a computer monitor or similar electronic display screen is refreshed, usually expressed in hertz.] -****** # {takesValue, valueClass=numericClass} -***** Speed [A scalar measure of the rate of movement of the object expressed either as the distance travelled divided by the time taken (average speed) or the rate of change of position with respect to time at a particular point (instantaneous speed). The direction of change should be given separately.] -****** # {takesValue, valueClass=numericClass, unitClass=speedUnits} -***** Temporal-rate [The number of items per unit of time.] -****** # {takesValue, valueClass=numericClass, unitClass=frequencyUnits} -**** Spatial-value [Value of an item involving space.] -***** Angle[The amount of inclination of one line to another or the plane of one object to another.] -****** # {takesValue, unitClass=angleUnits, valueClass=numericClass} -***** Distance [A measure of the space separating two objects or points.] -****** # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -***** Position [A reference to the alignment of an object, a particular situation or view of a situation, or the location of an object. Coordinates with respect a specified frame of reference or the default Screen-frame if no frame is given.] -****** X-position [The position along the x-axis of the frame of reference.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Y-position [The position along the y-axis of the frame of reference.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Z-position [The position along the z-axis of the frame of reference.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -***** Size [The physical magnitude of something.] -****** Area [The extent of a 2-dimensional surface enclosed within a boundary.] -******* # {takesValue, valueClass=numericClass, unitClass=areaUnits} -****** Depth [The distance from the surface of something especially from the perspective of looking from the front.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Length [The linear extent in space from one end of something to the other end, or the extent of something from beginning to end.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Width [The extent or measurement of something from side to side.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Height [The vertical measurement or distance from the base to the top of an object.] -******* # {takesValue, valueClass=numericClass, unitClass=physicalLengthUnits} -****** Volume [The amount of three dimensional space occupied by an object or the capacity of a space or container.] -******* # {takesValue, valueClass=numericClass, unitClass=volumeUnits} -**** Temporal-value [A characteristic of or relating to time or limited by time.] -***** Delay [Time during which some action is awaited.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Duration [The period of time during which something occurs or continues.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Time-interval [The period of time separating two instances, events, or occurrences.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Time-value [A value with units of time. Usually grouped with tags identifying what the value represents.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -** Data-variability-attribute[An attribute describing how something changes or varies.] -*** Abrupt [Marked by sudden change.] -*** Constant [Continually recurring or continuing without interruption. Not changing in time or space.] -*** Continuous {relatedTag=Discrete,relatedTag=Discontinuous}[Uninterrupted in time, sequence, substance, or extent.] -*** Decreasing {relatedTag=Increasing}[Becoming smaller or fewer in size, amount, intensity, or degree.] -*** Deterministic {relatedTag=Random,relatedTag=Stochastic}[No randomness is involved in the development of the future states of the element.] -*** Discontinuous {relatedTag=Continuous}[Having a gap in time, sequence, substance, or extent.] -*** Discrete {relatedTag=Continuous,relatedTag=Discontinuous}[Constituting a separate entities or parts.] -*** Flickering [Moving irregularly or unsteadily or burning or shining fitfully or with a fluctuating light.] -*** Estimated-value [Something that has been calculated or measured approximately.] -*** Exact-value [A value that is viewed to the true value according to some standard.] -*** Fractal [Having extremely irregular curves or shapes for which any suitably chosen part is similar in shape to a given larger or smaller part when magnified or reduced to the same size.] -*** Increasing {relatedTag=Decreasing}[Becoming greater in size, amount, or degree.] -*** Random {relatedTag=Deterministic,relatedTag=Stochastic}[Governed by or depending on chance. Lacking any definite plan or order or purpose.] -*** Repetitive [A recurring action that is often non-purposeful.] -*** Stochastic {relatedTag=Deterministic,relatedTag=Random}[Uses a random probability distribution or pattern that may be analysed statistically but may not be predicted precisely to determine future states.] -*** Varying [Differing in size, amount, degree, or nature.] -* Environmental-property [Relating to or arising from the surroundings of an agent.] -** Indoors [Located inside a building or enclosure.] -** Outdoors [Any area outside a building or shelter.] -** Real-world [Located in a place that exists in real space and time under realistic conditions.] -** Virtual-world [Using technology that creates immersive, computer-generated experiences that a person can interact with and navigate through. The digital content is generally delivered to the user through some type of headset and responds to changes in head position or through interaction with other types of sensors. Existing in a virtual setting such as a simulation or game environment.] -** Augmented-reality [Using technology that enhances real-world experiences with computer-derived digital overlays to change some aspects of perception of the natural environment. The digital content is shown to the user through a smart device or glasses and responds to changes in the environment.] -** Motion-platform [A mechanism that creates the feelings of being in a real motion environment.] -** Urban [Relating to, located in, or characteristic of a city or densely populated area.] -** Rural [Of or pertaining to the country as opposed to the city.] -** Terrain [Characterization of the physical features of a tract of land.] -*** Composite-terrain [Tracts of land characterized by a mixure of physical features.] -*** Dirt-terrain [Tracts of land characterized by a soil surface and lack of vegetation.] -*** Grassy-terrain [Tracts of land covered by grass.] -*** Gravel-terrain [Tracts of land covered by a surface consisting a loose aggregation of small water-worn or pounded stones.] -*** Leaf-covered-terrain [Tracts of land covered by leaves and composited organic material.] -*** Muddy-terrain [Tracts of land covered by a liquid or semi-liquid mixture of water and some combination of soil, silt, and clay.] -*** Paved-terrain [Tracts of land covered with concrete, asphalt, stones, or bricks.] -*** Rocky-terrain [Tracts of land consisting or full of rock or rocks.] -*** Sloped-terrain [Tracts of land arranged in a sloping or inclined position.] -*** Uneven-terrain [Tracts of land that are not level, smooth, or regular.] -* Informational-property{extensionAllowed}[Something that pertains to a task.] -** Description {requireChild} [An explanation of what the tag group it is in means. If the description is at the top-level of an event string, the description applies to the event.] -*** # {takesValue, valueClass=textClass} -** ID {requireChild} [An alphanumeric name that identifies either a unique object or a unique class of objects. Here the object or class may be an idea, physical countable object (or class), or physical uncountable substance (or class).] -*** # {takesValue, valueClass=textClass} -** Label {requireChild} [A string of 20 or fewer characters identifying something. Labels usually refer to general classes of things while IDs refer to specific instances. A term that is associated with some entity. A brief description given for purposes of identification. An identifying or descriptive marker that is attached to an object.] -*** # {takesValue, valueClass=nameClass} -** Metadata [Data about data. Information that describes another set of data.] -*** CogAtlas [The Cognitive Atlas ID number of something.] -**** # {takesValue} -*** CogPo [The CogPO ID number of something.] -**** # {takesValue} -*** Creation-date {requireChild}[The date on which data creation of this element began.] -**** # {takesValue, valueClass=dateTimeClass} -*** Experimental-note [A brief written record about the experiment.] -**** # {takesValue, valueClass=textClass} -*** Library-name [Official name of a HED library.] -**** # {takesValue, valueClass=nameClass} -*** OBO-identifier [The identifier of a term in some Open Biology Ontology (OBO) ontology.] -**** # {takesValue, valueClass=nameClass} -*** Pathname [The specification of a node (file or directory) in a hierarchical file system, usually specified by listing the nodes top-down.] -**** # {takesValue} -*** Subject-identifier [A sequence of characters used to identify, name, or characterize a trial or study subject.] -**** # {takesValue} -*** Version-identifier [An alphanumeric character string that identifies a form or variant of a type or original.] -**** # {takesValue}[Usually is a semantic version.] -** Parameter [Something user-defined for this experiment.] -*** Parameter-label [The name of the parameter.] -**** # {takesValue, valueClass=nameClass} -*** Parameter-value [The value of the parameter.] -**** # {takesValue, valueClass=textClass} -* Organizational-property [Relating to an organization or the action of organizing something.] -** Collection [A tag designating a grouping of items such as in a set or list.] -*** # {takesValue, valueClass=nameClass}[Name of the collection.] -** Condition-variable [An aspect of the experiment or task that is to be varied during the experiment. Task-conditions are sometimes called independent variables or contrasts.] -*** # {takesValue, valueClass=nameClass}[Name of the condition variable.] -** Control-variable [An aspect of the experiment that is fixed throughout the study and usually is explicitly controlled.] -*** # {takesValue, valueClass=nameClass}[Name of the control variable.] -** Def {requireChild} [A HED-specific utility tag used with a defined name to represent the tags associated with that definition.] -*** # {takesValue, valueClass=nameClass}[Name of the definition.] -** Def-expand {requireChild, tagGroup} [A HED specific utility tag that is grouped with an expanded definition. The child value of the Def-expand is the name of the expanded definition.] -*** # {takesValue, valueClass=nameClass} -** Definition {requireChild, topLevelTagGroup}[A HED-specific utility tag whose child value is the name of the concept and the tag group associated with the tag is an English language explanation of a concept.] -*** # {takesValue, valueClass=nameClass}[Name of the definition.] -** Event-context {topLevelTagGroup, unique}[A special HED tag inserted as part of a top-level tag group to contain information about the interrelated conditions under which the event occurs. The event context includes information about other events that are ongoing when this event happens.] -** Event-stream [A special HED tag indicating that this event is a member of an ordered succession of events.] -*** # {takesValue, valueClass=nameClass}[Name of the event stream.] -** Experimental-intertrial [A tag used to indicate a part of the experiment between trials usually where nothing is happening.] -*** # {takesValue, valueClass=nameClass}[Optional label for the intertrial block.] -** Experimental-trial [Designates a run or execution of an activity, for example, one execution of a script. A tag used to indicate a particular organizational part in the experimental design often containing a stimulus-response pair or stimulus-response-feedback triad.] -*** # {takesValue, valueClass=nameClass}[Optional label for the trial (often a numerical string).] -** Indicator-variable [An aspect of the experiment or task that is measured as task conditions are varied during the experiment. Experiment indicators are sometimes called dependent variables.] -*** # {takesValue, valueClass=nameClass}[Name of the indicator variable.] -** Recording [A tag designating the data recording. Recording tags are usually have temporal scope which is the entire recording.] -*** # {takesValue, valueClass=nameClass}[Optional label for the recording.] -** Task [An assigned piece of work, usually with a time allotment. A tag used to indicate a linkage the structured activities performed as part of the experiment.] -*** # {takesValue, valueClass=nameClass}[Optional label for the task block.] -** Time-block [A tag used to indicate a contiguous time block in the experiment during which something is fixed or noted.] -*** # {takesValue, valueClass=nameClass}[Optional label for the task block.] -* Sensory-property [Relating to sensation or the physical senses.] -** Sensory-attribute [A sensory characteristic associated with another entity.] -*** Auditory-attribute [Pertaining to the sense of hearing.] -**** Loudness [Perceived intensity of a sound.] -***** # {takesValue, valueClass=numericClass, valueClass=nameClass} -**** Pitch [A perceptual property that allows the user to order sounds on a frequency scale.] -***** # {takesValue, valueClass=numericClass, unitClass=frequencyUnits} -**** Sound-envelope [Description of how a sound changes over time.] -***** Sound-envelope-attack [The time taken for initial run-up of level from nil to peak usually beginning when the key on a musical instrument is pressed.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Sound-envelope-decay [The time taken for the subsequent run down from the attack level to the designated sustain level.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Sound-envelope-release [The time taken for the level to decay from the sustain level to zero after the key is released.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -***** Sound-envelope-sustain [The time taken for the main sequence of the sound duration, until the key is released.] -****** # {takesValue, valueClass=numericClass, unitClass=timeUnits} -**** Timbre [The perceived sound quality of a singing voice or musical instrument.] -***** # {takesValue, valueClass=nameClass} -**** Sound-volume [The sound pressure level (SPL) usually the ratio to a reference signal estimated as the lower bound of hearing.] -***** # {takesValue, valueClass=numericClass, unitClass=intensityUnits} -*** Gustatory-attribute [Pertaining to the sense of taste.] -**** Bitter [Having a sharp, pungent taste.] -**** Salty [Tasting of or like salt.] -**** Savory [Belonging to a taste that is salty or spicy rather than sweet.] -**** Sour [Having a sharp, acidic taste.] -**** Sweet [Having or resembling the taste of sugar.] -*** Olfactory-attribute [Having a smell.] -*** Somatic-attribute [Pertaining to the feelings in the body or of the nervous system.] -**** Pain [The sensation of discomfort, distress, or agony, resulting from the stimulation of specialized nerve endings.] -**** Stress [The negative mental, emotional, and physical reactions that occur when environmental stressors are perceived as exceeding the adaptive capacities of the individual.] -*** Tactile-attribute [Pertaining to the sense of touch.] -**** Tactile-pressure [Having a feeling of heaviness.] -**** Tactile-temperature [Having a feeling of hotness or coldness.] -**** Tactile-texture [Having a feeling of roughness.] -**** Tactile-vibration [Having a feeling of mechanical oscillation.] -*** Vestibular-attribute [Pertaining to the sense of balance or body position.] -*** Visual-attribute [Pertaining to the sense of sight.] -**** Color [The appearance of objects (or light sources) described in terms of perception of their hue and lightness (or brightness) and saturation.] -***** CSS-color [One of 140 colors supported by all browsers. For more details such as the color RGB or HEX values, check: https://www.w3schools.com/colors/colors_groups.asp.] -****** Blue-color [CSS color group.] -******* CadetBlue [CSS-color 0x5F9EA0.] -******* SteelBlue [CSS-color 0x4682B4.] -******* LightSteelBlue [CSS-color 0xB0C4DE.] -******* LightBlue [CSS-color 0xADD8E6.] -******* PowderBlue [CSS-color 0xB0E0E6.] -******* LightSkyBlue [CSS-color 0x87CEFA.] -******* SkyBlue [CSS-color 0x87CEEB.] -******* CornflowerBlue [CSS-color 0x6495ED.] -******* DeepSkyBlue [CSS-color 0x00BFFF.] -******* DodgerBlue [CSS-color 0x1E90FF.] -******* RoyalBlue [CSS-color 0x4169E1.] -******* Blue [CSS-color 0x0000FF.] -******* MediumBlue [CSS-color 0x0000CD.] -******* DarkBlue [CSS-color 0x00008B.] -******* Navy [CSS-color 0x000080.] -******* MidnightBlue [CSS-color 0x191970.] -****** Brown-color [CSS color group.] -******* Cornsilk [CSS-color 0xFFF8DC.] -******* BlanchedAlmond [CSS-color 0xFFEBCD.] -******* Bisque [CSS-color 0xFFE4C4.] -******* NavajoWhite [CSS-color 0xFFDEAD.] -******* Wheat [CSS-color 0xF5DEB3.] -******* BurlyWood [CSS-color 0xDEB887.] -******* Tan [CSS-color 0xD2B48C.] -******* RosyBrown [CSS-color 0xBC8F8F.] -******* SandyBrown [CSS-color 0xF4A460.] -******* GoldenRod [CSS-color 0xDAA520.] -******* DarkGoldenRod [CSS-color 0xB8860B.] -******* Peru [CSS-color 0xCD853F.] -******* Chocolate [CSS-color 0xD2691E.] -******* Olive [CSS-color 0x808000.] -******* SaddleBrown [CSS-color 0x8B4513.] -******* Sienna [CSS-color 0xA0522D.] -******* Brown [CSS-color 0xA52A2A.] -******* Maroon [CSS-color 0x800000.] -****** Cyan-color [CSS color group.] -******* Aqua [CSS-color 0x00FFFF.] -******* Cyan [CSS-color 0x00FFFF.] -******* LightCyan [CSS-color 0xE0FFFF.] -******* PaleTurquoise [CSS-color 0xAFEEEE.] -******* Aquamarine [CSS-color 0x7FFFD4.] -******* Turquoise [CSS-color 0x40E0D0.] -******* MediumTurquoise [CSS-color 0x48D1CC.] -******* DarkTurquoise [CSS-color 0x00CED1.] -****** Green-color [CSS color group.] -******* GreenYellow [CSS-color 0xADFF2F.] -******* Chartreuse [CSS-color 0x7FFF00.] -******* LawnGreen [CSS-color 0x7CFC00.] -******* Lime [CSS-color 0x00FF00.] -******* LimeGreen [CSS-color 0x32CD32.] -******* PaleGreen [CSS-color 0x98FB98.] -******* LightGreen [CSS-color 0x90EE90.] -******* MediumSpringGreen [CSS-color 0x00FA9A.] -******* SpringGreen [CSS-color 0x00FF7F.] -******* MediumSeaGreen [CSS-color 0x3CB371.] -******* SeaGreen [CSS-color 0x2E8B57.] -******* ForestGreen [CSS-color 0x228B22.] -******* Green [CSS-color 0x008000.] -******* DarkGreen [CSS-color 0x006400.] -******* YellowGreen [CSS-color 0x9ACD32.] -******* OliveDrab [CSS-color 0x6B8E23.] -******* DarkOliveGreen [CSS-color 0x556B2F.] -******* MediumAquaMarine [CSS-color 0x66CDAA.] -******* DarkSeaGreen [CSS-color 0x8FBC8F.] -******* LightSeaGreen [CSS-color 0x20B2AA.] -******* DarkCyan [CSS-color 0x008B8B.] -******* Teal [CSS-color 0x008080.] -****** Gray-color [CSS color group.] -******* Gainsboro [CSS-color 0xDCDCDC.] -******* LightGray [CSS-color 0xD3D3D3.] -******* Silver [CSS-color 0xC0C0C0.] -******* DarkGray [CSS-color 0xA9A9A9.] -******* DimGray [CSS-color 0x696969.] -******* Gray [CSS-color 0x808080.] -******* LightSlateGray [CSS-color 0x778899.] -******* SlateGray [CSS-color 0x708090.] -******* DarkSlateGray [CSS-color 0x2F4F4F.] -******* Black [CSS-color 0x000000.] -****** Orange-color [CSS color group.] -******* Orange [CSS-color 0xFFA500.] -******* DarkOrange [CSS-color 0xFF8C00.] -******* Coral [CSS-color 0xFF7F50.] -******* Tomato [CSS-color 0xFF6347.] -******* OrangeRed [CSS-color 0xFF4500.] -****** Pink-color [CSS color group.] -******* Pink [CSS-color 0xFFC0CB.] -******* LightPink [CSS-color 0xFFB6C1.] -******* HotPink [CSS-color 0xFF69B4.] -******* DeepPink [CSS-color 0xFF1493.] -******* PaleVioletRed [CSS-color 0xDB7093.] -******* MediumVioletRed [CSS-color 0xC71585.] -****** Purple-color [CSS color group.] -******* Lavender [CSS-color 0xE6E6FA.] -******* Thistle [CSS-color 0xD8BFD8.] -******* Plum [CSS-color 0xDDA0DD.] -******* Orchid [CSS-color 0xDA70D6.] -******* Violet [CSS-color 0xEE82EE.] -******* Fuchsia [CSS-color 0xFF00FF.] -******* Magenta [CSS-color 0xFF00FF.] -******* MediumOrchid [CSS-color 0xBA55D3.] -******* DarkOrchid [CSS-color 0x9932CC.] -******* DarkViolet [CSS-color 0x9400D3.] -******* BlueViolet [CSS-color 0x8A2BE2.] -******* DarkMagenta [CSS-color 0x8B008B.] -******* Purple [CSS-color 0x800080.] -******* MediumPurple [CSS-color 0x9370DB.] -******* MediumSlateBlue [CSS-color 0x7B68EE.] -******* SlateBlue [CSS-color 0x6A5ACD.] -******* DarkSlateBlue [CSS-color 0x483D8B.] -******* RebeccaPurple [CSS-color 0x663399.] -******* Indigo [CSS-color 0x4B0082.] -****** Red-color [CSS color group.] -******* LightSalmon [CSS-color 0xFFA07A.] -******* Salmon [CSS-color 0xFA8072.] -******* DarkSalmon [CSS-color 0xE9967A.] -******* LightCoral [CSS-color 0xF08080.] -******* IndianRed [CSS-color 0xCD5C5C.] -******* Crimson [CSS-color 0xDC143C.] -******* Red [CSS-color 0xFF0000.] -******* FireBrick [CSS-color 0xB22222.] -******* DarkRed [CSS-color 0x8B0000.] -****** Yellow-color [CSS color group.] -******* Gold [CSS-color 0xFFD700.] -******* Yellow [CSS-color 0xFFFF00.] -******* LightYellow [CSS-color 0xFFFFE0.] -******* LemonChiffon [CSS-color 0xFFFACD.] -******* LightGoldenRodYellow [CSS-color 0xFAFAD2.] -******* PapayaWhip [CSS-color 0xFFEFD5.] -******* Moccasin [CSS-color 0xFFE4B5.] -******* PeachPuff [CSS-color 0xFFDAB9.] -******* PaleGoldenRod [CSS-color 0xEEE8AA.] -******* Khaki [CSS-color 0xF0E68C.] -******* DarkKhaki [CSS-color 0xBDB76B.] -****** White-color [CSS color group.] -******* White [CSS-color 0xFFFFFF.] -******* Snow [CSS-color 0xFFFAFA.] -******* HoneyDew [CSS-color 0xF0FFF0.] -******* MintCream [CSS-color 0xF5FFFA.] -******* Azure [CSS-color 0xF0FFFF.] -******* AliceBlue [CSS-color 0xF0F8FF.] -******* GhostWhite [CSS-color 0xF8F8FF.] -******* WhiteSmoke [CSS-color 0xF5F5F5.] -******* SeaShell [CSS-color 0xFFF5EE.] -******* Beige [CSS-color 0xF5F5DC.] -******* OldLace [CSS-color 0xFDF5E6.] -******* FloralWhite [CSS-color 0xFFFAF0.] -******* Ivory [CSS-color 0xFFFFF0.] -******* AntiqueWhite [CSS-color 0xFAEBD7.] -******* Linen [CSS-color 0xFAF0E6.] -******* LavenderBlush [CSS-color 0xFFF0F5.] -******* MistyRose [CSS-color 0xFFE4E1.] -***** Color-shade [A slight degree of difference between colors, especially with regard to how light or dark it is or as distinguished from one nearly like it.] -****** Dark-shade [A color tone not reflecting much light.] -****** Light-shade [A color tone reflecting more light.] -***** Grayscale [Using a color map composed of shades of gray, varying from black at the weakest intensity to white at the strongest.] -****** # {takesValue, valueClass=numericClass} [White intensity between 0 and 1.] -***** HSV-color [A color representation that models how colors appear under light.] -****** Hue [Attribute of a visual sensation according to which an area appears to be similar to one of the perceived colors.] -******* # {takesValue, valueClass=numericClass} [Angular value between 0 and 360.] -****** Saturation [Colorfulness of a stimulus relative to its own brightness.] -******* # {takesValue, valueClass=numericClass} [B value of RGB between 0 and 1.] -****** HSV-value [An attribute of a visual sensation according to which an area appears to emit more or less light.] -******* # {takesValue, valueClass=numericClass} -***** RGB-color [A color from the RGB schema.] -****** RGB-red [The red component.] -******* # {takesValue, valueClass=numericClass} [R value of RGB between 0 and 1.] -****** RGB-blue [The blue component.] -******* # {takesValue, valueClass=numericClass} [B value of RGB between 0 and 1.] -****** RGB-green [The green component.] -******* # {takesValue, valueClass=numericClass} [G value of RGB between 0 and 1.] -**** Luminance [A quality that exists by virtue of the luminous intensity per unit area projected in a given direction.] -**** Opacity [A measure of impenetrability to light.] -** Sensory-presentation [The entity has a sensory manifestation.] -*** Auditory-presentation [The sense of hearing is used in the presentation to the user.] -**** Loudspeaker-separation {suggestedTag=Distance}[The distance between two loudspeakers. Grouped with the Distance tag.] -**** Monophonic [Relating to sound transmission, recording, or reproduction involving a single transmission path.] -**** Silent [The absence of ambient audible sound or the state of having ceased to produce sounds.] -**** Stereophonic [Relating to, or constituting sound reproduction involving the use of separated microphones and two transmission channels to achieve the sound separation of a live hearing.] -*** Gustatory-presentation [The sense of taste used in the presentation to the user.] -*** Olfactory-presentation [The sense of smell used in the presentation to the user.] -*** Somatic-presentation [The nervous system is used in the presentation to the user.] -*** Tactile-presentation [The sense of touch used in the presentation to the user.] -*** Vestibular-presentation [The sense balance used in the presentation to the user.] -*** Visual-presentation [The sense of sight used in the presentation to the user.] -**** 2D-view [A view showing only two dimensions.] -**** 3D-view [A view showing three dimensions.] -**** Background-view [Parts of the view that are farthest from the viewer and usually the not part of the visual focus.] -**** Bistable-view [Something having two stable visual forms that have two distinguishable stable forms as in optical illusions.] -**** Foreground-view [Parts of the view that are closest to the viewer and usually the most important part of the visual focus.] -**** Foveal-view [Visual presentation directly on the fovea. A view projected on the small depression in the retina containing only cones and where vision is most acute.] -**** Map-view [A diagrammatic representation of an area of land or sea showing physical features, cities, roads.] -***** Aerial-view [Elevated view of an object from above, with a perspective as though the observer were a bird.] -***** Satellite-view [A representation as captured by technology such as a satellite.] -***** Street-view [A 360-degrees panoramic view from a position on the ground.] -**** Peripheral-view [Indirect vision as it occurs outside the point of fixation.] -* Task-property {extensionAllowed}[Something that pertains to a task.] -** Task-attentional-demand [Strategy for allocating attention toward goal-relevant information.] -*** Bottom-up-attention {relatedTag=Top-down-attention}[Attentional guidance purely by externally driven factors to stimuli that are salient because of their inherent properties relative to the background. Sometimes this is referred to as stimulus driven.] -*** Covert-attention {relatedTag=Overt-attention}[Paying attention without moving the eyes.] -*** Divided-attention {relatedTag=Focused-attention}[Integrating parallel multiple stimuli. Behavior involving responding simultaneously to multiple tasks or multiple task demands.] -*** Focused-attention {relatedTag=Divided-attention}[Responding discretely to specific visual, auditory, or tactile stimuli.] -*** Orienting-attention [Directing attention to a target stimulus.] -*** Overt-attention {relatedTag=Covert-attention}[Selectively processing one location over others by moving the eyes to point at that location.] -*** Selective-attention [Maintaining a behavioral or cognitive set in the face of distracting or competing stimuli. Ability to pay attention to a limited array of all available sensory information.] -*** Sustained-attention [Maintaining a consistent behavioral response during continuous and repetitive activity.] -*** Switched-attention [Having to switch attention between two or more modalities of presentation.] -*** Top-down-attention {relatedTag=Bottom-up-attention}[Voluntary allocation of attention to certain features. Sometimes this is referred to goal-oriented attention.] -** Task-effect-evidence [The evidence supporting the conclusion that the event had the specified effect.] -*** Computational-evidence [A type of evidence in which data are produced, and/or generated, and/or analyzed on a computer.] -*** External-evidence [A phenomenon that follows and is caused by some previous phenomenon.] -*** Intended-effect [A phenomenon that is intended to follow and be caused by some previous phenomenon.] -*** Behavioral-evidence [An indication or conclusion based on the behavior of an agent.] -** Task-event-role [The purpose of an event with respect to the task.] -*** Experimental-stimulus [Part of something designed to elicit a response in the experiment.] -*** Incidental [A sensory or other type of event that is unrelated to the task or experiment.] -*** Instructional [Usually associated with a sensory event intended to give instructions to the participant about the task or behavior.] -*** Mishap [Unplanned disruption such as an equipment or experiment control abnormality or experimenter error.] -*** Participant-response [Something related to a participant actions in performing the task.] -*** Task-activity [Something that is part of the overall task or is necessary to the overall experiment but is not directly part of a stimulus-response cycle. Examples would be taking a survey or provided providing a silva sample.] -*** Warning [Something that should warn the participant that the parameters of the task have been or are about to be exceeded such as a warning message about getting too close to the shoulder of the road in a driving task.] -** Task-action-type [How an agent action should be interpreted in terms of the task specification.] -*** Appropriate-action {relatedTag=Inappropriate-action}[An action suitable or proper in the circumstances.] -*** Correct-action {relatedTag=Incorrect-action, relatedTag=Indeterminate-action}[An action that was a correct response in the context of the task.] -*** Correction [An action offering an improvement to replace a mistake or error.] -*** Done-indication {relatedTag=Ready-indication}[An action that indicates that the participant has completed this step in the task.] -*** Incorrect-action {relatedTag=Correct-action, relatedTag=Indeterminate-action}[An action considered wrong or incorrect in the context of the task.] -*** Imagined-action [Form a mental image or concept of something. This is used to identity something that only happened in the imagination of the participant as in imagined movements in motor imagery paradigms.] -*** Inappropriate-action {relatedTag=Appropriate-action}[An action not in keeping with what is correct or proper for the task.] -*** Indeterminate-action {relatedTag=Correct-action,relatedTag=Incorrect-action, relatedTag=Miss, relatedTag=Near-miss}[An action that cannot be distinguished between two or more possibibities in the current context. This tag might be applied when an outside evaluator or a classification algorithm cannot determine a definitive result.] -*** Omitted-action [An expected response was skipped.] -*** Miss {relatedTag=Near-miss}[An action considered to be a failure in the context of the task. For example, if the agent is supposed to try to hit a target and misses.] -*** Near-miss {relatedTag=Miss}[An action barely satisfied the requirements of the task. In a driving experiment for example this could pertain to a narrowly avoided collision or other accident.] -*** Ready-indication {relatedTag=Done-indication}[An action that indicates that the participant is ready to perform the next step in the task.] -** Task-relationship [Specifying organizational importance of sub-tasks.] -*** Background-subtask [A part of the task which should be performed in the background as for example inhibiting blinks due to instruction while performing the primary task.] -*** Primary-subtask [A part of the task which should be the primary focus of the participant.] -** Task-stimulus-role [The role the stimulus plays in the task.] -*** Cue [A signal for an action, a pattern of stimuli indicating a particular response.] -*** Distractor [A person or thing that distracts or a plausible but incorrect option in a multiple-choice question. In pyschological studies this is sometimes referred to as a foil.] -*** Expected {relatedTag=Unexpected, suggestedTag=Target}[Considered likely, probable or anticipated. Something of low information value as in frequent non-targets in an RSVP paradigm.] -*** Extraneous [Irrelevant or unrelated to the subject being dealt with.] -*** Feedback [An evaluative response to an inquiry, process, event, or activity.] -*** Go-signal {relatedTag=Stop-signal}[An indicator to proceed with a planned action.] -*** Meaningful [Conveying significant or relevant information.] -*** Newly-learned [Representing recently acquired information or understanding.] -*** Non-informative [Something that is not useful in forming an opinion or judging an outcome.] -*** Non-target {relatedTag=Target}[Something other than that done or looked for. Also tag Expected if the Non-target is frequent.] -*** Not-meaningful [Not having a serious, important, or useful quality or purpose.] -*** Novel [Having no previous example or precedent or parallel.] -*** Oddball {relatedTag=Unexpected, suggestedTag=Target}[Something unusual, or infrequent.] -*** Planned {relatedTag=Unplanned}[Something that was decided on or arranged in advance.] -*** Penalty [A disadvantage, loss, or hardship due to some action.] -*** Priming [An implicit memory effect in which exposure to a stimulus influences response to a later stimulus.] -*** Query [A sentence of inquiry that asks for a reply.] -*** Reward [A positive reinforcement for a desired action, behavior or response.] -*** Stop-signal {relatedTag=Go-signal}[An indicator that the agent should stop the current activity.] -*** Target [Something fixed as a goal, destination, or point of examination.] -*** Threat [An indicator that signifies hostility and predicts an increased probability of attack.] -*** Timed [Something planned or scheduled to be done at a particular time or lasting for a specified amount of time.] -*** Unexpected {relatedTag=Expected}[Something that is not anticipated.] -*** Unplanned {relatedTag=Planned}[Something that has not been planned as part of the task.] - -'''Relation''' {extensionAllowed}[Concerns the way in which two or more people or things are connected.] -* Comparative-relation [Something considered in comparison to something else. The first entity is the focus.] -** Approximately-equal-to [(A, (Approximately-equal-to, B)) indicates that A and B have almost the same value. Here A and B could refer to sizes, orders, positions or other quantities.] -** Less-than [(A, (Less-than, B)) indicates that A is smaller than B. Here A and B could refer to sizes, orders, positions or other quantities.] -** Less-than-or-equal-to [(A, (Less-than-or-equal-to, B)) indicates that the relative size or order of A is smaller than or equal to B.] -** Greater-than [(A, (Greater-than, B)) indicates that the relative size or order of A is bigger than that of B.] -** Greater-than-or-equal-to [(A, (Greater-than-or-equal-to, B)) indicates that the relative size or order of A is bigger than or the same as that of B.] -** Equal-to [(A, (Equal-to, B)) indicates that the size or order of A is the same as that of B.] -** Not-equal-to [(A, (Not-equal-to, B)) indicates that the size or order of A is not the same as that of B.] -* Connective-relation [Indicates two entities are related in some way. The first entity is the focus.] -** Belongs-to [(A, (Belongs-to, B)) indicates that A is a member of B.] -** Connected-to [(A, (Connected-to, B)) indicates that A is related to B in some respect, usually through a direct link.] -** Contained-in [(A, (Contained-in, B)) indicates that A is completely inside of B.] -** Described-by [(A, (Described-by, B)) indicates that B provides information about A.] -** From-to [(A, (From-to, B)) indicates a directional relation from A to B. A is considered the source.] -** Group-of [(A, (Group-of, B)) indicates A is a group of items of type B.] -** Implied-by [(A, (Implied-by, B)) indicates B is suggested by A.] -** Includes [(A, (Includes, B)) indicates that A has B as a member or part.] -** Interacts-with [(A, (Interacts-with, B)) indicates A and B interact, possibly reciprocally.] -** Member-of [(A, (Member-of, B)) indicates A is a member of group B.] -** Part-of [(A, (Part-of, B)) indicates A is a part of the whole B.] -** Performed-by [(A, (Performed-by, B)) indicates that the action or procedure A was carried out by agent B.] -** Performed-using [(A, (Performed-using, B)) indicates that the action or procedure A was accomplished using B.] -** Related-to [(A, (Related-to, B)) indicates A has some relationship to B.] -** Unrelated-to [(A, (Unrelated-to, B)) indicates that A is not related to B. For example, A is not related to Task.] -* Directional-relation [A relationship indicating direction of change of one entity relative to another. The first entity is the focus.] -** Away-from [(A, (Away-from, B)) indicates that A is going or has moved away from B. The meaning depends on A and B.] -** Towards [(A, (Towards, B)) indicates that A is going to or has moved to B. The meaning depends on A and B.] -* Logical-relation [Indicating a logical relationship between entities. The first entity is usually the focus.] -** And [(A, (And, B)) means A and B are both in effect.] -** Or [(A, (Or, B)) means at least one of A and B are in effect.] -* Spatial-relation [Indicating a relationship about position between entities.] -** Above [(A, (Above, B)) means A is in a place or position that is higher than B.] -** Across-from [(A, (Across-from, B)) means A is on the opposite side of something from B.] -** Adjacent-to [(A, (Adjacent-to, B)) indicates that A is next to B in time or space.] -** Ahead-of [(A, (Ahead-of, B)) indicates that A is further forward in time or space in B.] -** Around [(A, (Around, B)) means A is in or near the present place or situation of B.] -** Behind [(A, (Behind, B)) means A is at or to the far side of B, typically so as to be hidden by it.] -** Below [(A, (Below, B)) means A is in a place or position that is lower than the position of B.] -** Between [(A, (Between, (B, C))) means A is in the space or interval separating B and C.] -** Bilateral-to [(A, (Bilateral, B)) means A is on both sides of B or affects both sides of B.] -** Bottom-edge-of {relatedTag=Left-edge-of,relatedTag=Right-edge-of,relatedTag=Top-edge-of}[(A, (Bottom-edge-of, B)) means A is on the bottom most part or or near the boundary of B.] -** Boundary-of [(A, (Boundary-of, B)) means A is on or part of the edge or boundary of B.] -** Center-of [(A, (Center-of, B)) means A is at a point or or in an area that is approximately central within B.] -** Close-to [(A, (Close-to, B)) means A is at a small distance from or is located near in space to B.] -** Far-from [(A, (Far-from, B)) means A is at a large distance from or is not located near in space to B.] -** In-front-of [(A, (In-front-of, B)) means A is in a position just ahead or at the front part of B, potentially partially blocking B from view.] -** Left-edge-of {relatedTag=Bottom-edge-of,relatedTag=Right-edge-of,relatedTag=Top-edge-of}[(A, (Left-edge-of, B)) means A is located on the left side of B on or near the boundary of B.] -** Left-side-of {relatedTag=Right-side-of}[(A, (Left-side-of, B)) means A is located on the left side of B usually as part of B.] -** Lower-center-of {relatedTag=Center-of,relatedTag=Lower-left-of,relatedTag=Lower-right-of,relatedTag=Upper-center-of,relatedTag=Upper-right-of}[(A, (Lower-center-of, B)) means A is situated on the lower center part of B (due south). This relation is often used to specify qualitative information about screen position.] -** Lower-left-of {relatedTag=Center-of,relatedTag=Lower-center-of,relatedTag=Lower-right-of,relatedTag=Upper-center-of,relatedTag=Upper-left-of,relatedTag=Upper-right-of}[(A, (Lower-left-of, B)) means A is situated on the lower left part of B. This relation is often used to specify qualitative information about screen position.] -** Lower-right-of {relatedTag=Center-of,relatedTag=Lower-center-of,relatedTag=Lower-left-of,relatedTag=Upper-left-of,relatedTag=Upper-center-of,relatedTag=Upper-left-of,relatedTag=Lower-right-of}[(A, (Lower-right-of, B)) means A is situated on the lower right part of B. This relation is often used to specify qualitative information about screen position.] -** Outside-of [(A, (Outside-of, B)) means A is located in the space around but not including B.] -** Over [(A, (Over, B)) means A above is above B so as to cover or protect or A extends over the a general area as from a from a vantage point.] -** Right-edge-of {relatedTag=Bottom-edge-of,relatedTag=Left-edge-of,relatedTag=Top-edge-of}[(A, (Right-edge-of, B)) means A is located on the right side of B on or near the boundary of B.] -** Right-side-of {relatedTag=Left-side-of}[(A, (Right-side-of, B)) means A is located on the right side of B usually as part of B.] -** To-left-of [(A, (To-left-of, B)) means A is located on or directed toward the side to the west of B when B is facing north. This term is used when A is not part of B.] -** To-right-of [(A, (To-right-of, B)) means A is located on or directed toward the side to the east of B when B is facing north. This term is used when A is not part of B.] -** Top-edge-of {relatedTag=Left-edge-of,relatedTag=Right-edge-of,relatedTag=Bottom-edge-of}[(A, (Top-edge-of, B)) means A is on the uppermost part or or near the boundary of B.] -** Top-of [(A, (Top-of, B)) means A is on the uppermost part, side, or surface of B.] -** Upper-center-of {relatedTag=Center-of,relatedTag=Lower-center-of,relatedTag=Lower-left-of,relatedTag=Lower-right-of,relatedTag=Upper-center-of,relatedTag=Upper-right-of}[(A, (Upper-center-of, B)) means A is situated on the upper center part of B (due north). This relation is often used to specify qualitative information about screen position.] -** Upper-left-of {relatedTag=Center-of,relatedTag=Lower-center-of,relatedTag=Lower-left-of,relatedTag=Lower-right-of,relatedTag=Upper-center-of,relatedTag=Upper-right-of}[(A, (Upper-left-of, B)) means A is situated on the upper left part of B. This relation is often used to specify qualitative information about screen position.] -** Upper-right-of {relatedTag=Center-of,relatedTag=Lower-center-of,relatedTag=Lower-left-of,relatedTag=Upper-left-of,relatedTag=Upper-center-of,relatedTag=Lower-right-of}[(A, (Upper-right-of, B)) means A is situated on the upper right part of B. This relation is often used to specify qualitative information about screen position.] -** Underneath [(A, (Underneath, B)) means A is situated directly below and may be concealed by B.] -** Within [(A, (Within, B)) means A is on the inside of or contained in B.] -* Temporal-relation [A relationship that includes a temporal or time-based component.] -** After [(A, (After B)) means A happens at a time subsequent to a reference time related to B.] -** Asynchronous-with [(A, (Asynchronous-with, B)) means A happens at times not occurring at the same time or having the same period or phase as B.] -** Before [(A, (Before B)) means A happens at a time earlier in time or order than B.] -** During [(A, (During, B)) means A happens at some point in a given period of time in which B is ongoing.] -** Synchronous-with [(A, (Synchronous-with, B)) means A happens at occurs at the same time or rate as B.] -** Waiting-for [(A, (Waiting-for, B)) means A pauses for something to happen in B.] - -!# end schema - -'''Unit classes''' [Unit classes and the units for the nodes.] -* accelerationUnits {defaultUnits=m-per-s^2} -** m-per-s^2 {SIUnit, unitSymbol, conversionFactor=1.0} -* angleUnits {defaultUnits=radian} -** radian {SIUnit, conversionFactor=1.0} -** rad {SIUnit, unitSymbol, conversionFactor=1.0} -** degree {conversionFactor=0.0174533} -* areaUnits {defaultUnits=m^2} -** m^2 {SIUnit, unitSymbol, conversionFactor=1.0} -* currencyUnits {defaultUnits=$}[Units indicating the worth of something.] -** dollar {conversionFactor=1.0} -** $ {unitPrefix, unitSymbol, conversionFactor=1.0} -** euro -** point -* electricPotentialUnits {defaultUnits=uv} -** v {SIUnit, unitSymbol, conversionFactor=0.000001} -** Volt {SIUnit, conversionFactor=0.000001} -* frequencyUnits {defaultUnits=Hz} -** hertz {SIUnit, conversionFactor=1.0} -** Hz {SIUnit, unitSymbol, conversionFactor=1.0} -* intensityUnits {defaultUnits=dB} -** dB {unitSymbol, conversionFactor=1.0}[Intensity expressed as ratio to a threshold. May be used for sound intensity.] -** candela {SIUnit}[Units used to express light intensity.] -** cd {SIUnit, unitSymbol}[Units used to express light intensity.] -* jerkUnits {defaultUnits=m-per-s^3} -** m-per-s^3 {unitSymbol, conversionFactor=1.0} -* magneticFieldUnits {defaultUnits=fT}[Units used to magnetic field intensity.] -** tesla {SIUnit, conversionFactor=10^-15} -** T {SIUnit, unitSymbol, conversionFactor=10^-15} -* memorySizeUnits {defaultUnits=B} -** byte {SIUnit, conversionFactor=1.0} -** B {SIUnit, unitSymbol, conversionFactor=1.0} -* physicalLengthUnits {defaultUnits=m} -** foot {conversionFactor=0.3048} -** inch {conversionFactor=0.0254} -** metre {SIUnit, conversionFactor=1.0} -** m {SIUnit, unitSymbol, conversionFactor=1.0} -** mile {conversionFactor=1609.34} -* speedUnits {defaultUnits=m-per-s} -** m-per-s {SIUnit, unitSymbol, conversionFactor=1.0} -** mph {unitSymbol, conversionFactor=0.44704} -** kph {unitSymbol, conversionFactor=0.277778} -* temperatureUnits {defaultUnits=degree Celsius} -** degree Celsius {SIUnit, conversionFactor=1.0} -** oC {SIUnit, unitSymbol, conversionFactor=1.0} -* timeUnits {defaultUnits=s} -** second {SIUnit, conversionFactor=1.0} -** s {SIUnit, unitSymbol, conversionFactor=1.0} -** day {conversionFactor=86400} -** minute {conversionFactor=60} -** hour {conversionFactor=3600}[Should be in 24-hour format.] -* volumeUnits {defaultUnits=m^3} -** m^3 {SIUnit, unitSymbol, conversionFactor=1.0} -* weightUnits {defaultUnits=g} -** g {SIUnit, unitSymbol, conversionFactor=1.0} -** gram {SIUnit, conversionFactor=1.0} -** pound {conversionFactor=453.592} -** lb {conversionFactor=453.592} - - -'''Unit modifiers''' [Unit multiples and submultiples.] -* deca {SIUnitModifier, conversionFactor=10.0} [SI unit multiple representing 10^1.] -* da {SIUnitSymbolModifier, conversionFactor=10.0} [SI unit multiple representing 10^1.] -* hecto {SIUnitModifier, conversionFactor=100.0} [SI unit multiple representing 10^2.] -* h {SIUnitSymbolModifier, conversionFactor=100.0} [SI unit multiple representing 10^2.] -* kilo {SIUnitModifier, conversionFactor=1000.0} [SI unit multiple representing 10^3.] -* k {SIUnitSymbolModifier, conversionFactor=1000.0} [SI unit multiple representing 10^3.] -* mega {SIUnitModifier, conversionFactor=10^6} [SI unit multiple representing 10^6.] -* M {SIUnitSymbolModifier, conversionFactor=10^6} [SI unit multiple representing 10^6.] -* giga {SIUnitModifier, conversionFactor=10^9} [SI unit multiple representing 10^9.] -* G {SIUnitSymbolModifier, conversionFactor=10^9} [SI unit multiple representing 10^9.] -* tera {SIUnitModifier, conversionFactor=10^12} [SI unit multiple representing 10^12.] -* T {SIUnitSymbolModifier, conversionFactor=10^12} [SI unit multiple representing 10^12.] -* peta {SIUnitModifier, conversionFactor=10^15} [SI unit multiple representing 10^15.] -* P {SIUnitSymbolModifier, conversionFactor=10^15} [SI unit multiple representing 10^15.] -* exa {SIUnitModifier, conversionFactor=10^18} [SI unit multiple representing 10^18.] -* E {SIUnitSymbolModifier, conversionFactor=10^18} [SI unit multiple representing 10^18.] -* zetta {SIUnitModifier, conversionFactor=10^21} [SI unit multiple representing 10^21.] -* Z {SIUnitSymbolModifier, conversionFactor=10^21} [SI unit multiple representing 10^21.] -* yotta {SIUnitModifier, conversionFactor=10^24} [SI unit multiple representing 10^24.] -* Y {SIUnitSymbolModifier, conversionFactor=10^24} [SI unit multiple representing 10^24.] -* deci {SIUnitModifier, conversionFactor=0.1}[SI unit submultiple representing 10^-1.] -* d {SIUnitSymbolModifier, conversionFactor=0.1} [SI unit submultiple representing 10^-1.] -* centi {SIUnitModifier, conversionFactor=0.01} [SI unit submultiple representing 10^-2.] -* c {SIUnitSymbolModifier, conversionFactor=0.01} [SI unit submultiple representing 10^-2.] -* milli {SIUnitModifier, conversionFactor=0.001} [SI unit submultiple representing 10^-3.] -* m {SIUnitSymbolModifier, conversionFactor=0.001} [SI unit submultiple representing 10^-3.] -* micro {SIUnitModifier, conversionFactor=10^-6} [SI unit submultiple representing 10^-6.] -* u {SIUnitSymbolModifier, conversionFactor=10^-6} [SI unit submultiple representing 10^-6.] -* nano {SIUnitModifier, conversionFactor=10^-9} [SI unit submultiple representing 10^-9.] -* n {SIUnitSymbolModifier, conversionFactor=10^-9} [SI unit submultiple representing 10^-9.] -* pico {SIUnitModifier, conversionFactor=10^-12} [SI unit submultiple representing 10^-12.] -* p {SIUnitSymbolModifier, conversionFactor=10^-12} [SI unit submultiple representing 10^-12.] -* femto {SIUnitModifier, conversionFactor=10^-15} [SI unit submultiple representing 10^-15.] -* f {SIUnitSymbolModifier, conversionFactor=10^-15} [SI unit submultiple representing 10^-15.] -* atto {SIUnitModifier, conversionFactor=10^-18} [SI unit submultiple representing 10^-18.] -* a {SIUnitSymbolModifier, conversionFactor=10^-18} [SI unit submultiple representing 10^-18.] -* zepto {SIUnitModifier, conversionFactor=10^-21} [SI unit submultiple representing 10^-21.] -* z {SIUnitSymbolModifier, conversionFactor=10^-21} [SI unit submultiple representing 10^-21.] -* yocto {SIUnitModifier, conversionFactor=10^-24} [SI unit submultiple representing 10^-24.] -* y {SIUnitSymbolModifier, conversionFactor=10^-24} [SI unit submultiple representing 10^-24.] - - -'''Value classes''' [Specification of the rules for the values provided by users.] -* dateTimeClass {allowedCharacter=digits,allowedCharacter=T,allowedCharacter=-,allowedCharacter=:}[Date-times should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss. Any variation on the full form is allowed.] -* nameClass {allowedCharacter=letters,allowedCharacter=digits,allowedCharacter=_,allowedCharacter=-}[Value class designating values that have the characteristics of node names. The allowed characters are alphanumeric, hyphen, and underbar.] -* numericClass {allowedCharacter=digits,allowedCharacter=E,allowedCharacter=e,allowedCharacter=+,allowedCharacter=-,allowedCharacter=.}[Value must be a valid numerical value.] -* posixPath {allowedCharacter=digits,allowedCharacter=letters,allowedCharacter=/,allowedCharacter=:}[Posix path specification.] -* textClass {allowedCharacter=letters, allowedCharacter=digits, allowedCharacter=blank, allowedCharacter=+, allowedCharacter=-, allowedCharacter=:, allowedCharacter=;, allowedCharacter=., allowedCharacter=/, allowedCharacter=(, allowedCharacter=), allowedCharacter=?, allowedCharacter=*, allowedCharacter=%, allowedCharacter=$, allowedCharacter=@}[Value class designating values that have the characteristics of text such as in descriptions.] - - -'''Schema attributes''' [Allowed node, unit class or unit modifier attributes.] -* allowedCharacter {valueClassProperty}[A schema attribute of value classes specifying a special character that is allowed in expressing the value of a placeholder. Normally the allowed characters are listed individually. However, the word letters designates the upper and lower case alphabetic characters and the word digits designates the digits 0-9. The word blank designates the blank character.] -* conversionFactor {unitProperty, unitModifierProperty}[The multiplicative factor to multiply these units to convert to default units.] -* deprecated {boolProperty}[This tag is out of date and should no longer be used.] -* defaultUnits {unitClassProperty}[A schema attribute of unit classes specifying the default units to use if the placeholder has a unit class but the substituted value has no units.] -* extensionAllowed {boolProperty}[A schema attribute indicating that users can add unlimited levels of child nodes under this tag. This tag is propagated to child nodes with the exception of the hashtag placeholders.] -* recommended {boolProperty}[A schema attribute indicating that the event-level HED string should include this tag.] -* relatedTag [A schema attribute suggesting HED tags that are closely related to this tag. This attribute is used by tagging tools.] -* requireChild {boolProperty}[A schema attribute indicating that one of the node elements descendants must be included when using this tag.] -* required {boolProperty}[A schema attribute indicating that every event-level HED string should include this tag.] -* SIUnit {boolProperty, unitProperty}[A schema attribute indicating that this unit element is an SI unit and can be modified by multiple and submultiple names. Note that some units such as byte are designated as SI units although they are not part of the standard.] -* SIUnitModifier {boolProperty, unitModifierProperty}[A schema attribute indicating that this SI unit modifier represents a multiple or submultiple of a base unit rather than a unit symbol.] -* SIUnitSymbolModifier {boolProperty, unitModifierProperty}[A schema attribute indicating that this SI unit modifier represents a multiple or submultiple of a unit symbol rather than a base symbol.] -* suggestedTag [A schema attribute that indicates another tag that is often associated with this tag. This attribute is used by tagging tools to provide tagging suggestions.] -* tagGroup {boolProperty}[A schema attribute indicating the tag can only appear inside a tag group.] -* takesValue {boolProperty}[A schema attribute indicating the tag is a hashtag placeholder that is expected to be replaced with a user-defined value.] -* topLevelTagGroup {boolProperty}[A schema attribute indicating that this tag (or its descendants) can only appear in a top-level tag group. A tag group can have at most one tag with this attribute.] -* unique {boolProperty}[A schema attribute indicating that only one of this tag or its descendants can be used in the event-level HED string.] -* unitClass [A schema attribute specifying which unit class this value tag belongs to.] -* unitPrefix {boolProperty, unitProperty}[A schema attribute applied specifically to unit elements to designate that the unit indicator is a prefix (e.g., dollar sign in the currency units).] -* unitSymbol {boolProperty, unitProperty}[A schema attribute indicating this tag is an abbreviation or symbol representing a type of unit. Unit symbols represent both the singular and the plural and thus cannot be pluralized.] -* valueClass [A schema attribute specifying which value class this value tag belongs to.] - -'''Properties''' [Properties of the schema attributes themselves. These are used for schema handling and verification.] -* boolProperty [Indicates that the schema attribute represents something that is either true or false and does not have a value. Attributes without this value are assumed to have string values.] -* unitClassProperty [Indicates that the schema attribute is meant to be applied to unit classes.] -* unitModifierProperty [Indicates that the schema attribute is meant to be applied to unit modifier classes.] -* unitProperty [Indicates that the schema attribute is meant to be applied to units within a unit class.] -* valueClassProperty [Indicates that the schema attribute is meant to be applied to value classes.] - -'''Epilogue''' -This is an updated version of the schema format. The properties are now part of the schema. The schema attributes are designed to be checked in software rather than hard-coded. The schema attributes, themselves have properties. - -!# end hed \ No newline at end of file diff --git a/prerelease/HED8.2.0.xml b/prerelease/HED8.2.0.xml deleted file mode 100644 index c584639c..00000000 --- a/prerelease/HED8.2.0.xml +++ /dev/null @@ -1,7137 +0,0 @@ - - - This schema includes an xsd and requires unit class, unit modifier, value class, schema attribute and property sections. - - - - - Event - Something that happens at a given time and (typically) place. Elements of this tag subtree designate the general category in which an event falls. - - suggestedTag - Task-property - - - Sensory-event - Something perceivable by the participant. An event meant to be an experimental stimulus should include the tag Task-property/Task-event-role/Experimental-stimulus. - - suggestedTag - Task-event-role - Sensory-presentation - - - - Agent-action - Any action engaged in by an agent (see the Agent subtree for agent categories). A participant response to an experiment stimulus should include the tag Agent-property/Agent-task-role/Experiment-participant. - - suggestedTag - Task-event-role - Agent - - - - Data-feature - An event marking the occurrence of a data feature such as an interictal spike or alpha burst that is often added post hoc to the data record. - - suggestedTag - Data-property - - - - Experiment-control - An event pertaining to the physical control of the experiment during its operation. - - - Experiment-procedure - An event indicating an experimental procedure, as in performing a saliva swab during the experiment or administering a survey. - - - Experiment-structure - An event specifying a change-point of the structure of experiment. This event is typically used to indicate a change in experimental conditions or tasks. - - - Measurement-event - A discrete measure returned by an instrument. - - suggestedTag - Data-property - - - - - Agent - Someone or something that takes an active role or produces a specified effect.The role or effect may be implicit. Being alive or performing an activity such as a computation may qualify something to be an agent. An agent may also be something that simulates something else. - - suggestedTag - Agent-property - - - Animal-agent - An agent that is an animal. - - - Avatar-agent - An agent associated with an icon or avatar representing another agent. - - - Controller-agent - An agent experiment control software or hardware. - - - Human-agent - A person who takes an active role or produces a specified effect. - - - Robotic-agent - An agent mechanical device capable of performing a variety of often complex tasks on command or by being programmed in advance. - - - Software-agent - An agent computer program. - - - - Action - Do something. - - extensionAllowed - - - Communicate - Convey knowledge of or information about something. - - Communicate-gesturally - Communicate nonverbally using visible bodily actions, either in place of speech or together and in parallel with spoken words. Gestures include movement of the hands, face, or other parts of the body. - - relatedTag - Move-face - Move-upper-extremity - - - Clap-hands - Strike the palms of against one another resoundingly, and usually repeatedly, especially to express approval. - - - Clear-throat - Cough slightly so as to speak more clearly, attract attention, or to express hesitancy before saying something awkward. - - relatedTag - Move-face - Move-head - - - - Frown - Express disapproval, displeasure, or concentration, typically by turning down the corners of the mouth. - - relatedTag - Move-face - - - - Grimace - Make a twisted expression, typically expressing disgust, pain, or wry amusement. - - relatedTag - Move-face - - - - Nod-head - Tilt head in alternating up and down arcs along the sagittal plane. It is most commonly, but not universally, used to indicate agreement, acceptance, or acknowledgement. - - relatedTag - Move-head - - - - Pump-fist - Raise with fist clenched in triumph or affirmation. - - relatedTag - Move-upper-extremity - - - - Raise-eyebrows - Move eyebrows upward. - - relatedTag - Move-face - Move-eyes - - - - Shake-fist - Clench hand into a fist and shake to demonstrate anger. - - relatedTag - Move-upper-extremity - - - - Shake-head - Turn head from side to side as a way of showing disagreement or refusal. - - relatedTag - Move-head - - - - Shhh - Place finger over lips and possibly uttering the syllable shhh to indicate the need to be quiet. - - relatedTag - Move-upper-extremity - - - - Shrug - Lift shoulders up towards head to indicate a lack of knowledge about a particular topic. - - relatedTag - Move-upper-extremity - Move-torso - - - - Smile - Form facial features into a pleased, kind, or amused expression, typically with the corners of the mouth turned up and the front teeth exposed. - - relatedTag - Move-face - - - - Spread-hands - Spread hands apart to indicate ignorance. - - relatedTag - Move-upper-extremity - - - - Thumbs-down - Extend the thumb downward to indicate disapproval. - - relatedTag - Move-upper-extremity - - - - Thumb-up - Extend the thumb upward to indicate approval. - - relatedTag - Move-upper-extremity - - - - Wave - Raise hand and move left and right, as a greeting or sign of departure. - - relatedTag - Move-upper-extremity - - - - Widen-eyes - Open eyes and possibly with eyebrows lifted especially to express surprise or fear. - - relatedTag - Move-face - Move-eyes - - - - Wink - Close and open one eye quickly, typically to indicate that something is a joke or a secret or as a signal of affection or greeting. - - relatedTag - Move-face - Move-eyes - - - - - Communicate-musically - Communicate using music. - - Hum - Make a low, steady continuous sound like that of a bee. Sing with the lips closed and without uttering speech. - - - Play-instrument - Make musical sounds using an instrument. - - - Sing - Produce musical tones by means of the voice. - - - Vocalize - Utter vocal sounds. - - - Whistle - Produce a shrill clear sound by forcing breath out or air in through the puckered lips. - - - - Communicate-vocally - Communicate using mouth or vocal cords. - - Cry - Shed tears associated with emotions, usually sadness but also joy or frustration. - - - Groan - Make a deep inarticulate sound in response to pain or despair. - - - Laugh - Make the spontaneous sounds and movements of the face and body that are the instinctive expressions of lively amusement and sometimes also of contempt or derision. - - - Scream - Make loud, vociferous cries or yells to express pain, excitement, or fear. - - - Shout - Say something very loudly. - - - Sigh - Emit a long, deep, audible breath expressing sadness, relief, tiredness, or a similar feeling. - - - Speak - Communicate using spoken language. - - - Whisper - Speak very softly using breath without vocal cords. - - - - - Move - Move in a specified direction or manner. Change position or posture. - - Breathe - Inhale or exhale during respiration. - - Blow - Expel air through pursed lips. - - - Cough - Suddenly and audibly expel air from the lungs through a partially closed glottis, preceded by inhalation. - - - Exhale - Blow out or expel breath. - - - Hiccup - Involuntarily spasm the diaphragm and respiratory organs, with a sudden closure of the glottis and a characteristic sound like that of a cough. - - - Hold-breath - Interrupt normal breathing by ceasing to inhale or exhale. - - - Inhale - Draw in with the breath through the nose or mouth. - - - Sneeze - Suddenly and violently expel breath through the nose and mouth. - - - Sniff - Draw in air audibly through the nose to detect a smell, to stop it from running, or to express contempt. - - - - Move-body - Move entire body. - - Bend - Move body in a bowed or curved manner. - - - Dance - Perform a purposefully selected sequences of human movement often with aesthetic or symbolic value. Move rhythmically to music, typically following a set sequence of steps. - - - Fall-down - Lose balance and collapse. - - - Flex - Cause a muscle to stand out by contracting or tensing it. Bend a limb or joint. - - - Jerk - Make a quick, sharp, sudden movement. - - - Lie-down - Move to a horizontal or resting position. - - - Recover-balance - Return to a stable, upright body position. - - - Sit-down - Move from a standing to a sitting position. - - - Sit-up - Move from lying down to a sitting position. - - - Stand-up - Move from a sitting to a standing position. - - - Stretch - Straighten or extend body or a part of body to its full length, typically so as to tighten muscles or in order to reach something. - - - Shudder - Tremble convulsively, sometimes as a result of fear or revulsion. - - - Stumble - Trip or momentarily lose balance and almost fall. - - - Turn - Change or cause to change direction. - - - - Move-body-part - Move one part of a body. - - Move-eyes - Move eyes. - - Blink - Shut and open the eyes quickly. - - - Close-eyes - Lower and keep eyelids in a closed position. - - - Fixate - Direct eyes to a specific point or target. - - - Inhibit-blinks - Purposely prevent blinking. - - - Open-eyes - Raise eyelids to expose pupil. - - - Saccade - Move eyes rapidly between fixation points. - - - Squint - Squeeze one or both eyes partly closed in an attempt to see more clearly or as a reaction to strong light. - - - Stare - Look fixedly or vacantly at someone or something with eyes wide open. - - - - Move-face - Move the face or jaw. - - Bite - Seize with teeth or jaws an object or organism so as to grip or break the surface covering. - - - Burp - Noisily release air from the stomach through the mouth. Belch. - - - Chew - Repeatedly grinding, tearing, and or crushing with teeth or jaws. - - - Gurgle - Make a hollow bubbling sound like that made by water running out of a bottle. - - - Swallow - Cause or allow something, especially food or drink to pass down the throat. - - Gulp - Swallow quickly or in large mouthfuls, often audibly, sometimes to indicate apprehension. - - - - Yawn - Take a deep involuntary inhalation with the mouth open often as a sign of drowsiness or boredom. - - - - Move-head - Move head. - - Lift-head - Tilt head back lifting chin. - - - Lower-head - Move head downward so that eyes are in a lower position. - - - Turn-head - Rotate head horizontally to look in a different direction. - - - - Move-lower-extremity - Move leg and/or foot. - - Curl-toes - Bend toes sometimes to grip. - - - Hop - Jump on one foot. - - - Jog - Run at a trot to exercise. - - - Jump - Move off the ground or other surface through sudden muscular effort in the legs. - - - Kick - Strike out or flail with the foot or feet. Strike using the leg, in unison usually with an area of the knee or lower using the foot. - - - Pedal - Move by working the pedals of a bicycle or other machine. - - - Press-foot - Move by pressing foot. - - - Run - Travel on foot at a fast pace. - - - Step - Put one leg in front of the other and shift weight onto it. - - Heel-strike - Strike the ground with the heel during a step. - - - Toe-off - Push with toe as part of a stride. - - - - Trot - Run at a moderate pace, typically with short steps. - - - Walk - Move at a regular pace by lifting and setting down each foot in turn never having both feet off the ground at once. - - - - Move-torso - Move body trunk. - - - Move-upper-extremity - Move arm, shoulder, and/or hand. - - Drop - Let or cause to fall vertically. - - - Grab - Seize suddenly or quickly. Snatch or clutch. - - - Grasp - Seize and hold firmly. - - - Hold-down - Prevent someone or something from moving by holding them firmly. - - - Lift - Raising something to higher position. - - - Make-fist - Close hand tightly with the fingers bent against the palm. - - - Point - Draw attention to something by extending a finger or arm. - - - Press - Apply pressure to something to flatten, shape, smooth or depress it. This action tag should be used to indicate key presses and mouse clicks. - - relatedTag - Push - - - - Push - Apply force in order to move something away. Use Press to indicate a key press or mouse click. - - relatedTag - Press - - - - Reach - Stretch out your arm in order to get or touch something. - - - Release - Make available or set free. - - - Retract - Draw or pull back. - - - Scratch - Drag claws or nails over a surface or on skin. - - - Snap-fingers - Make a noise by pushing second finger hard against thumb and then releasing it suddenly so that it hits the base of the thumb. - - - Touch - Come into or be in contact with. - - - - - - Perceive - Produce an internal, conscious image through stimulating a sensory system. - - Hear - Give attention to a sound. - - - See - Direct gaze toward someone or something or in a specified direction. - - - Smell - Inhale in order to ascertain an odor or scent. - - - Taste - Sense a flavor in the mouth and throat on contact with a substance. - - - Sense-by-touch - Sense something through receptors in the skin. - - - - Perform - Carry out or accomplish an action, task, or function. - - Close - Act as to blocked against entry or passage. - - - Collide-with - Hit with force when moving. - - - Halt - Bring or come to an abrupt stop. - - - Modify - Change something. - - - Open - Widen an aperture, door, or gap, especially one allowing access to something. - - - Operate - Control the functioning of a machine, process, or system. - - - Play - Engage in activity for enjoyment and recreation rather than a serious or practical purpose. - - - Read - Interpret something that is written or printed. - - - Repeat - Make do or perform again. - - - Rest - Be inactive in order to regain strength, health, or energy. - - - Write - Communicate or express by means of letters or symbols written or imprinted on a surface. - - - - Think - Direct the mind toward someone or something or use the mind actively to form connected ideas. - - Allow - Allow access to something such as allowing a car to pass. - - - Attend-to - Focus mental experience on specific targets. - - - Count - Tally items either silently or aloud. - - - Deny - Refuse to give or grant something requested or desired by someone. - - - Detect - Discover or identify the presence or existence of something. - - - Discriminate - Recognize a distinction. - - - Encode - Convert information or an instruction into a particular form. - - - Evade - Escape or avoid, especially by cleverness or trickery. - - - Generate - Cause something, especially an emotion or situation to arise or come about. - - - Identify - Establish or indicate who or what someone or something is. - - - Imagine - Form a mental image or concept of something. - - - Judge - Evaluate evidence to make a decision or form a belief. - - - Learn - Adaptively change behavior as the result of experience. - - - Memorize - Adaptively change behavior as the result of experience. - - - Plan - Think about the activities required to achieve a desired goal. - - - Predict - Say or estimate that something will happen or will be a consequence of something without having exact informaton. - - - Recognize - Identify someone or something from having encountered them before. - - - Respond - React to something such as a treatment or a stimulus. - - - Recall - Remember information by mental effort. - - - Switch-attention - Transfer attention from one focus to another. - - - Track - Follow a person, animal, or object through space or time. - - - - - Item - An independently existing thing (living or nonliving). - - extensionAllowed - - - Biological-item - An entity that is biological, that is related to living organisms. - - Anatomical-item - A biological structure, system, fluid or other substance excluding single molecular entities. - - Body - The biological structure representing an organism. - - - Body-part - Any part of an organism. - - Head - The upper part of the human body, or the front or upper part of the body of an animal, typically separated from the rest of the body by a neck, and containing the brain, mouth, and sense organs. - - Hair - The filamentous outgrowth of the epidermis. - - - Ear - A sense organ needed for the detection of sound and for establishing balance. - - - Face - The anterior portion of the head extending from the forehead to the chin and ear to ear. The facial structures contain the eyes, nose and mouth, cheeks and jaws. - - Cheek - The fleshy part of the face bounded by the eyes, nose, ear, and jaw line. - - - Chin - The part of the face below the lower lip and including the protruding part of the lower jaw. - - - Eye - The organ of sight or vision. - - - Eyebrow - The arched strip of hair on the bony ridge above each eye socket. - - - Forehead - The part of the face between the eyebrows and the normal hairline. - - - Lip - Fleshy fold which surrounds the opening of the mouth. - - - Nose - A structure of special sense serving as an organ of the sense of smell and as an entrance to the respiratory tract. - - - Mouth - The proximal portion of the digestive tract, containing the oral cavity and bounded by the oral opening. - - - Teeth - The hard bonelike structures in the jaws. A collection of teeth arranged in some pattern in the mouth or other part of the body. - - - - - Lower-extremity - Refers to the whole inferior limb (leg and/or foot). - - Ankle - A gliding joint between the distal ends of the tibia and fibula and the proximal end of the talus. - - - Calf - The fleshy part at the back of the leg below the knee. - - - Foot - The structure found below the ankle joint required for locomotion. - - Big-toe - The largest toe on the inner side of the foot. - - - Heel - The back of the foot below the ankle. - - - Instep - The part of the foot between the ball and the heel on the inner side. - - - Little-toe - The smallest toe located on the outer side of the foot. - - - Toes - The terminal digits of the foot. - - - - Knee - A joint connecting the lower part of the femur with the upper part of the tibia. - - - Shin - Front part of the leg below the knee. - - - Thigh - Upper part of the leg between hip and knee. - - - - Torso - The body excluding the head and neck and limbs. - - Torso-back - The rear surface of the human body from the shoulders to the hips. - - - Buttocks - The round fleshy parts that form the lower rear area of a human trunk. - - - Torso-chest - The anterior side of the thorax from the neck to the abdomen. - - - Gentalia - The external organs of reproduction. - - - Hip - The lateral prominence of the pelvis from the waist to the thigh. - - - Waist - The abdominal circumference at the navel. - - - - Upper-extremity - Refers to the whole superior limb (shoulder, arm, elbow, wrist, hand). - - Elbow - A type of hinge joint located between the forearm and upper arm. - - - Forearm - Lower part of the arm between the elbow and wrist. - - - Hand - The distal portion of the upper extremity. It consists of the carpus, metacarpus, and digits. - - Finger - Any of the digits of the hand. - - Index-finger - The second finger from the radial side of the hand, next to the thumb. - - - Little-finger - The fifth and smallest finger from the radial side of the hand. - - - Middle-finger - The middle or third finger from the radial side of the hand. - - - Ring-finger - The fourth finger from the radial side of the hand. - - - Thumb - The thick and short hand digit which is next to the index finger in humans. - - - - Palm - The part of the inner surface of the hand that extends from the wrist to the bases of the fingers. - - - Knuckles - A part of a finger at a joint where the bone is near the surface, especially where the finger joins the hand. - - - - Shoulder - Joint attaching upper arm to trunk. - - - Upper-arm - Portion of arm between shoulder and elbow. - - - Wrist - A joint between the distal end of the radius and the proximal row of carpal bones. - - - - - - Organism - A living entity, more specifically a biological entity that consists of one or more cells and is capable of genomic replication (independently or not). - - Animal - A living organism that has membranous cell walls, requires oxygen and organic foods, and is capable of voluntary movement. - - - Human - The bipedal primate mammal Homo sapiens. - - - Plant - Any living organism that typically synthesizes its food from inorganic substances and possesses cellulose cell walls. - - - - - Language-item - An entity related to a systematic means of communicating by the use of sounds, symbols, or gestures. - - suggestedTag - Sensory-presentation - - - Character - A mark or symbol used in writing. - - - Clause - A unit of grammatical organization next below the sentence in rank, usually consisting of a subject and predicate. - - - Glyph - A hieroglyphic character, symbol, or pictograph. - - - Nonword - A group of letters or speech sounds that looks or sounds like a word but that is not accepted as such by native speakers. - - - Paragraph - A distinct section of a piece of writing, usually dealing with a single theme. - - - Phoneme - A speech sound that is distinguished by the speakers of a particular language. - - - Phrase - A phrase is a group of words functioning as a single unit in the syntax of a sentence. - - - Sentence - A set of words that is complete in itself, conveying a statement, question, exclamation, or command and typically containing an explicit or implied subject and a predicate containing a finite verb. - - - Syllable - A unit of spoken language larger than a phoneme. - - - Textblock - A block of text. - - - Word - A word is the smallest free form (an item that may be expressed in isolation with semantic or pragmatic content) in a language. - - - - Object - Something perceptible by one or more of the senses, especially by vision or touch. A material thing. - - suggestedTag - Sensory-presentation - - - Geometric-object - An object or a representation that has structure and topology in space. - - Pattern - An arrangement of objects, facts, behaviors, or other things which have scientific, mathematical, geometric, statistical, or other meaning. - - Dots - A small round mark or spot. - - - LED-pattern - A pattern created by lighting selected members of a fixed light emitting diode array. - - - - 2D-shape - A planar, two-dimensional shape. - - Arrow - A shape with a pointed end indicating direction. - - - Clockface - The dial face of a clock. A location identifier based on clockface numbering or anatomic subregion. - - - Cross - A figure or mark formed by two intersecting lines crossing at their midpoints. - - - Dash - A horizontal stroke in writing or printing to mark a pause or break in sense or to represent omitted letters or words. - - - Ellipse - A closed plane curve resulting from the intersection of a circular cone and a plane cutting completely through it, especially a plane not parallel to the base. - - Circle - A ring-shaped structure with every point equidistant from the center. - - - - Rectangle - A parallelogram with four right angles. - - Square - A square is a special rectangle with four equal sides. - - - - Single-point - A point is a geometric entity that is located in a zero-dimensional spatial region and whose position is defined by its coordinates in some coordinate system. - - - Star - A conventional or stylized representation of a star, typically one having five or more points. - - - Triangle - A three-sided polygon. - - - - 3D-shape - A geometric three-dimensional shape. - - Box - A square or rectangular vessel, usually made of cardboard or plastic. - - Cube - A solid or semi-solid in the shape of a three dimensional square. - - - - Cone - A shape whose base is a circle and whose sides taper up to a point. - - - Cylinder - A surface formed by circles of a given radius that are contained in a plane perpendicular to a given axis, whose centers align on the axis. - - - Ellipsoid - A closed plane curve resulting from the intersection of a circular cone and a plane cutting completely through it, especially a plane not parallel to the base. - - Sphere - A solid or hollow three-dimensional object bounded by a closed surface such that every point on the surface is equidistant from the center. - - - - Pyramid - A polyhedron of which one face is a polygon of any number of sides, and the other faces are triangles with a common vertex. - - - - - Ingestible-object - Something that can be taken into the body by the mouth for digestion or absorption. - - - Man-made-object - Something constructed by human means. - - Building - A structure that has a roof and walls and stands more or less permanently in one place. - - Room - An area within a building enclosed by walls and floor and ceiling. - - - Roof - A roof is the covering on the uppermost part of a building which provides protection from animals and weather, notably rain, but also heat, wind and sunlight. - - - Entrance - The means or place of entry. - - - Attic - A room or a space immediately below the roof of a building. - - - Basement - The part of a building that is wholly or partly below ground level. - - - - Clothing - A covering designed to be worn on the body. - - - Device - An object contrived for a specific purpose. - - Assistive-device - A device that help an individual accomplish a task. - - Glasses - Frames with lenses worn in front of the eye for vision correction, eye protection, or protection from UV rays. - - - Writing-device - A device used for writing. - - Pen - A common writing instrument used to apply ink to a surface for writing or drawing. - - - Pencil - An implement for writing or drawing that is constructed of a narrow solid pigment core in a protective casing that prevents the core from being broken or marking the hand. - - - - - Computing-device - An electronic device which take inputs and processes results from the inputs. - - Cellphone - A telephone with access to a cellular radio system so it can be used over a wide area, without a physical connection to a network. - - - Desktop-computer - A computer suitable for use at an ordinary desk. - - - Laptop-computer - A computer that is portable and suitable for use while traveling. - - - Tablet-computer - A small portable computer that accepts input directly on to its screen rather than via a keyboard or mouse. - - - - Engine - A motor is a machine designed to convert one or more forms of energy into mechanical energy. - - - IO-device - Hardware used by a human (or other system) to communicate with a computer. - - Input-device - A piece of equipment used to provide data and control signals to an information processing system such as a computer or information appliance. - - Computer-mouse - A hand-held pointing device that detects two-dimensional motion relative to a surface. - - Mouse-button - An electric switch on a computer mouse which can be pressed or clicked to select or interact with an element of a graphical user interface. - - - Scroll-wheel - A scroll wheel or mouse wheel is a wheel used for scrolling made of hard plastic with a rubbery surface usually located between the left and right mouse buttons and is positioned perpendicular to the mouse surface. - - - - Joystick - A control device that uses a movable handle to create two-axis input for a computer device. - - - Keyboard - A device consisting of mechanical keys that are pressed to create input to a computer. - - Keyboard-key - A button on a keyboard usually representing letters, numbers, functions, or symbols. - - # - Value of a keyboard key. - - takesValue - - - - - - Keypad - A device consisting of keys, usually in a block arrangement, that provides limited input to a system. - - Keypad-key - A key on a separate section of a computer keyboard that groups together numeric keys and those for mathematical or other special functions in an arrangement like that of a calculator. - - # - Value of keypad key. - - takesValue - - - - - - Microphone - A device designed to convert sound to an electrical signal. - - - Push-button - A switch designed to be operated by pressing a button. - - - - Output-device - Any piece of computer hardware equipment which converts information into human understandable form. - - Display-device - An output device for presentation of information in visual or tactile form the latter used for example in tactile electronic displays for blind people. - - Head-mounted-display - An instrument that functions as a display device, worn on the head or as part of a helmet, that has a small display optic in front of one (monocular HMD) or each eye (binocular HMD). - - - LED-display - A LED display is a flat panel display that uses an array of light-emitting diodes as pixels for a video display. - - - Computer-screen - An electronic device designed as a display or a physical device designed to be a protective meshwork. - - Screen-window - A part of a computer screen that contains a display different from the rest of the screen. A window is a graphical control element consisting of a visual area containing some of the graphical user interface of the program it belongs to and is framed by a window decoration. - - - - - Auditory-device - A device designed to produce sound. - - Headphones - An instrument that consists of a pair of small loudspeakers, or less commonly a single speaker, held close to ears and connected to a signal source such as an audio amplifier, radio, CD player or portable media player. - - - Loudspeaker - A device designed to convert electrical signals to sounds that can be heard. - - - - - Recording-device - A device that copies information in a signal into a persistent information bearer. - - EEG-recorder - A device for recording electric currents in the brain using electrodes applied to the scalp, to the surface of the brain, or placed within the substance of the brain. - - - File-storage - A device for recording digital information to a permanent media. - - - MEG-recorder - A device for measuring the magnetic fields produced by electrical activity in the brain, usually conducted externally. - - - Motion-capture - A device for recording the movement of objects or people. - - - Tape-recorder - A device for recording and reproduction usually using magnetic tape for storage that can be saved and played back. - - - - Touchscreen - A control component that operates an electronic device by pressing the display on the screen. - - - - Machine - A human-made device that uses power to apply forces and control movement to perform an action. - - - Measurement-device - A device in which a measure function inheres. - - Clock - A device designed to indicate the time of day or to measure the time duration of an event or action. - - Clock-face - A location identifier based on clockface numbering or anatomic subregion. - - - - - Robot - A mechanical device that sometimes resembles a living animal and is capable of performing a variety of often complex human tasks on command or by being programmed in advance. - - - Tool - A component that is not part of a device but is designed to support its assemby or operation. - - - - Document - A physical object, or electronic counterpart, that is characterized by containing writing which is meant to be human-readable. - - Letter - A written message addressed to a person or organization. - - - Note - A brief written record. - - - Book - A volume made up of pages fastened along one edge and enclosed between protective covers. - - - Notebook - A book for notes or memoranda. - - - Questionnaire - A document consisting of questions and possibly responses, depending on whether it has been filled out. - - - - Furnishing - Furniture, fittings, and other decorative accessories, such as curtains and carpets, for a house or room. - - - Manufactured-material - Substances created or extracted from raw materials. - - Ceramic - A hard, brittle, heat-resistant and corrosion-resistant material made by shaping and then firing a nonmetallic mineral, such as clay, at a high temperature. - - - Glass - A brittle transparent solid with irregular atomic structure. - - - Paper - A thin sheet material produced by mechanically or chemically processing cellulose fibres derived from wood, rags, grasses or other vegetable sources in water. - - - Plastic - Various high-molecular-weight thermoplastic or thermosetting polymers that are capable of being molded, extruded, drawn, or otherwise shaped and then hardened into a form. - - - Steel - An alloy made up of iron with typically a few tenths of a percent of carbon to improve its strength and fracture resistance compared to iron. - - - - Media - Media are audo/visual/audiovisual modes of communicating information for mass consumption. - - Media-clip - A short segment of media. - - Audio-clip - A short segment of audio. - - - Audiovisual-clip - A short media segment containing both audio and video. - - - Video-clip - A short segment of video. - - - - Visualization - An planned process that creates images, diagrams or animations from the input data. - - Animation - A form of graphical illustration that changes with time to give a sense of motion or represent dynamic changes in the portrayal. - - - Art-installation - A large-scale, mixed-media constructions, often designed for a specific place or for a temporary period of time. - - - Braille - A display using a system of raised dots that can be read with the fingers by people who are blind. - - - Image - Any record of an imaging event whether physical or electronic. - - Cartoon - A type of illustration, sometimes animated, typically in a non-realistic or semi-realistic style. The specific meaning has evolved over time, but the modern usage usually refers to either an image or series of images intended for satire, caricature, or humor. A motion picture that relies on a sequence of illustrations for its animation. - - - Drawing - A representation of an object or outlining a figure, plan, or sketch by means of lines. - - - Icon - A sign (such as a word or graphic symbol) whose form suggests its meaning. - - - Painting - A work produced through the art of painting. - - - Photograph - An image recorded by a camera. - - - - Movie - A sequence of images displayed in succession giving the illusion of continuous movement. - - - Outline-visualization - A visualization consisting of a line or set of lines enclosing or indicating the shape of an object in a sketch or diagram. - - - Point-light-visualization - A display in which action is depicted using a few points of light, often generated from discrete sensors in motion capture. - - - Sculpture - A two- or three-dimensional representative or abstract forms, especially by carving stone or wood or by casting metal or plaster. - - - Stick-figure-visualization - A drawing showing the head of a human being or animal as a circle and all other parts as straight lines. - - - - - Navigational-object - An object whose purpose is to assist directed movement from one location to another. - - Path - A trodden way. A way or track laid down for walking or made by continual treading. - - - Road - An open way for the passage of vehicles, persons, or animals on land. - - Lane - A defined path with physical dimensions through which an object or substance may traverse. - - - - Runway - A paved strip of ground on a landing field for the landing and takeoff of aircraft. - - - - Vehicle - A mobile machine which transports people or cargo. - - Aircraft - A vehicle which is able to travel through air in an atmosphere. - - - Bicycle - A human-powered, pedal-driven, single-track vehicle, having two wheels attached to a frame, one behind the other. - - - Boat - A watercraft of any size which is able to float or plane on water. - - - Car - A wheeled motor vehicle used primarily for the transportation of human passengers. - - - Cart - A cart is a vehicle which has two wheels and is designed to transport human passengers or cargo. - - - Tractor - A mobile machine specifically designed to deliver a high tractive effort at slow speeds, and mainly used for the purposes of hauling a trailer or machinery used in agriculture or construction. - - - Train - A connected line of railroad cars with or without a locomotive. - - - Truck - A motor vehicle which, as its primary funcion, transports cargo rather than human passangers. - - - - - Natural-object - Something that exists in or is produced by nature, and is not artificial or man-made. - - Mineral - A solid, homogeneous, inorganic substance occurring in nature and having a definite chemical composition. - - - Natural-feature - A feature that occurs in nature. A prominent or identifiable aspect, region, or site of interest. - - Field - An unbroken expanse as of ice or grassland. - - - Hill - A rounded elevation of limited extent rising above the surrounding land with local relief of less than 300m. - - - Mountain - A landform that extends above the surrounding terrain in a limited area. - - - River - A natural freshwater surface stream of considerable volume and a permanent or seasonal flow, moving in a definite channel toward a sea, lake, or another river. - - - Waterfall - A sudden descent of water over a step or ledge in the bed of a river. - - - - - - Sound - Mechanical vibrations transmitted by an elastic medium. Something that can be heard. - - Environmental-sound - Sounds occuring in the environment. An accumulation of noise pollution that occurs outside. This noise can be caused by transport, industrial, and recreational activities. - - Crowd-sound - Noise produced by a mixture of sounds from a large group of people. - - - Signal-noise - Any part of a signal that is not the true or original signal but is introduced by the communication mechanism. - - - - Musical-sound - Sound produced by continuous and regular vibrations, as opposed to noise. - - Tone - A musical note, warble, or other sound used as a particular signal on a telephone or answering machine. - - - Instrument-sound - Sound produced by a musical instrument. - - - Vocalized-sound - Musical sound produced by vocal cords in a biological agent. - - - - Named-animal-sound - A sound recognizable as being associated with particular animals. - - Barking - Sharp explosive cries like sounds made by certain animals, especially a dog, fox, or seal. - - - Bleating - Wavering cries like sounds made by a sheep, goat, or calf. - - - Crowing - Loud shrill sounds characteristic of roosters. - - - Chirping - Short, sharp, high-pitched noises like sounds made by small birds or an insects. - - - Growling - Low guttural sounds like those that made in the throat by a hostile dog or other animal. - - - Meowing - Vocalizations like those made by as those cats. These sounds have diverse tones and are sometimes chattered, murmured or whispered. The purpose can be assertive. - - - Mooing - Deep vocal sounds like those made by a cow. - - - Purring - Low continuous vibratory sound such as those made by cats. The sound expresses contentment. - - - Roaring - Loud, deep, or harsh prolonged sounds such as those made by big cats and bears for long-distance communication and intimidation. - - - Squawking - Loud, harsh noises such as those made by geese. - - - - Named-object-sound - A sound identifiable as coming from a particular type of object. - - Alarm-sound - A loud signal often loud continuous ringing to alert people to a problem or condition that requires urgent attention. - - - Beep - A short, single tone, that is typically high-pitched and generally made by a computer or other machine. - - - Buzz - A persistent vibratory sound often made by a buzzer device and used to indicate something incorrect. - - - Ka-ching - The sound made by a mechanical cash register, often to designate a reward. - - - Click - The sound made by a mechanical cash register, often to designate a reward. - - - Ding - A short ringing sound such as that made by a bell, often to indicate a correct response or the expiration of time. - - - Horn-blow - A loud sound made by forcing air through a sound device that funnels air to create the sound, often used to sound an alert. - - - Siren - A loud, continuous sound often varying in frequency designed to indicate an emergency. - - - - - - Property - Something that pertains to a thing. A characteristic of some entity. A quality or feature regarded as a characteristic or inherent part of someone or something. HED attributes are adjectives or adverbs. - - extensionAllowed - - - Agent-property - Something that pertains to an agent. - - extensionAllowed - - - Agent-state - The state of the agent. - - Agent-cognitive-state - The state of the cognitive processes or state of mind of the agent. - - Alert - Condition of heightened watchfulness or preparation for action. - - - Anesthetized - Having lost sensation to pain or having senses dulled due to the effects of an anesthetic. - - - Asleep - Having entered a periodic, readily reversible state of reduced awareness and metabolic activity, usually accompanied by physical relaxation and brain activity. - - - Attentive - Concentrating and focusing mental energy on the task or surroundings. - - - Distracted - Lacking in concentration because of being preoccupied. - - - Awake - In a non sleeping state. - - - Brain-dead - Characterized by the irreversible absence of cortical and brain stem functioning. - - - Comatose - In a state of profound unconsciousness associated with markedly depressed cerebral activity. - - - Drowsy - In a state of near-sleep, a strong desire for sleep, or sleeping for unusually long periods. - - - Intoxicated - In a state with disturbed psychophysiological functions and responses as a result of administration or ingestion of a psychoactive substance. - - - Locked-in - In a state of complete paralysis of all voluntary muscles except for the ones that control the movements of the eyes. - - - Passive - Not responding or initiating an action in response to a stimulus. - - - Resting - A state in which the agent is not exhibiting any physical exertion. - - - Vegetative - A state of wakefulness and conscience, but (in contrast to coma) with involuntary opening of the eyes and movements (such as teeth grinding, yawning, or thrashing of the extremities). - - - - Agent-emotional-state - The status of the general temperament and outlook of an agent. - - Angry - Experiencing emotions characterized by marked annoyance or hostility. - - - Aroused - In a state reactive to stimuli leading to increased heart rate and blood pressure, sensory alertness, mobility and readiness to respond. - - - Awed - Filled with wonder. Feeling grand, sublime or powerful emotions characterized by a combination of joy, fear, admiration, reverence, and/or respect. - - - Compassionate - Feeling or showing sympathy and concern for others often evoked for a person who is in distress and associated with altruistic motivation. - - - Content - Feeling satisfaction with things as they are. - - - Disgusted - Feeling revulsion or profound disapproval aroused by something unpleasant or offensive. - - - Emotionally-neutral - Feeling neither satisfied nor dissatisfied. - - - Empathetic - Understanding and sharing the feelings of another. Being aware of, being sensitive to, and vicariously experiencing the feelings, thoughts, and experience of another. - - - Excited - Feeling great enthusiasm and eagerness. - - - Fearful - Feeling apprehension that one may be in danger. - - - Frustrated - Feeling annoyed as a result of being blocked, thwarted, disappointed or defeated. - - - Grieving - Feeling sorrow in response to loss, whether physical or abstract. - - - Happy - Feeling pleased and content. - - - Jealous - Feeling threatened by a rival in a relationship with another individual, in particular an intimate partner, usually involves feelings of threat, fear, suspicion, distrust, anxiety, anger, betrayal, and rejection. - - - Joyful - Feeling delight or intense happiness. - - - Loving - Feeling a strong positive emotion of affection and attraction. - - - Relieved - No longer feeling pain, distress, anxiety, or reassured. - - - Sad - Feeling grief or unhappiness. - - - Stressed - Experiencing mental or emotional strain or tension. - - - - Agent-physiological-state - Having to do with the mechanical, physical, or biochemical function of an agent. - - Healthy - Having no significant health-related issues. - - relatedTag - Sick - - - - Hungry - Being in a state of craving or desiring food. - - relatedTag - Sated - Thirsty - - - - Rested - Feeling refreshed and relaxed. - - relatedTag - Tired - - - - Sated - Feeling full. - - relatedTag - Hungry - - - - Sick - Being in a state of ill health, bodily malfunction, or discomfort. - - relatedTag - Healthy - - - - Thirsty - Feeling a need to drink. - - relatedTag - Hungry - - - - Tired - Feeling in need of sleep or rest. - - relatedTag - Rested - - - - - Agent-postural-state - Pertaining to the position in which agent holds their body. - - Crouching - Adopting a position where the knees are bent and the upper body is brought forward and down, sometimes to avoid detection or to defend oneself. - - - Eyes-closed - Keeping eyes closed with no blinking. - - - Eyes-open - Keeping eyes open with occasional blinking. - - - Kneeling - Positioned where one or both knees are on the ground. - - - On-treadmill - Ambulation on an exercise apparatus with an endless moving belt to support moving in place. - - - Prone - Positioned in a recumbent body position whereby the person lies on its stomach and faces downward. - - - Sitting - In a seated position. - - - Standing - Assuming or maintaining an erect upright position. - - - Seated-with-chin-rest - Using a device that supports the chin and head. - - - - - Agent-task-role - The function or part that is ascribed to an agent in performing the task. - - Experiment-actor - An agent who plays a predetermined role to create the experiment scenario. - - - Experiment-controller - An agent exerting control over some aspect of the experiment. - - - Experiment-participant - Someone who takes part in an activity related to an experiment. - - - Experimenter - Person who is the owner of the experiment and has its responsibility. - - - - Agent-trait - A genetically, environmentally, or socially determined characteristic of an agent. - - Age - Length of time elapsed time since birth of the agent. - - # - - takesValue - - - valueClass - numericClass - - - - - Agent-experience-level - Amount of skill or knowledge that the agent has as pertains to the task. - - Expert-level - Having comprehensive and authoritative knowledge of or skill in a particular area related to the task. - - relatedTag - Intermediate-experience-level - Novice-level - - - - Intermediate-experience-level - Having a moderate amount of knowledge or skill related to the task. - - relatedTag - Expert-level - Novice-level - - - - Novice-level - Being inexperienced in a field or situation related to the task. - - relatedTag - Expert-level - Intermediate-experience-level - - - - - Gender - Characteristics that are socially constructed, including norms, behaviors, and roles based on sex. - - - Sex - Physical properties or qualities by which male is distinguished from female. - - Female - Biological sex of an individual with female sexual organs such ova. - - - Male - Biological sex of an individual with male sexual organs producing sperm. - - - Intersex - Having genitalia and/or secondary sexual characteristics of indeterminate sex. - - - - Ethnicity - Belong to a social group that has a common national or cultural tradition. Use with Label to avoid extension. - - - Handedness - Individual preference for use of a hand, known as the dominant hand. - - Left-handed - Preference for using the left hand or foot for tasks requiring the use of a single hand or foot. - - - Right-handed - Preference for using the right hand or foot for tasks requiring the use of a single hand or foot. - - - Ambidextrous - Having no overall dominance in the use of right or left hand or foot in the performance of tasks that require one hand or foot. - - - - Race - Belonging to a group sharing physical or social qualities as defined within a specified society. Use with Label to avoid extension. - - - - - Data-property - Something that pertains to data or information. - - extensionAllowed - - - Data-marker - An indicator placed to mark something. - - Data-break-marker - An indicator place to indicate a gap in the data. - - - Temporal-marker - An indicator placed at a particular time in the data. - - Onset - Labels the start or beginning of something, usually an event. - - topLevelTagGroup - - - - Offset - Labels the time at which something stops. - - topLevelTagGroup - - - - Pause - Indicates the temporary interruption of the operation a process and subsequently wait for a signal to continue. - - - Time-out - A cancellation or cessation that automatically occurs when a predefined interval of time has passed without a certain event occurring. - - - Time-sync - A synchronization signal whose purpose to help synchronize different signals or processes. Often used to indicate a marker inserted into the recorded data to allow post hoc synchronization of concurrently recorded data streams. - - - - - Data-resolution - Smallest change in a quality being measured by an sensor that causes a perceptible change. - - Printer-resolution - Resolution of a printer, usually expressed as the number of dots-per-inch for a printer. - - # - - takesValue - - - valueClass - numericClass - - - - - Screen-resolution - Resolution of a screen, usually expressed as the of pixels in a dimension for a digital display device. - - # - - takesValue - - - valueClass - numericClass - - - - - Sensory-resolution - Resolution of measurements by a sensing device. - - # - - takesValue - - - valueClass - numericClass - - - - - Spatial-resolution - Linear spacing of a spatial measurement. - - # - - takesValue - - - valueClass - numericClass - - - - - Spectral-resolution - Measures the ability of a sensor to resolve features in the electromagnetic spectrum. - - # - - takesValue - - - valueClass - numericClass - - - - - Temporal-resolution - Measures the ability of a sensor to resolve features in time. - - # - - takesValue - - - valueClass - numericClass - - - - - - Data-source-type - The type of place, person, or thing from which the data comes or can be obtained. - - Computed-feature - A feature computed from the data by a tool. This tag should be grouped with a label of the form Toolname_propertyName. - - - Computed-prediction - A computed extrapolation of known data. - - - Expert-annotation - An explanatory or critical comment or other in-context information provided by an authority. - - - Instrument-measurement - Information obtained from a device that is used to measure material properties or make other observations. - - - Observation - Active acquisition of information from a primary source. Should be grouped with a label of the form AgentID_featureName. - - - - Data-value - Designation of the type of a data item. - - Categorical-value - Indicates that something can take on a limited and usually fixed number of possible values. - - Categorical-class-value - Categorical values that fall into discrete classes such as true or false. The grouping is absolute in the sense that it is the same for all participants. - - All - To a complete degree or to the full or entire extent. - - relatedTag - Some - None - - - - Correct - Free from error. Especially conforming to fact or truth. - - relatedTag - Wrong - - - - Explicit - Stated clearly and in detail, leaving no room for confusion or doubt. - - relatedTag - Implicit - - - - False - Not in accordance with facts, reality or definitive criteria. - - relatedTag - True - - - - Implicit - Implied though not plainly expressed. - - relatedTag - Explicit - - - - Invalid - Not allowed or not conforming to the correct format or specifications. - - relatedTag - Valid - - - - None - No person or thing, nobody, not any. - - relatedTag - All - Some - - - - Some - At least a small amount or number of, but not a large amount of, or often. - - relatedTag - All - None - - - - True - Conforming to facts, reality or definitive criteria. - - relatedTag - False - - - - Valid - Allowable, usable, or acceptable. - - relatedTag - Invalid - - - - Wrong - Inaccurate or not correct. - - relatedTag - Correct - - - - - Categorical-judgment-value - Categorical values that are based on the judgment or perception of the participant such familiar and famous. - - Abnormal - Deviating in any way from the state, position, structure, condition, behavior, or rule which is considered a norm. - - relatedTag - Normal - - - - Asymmetrical - Lacking symmetry or having parts that fail to correspond to one another in shape, size, or arrangement. - - relatedTag - Symmetrical - - - - Audible - A sound that can be perceived by the participant. - - relatedTag - Inaudible - - - - Congruent - Concordance of multiple evidence lines. In agreement or harmony. - - relatedTag - Incongruent - - - - Complex - Hard, involved or complicated, elaborate, having many parts. - - relatedTag - Simple - - - - Constrained - Keeping something within particular limits or bounds. - - relatedTag - Unconstrained - - - - Disordered - Not neatly arranged. Confused and untidy. A structural quality in which the parts of an object are non-rigid. - - relatedTag - Ordered - - - - Familiar - Recognized, familiar, or within the scope of knowledge. - - relatedTag - Unfamiliar - Famous - - - - Famous - A person who has a high degree of recognition by the general population for his or her success or accomplishments. A famous person. - - relatedTag - Familiar - Unfamiliar - - - - Inaudible - A sound below the threshold of perception of the participant. - - relatedTag - Audible - - - - Incongruent - Not in agreement or harmony. - - relatedTag - Congruent - - - - Involuntary - An action that is not made by choice. In the body, involuntary actions (such as blushing) occur automatically, and cannot be controlled by choice. - - relatedTag - Voluntary - - - - Masked - Information exists but is not provided or is partially obscured due to security, privacy, or other concerns. - - relatedTag - Unmasked - - - - Normal - Being approximately average or within certain limits. Conforming with or constituting a norm or standard or level or type or social norm. - - relatedTag - Abnormal - - - - Ordered - Conforming to a logical or comprehensible arrangement of separate elements. - - relatedTag - Disordered - - - - Simple - Easily understood or presenting no difficulties. - - relatedTag - Complex - - - - Symmetrical - Made up of exactly similar parts facing each other or around an axis. Showing aspects of symmetry. - - relatedTag - Asymmetrical - - - - Unconstrained - Moving without restriction. - - relatedTag - Constrained - - - - Unfamiliar - Not having knowledge or experience of. - - relatedTag - Familiar - Famous - - - - Unmasked - Information is revealed. - - relatedTag - Masked - - - - Voluntary - Using free will or design; not forced or compelled; controlled by individual volition. - - relatedTag - Involuntary - - - - - Categorical-level-value - Categorical values based on dividing a continuous variable into levels such as high and low. - - Cold - Having an absence of heat. - - relatedTag - Hot - - - - Deep - Extending relatively far inward or downward. - - relatedTag - Shallow - - - - High - Having a greater than normal degree, intensity, or amount. - - relatedTag - Low - Medium - - - - Hot - Having an excess of heat. - - relatedTag - Cold - - - - Large - Having a great extent such as in physical dimensions, period of time, amplitude or frequency. - - relatedTag - Small - - - - Liminal - Situated at a sensory threshold that is barely perceptible or capable of eliciting a response. - - relatedTag - Subliminal - Supraliminal - - - - Loud - Having a perceived high intensity of sound. - - relatedTag - Quiet - - - - Low - Less than normal in degree, intensity or amount. - - relatedTag - High - - - - Medium - Mid-way between small and large in number, quantity, magnitude or extent. - - relatedTag - Low - High - - - - Negative - Involving disadvantage or harm. - - relatedTag - Positive - - - - Positive - Involving advantage or good. - - relatedTag - Negative - - - - Quiet - Characterizing a perceived low intensity of sound. - - relatedTag - Loud - - - - Rough - Having a surface with perceptible bumps, ridges, or irregularities. - - relatedTag - Smooth - - - - Shallow - Having a depth which is relatively low. - - relatedTag - Deep - - - - Small - Having a small extent such as in physical dimensions, period of time, amplitude or frequency. - - relatedTag - Large - - - - Smooth - Having a surface free from bumps, ridges, or irregularities. - - relatedTag - Rough - - - - Subliminal - Situated below a sensory threshold that is imperceptible or not capable of eliciting a response. - - relatedTag - Liminal - Supraliminal - - - - Supraliminal - Situated above a sensory threshold that is perceptible or capable of eliciting a response. - - relatedTag - Liminal - Subliminal - - - - Thick - Wide in width, extent or cross-section. - - relatedTag - Thin - - - - Thin - Narrow in width, extent or cross-section. - - relatedTag - Thick - - - - - Categorical-orientation-value - Value indicating the orientation or direction of something. - - Backward - Directed behind or to the rear. - - relatedTag - Forward - - - - Downward - Moving or leading toward a lower place or level. - - relatedTag - Leftward - Rightward - Upward - - - - Forward - At or near or directed toward the front. - - relatedTag - Backward - - - - Horizontally-oriented - Oriented parallel to or in the plane of the horizon. - - relatedTag - Vertically-oriented - - - - Leftward - Going toward or facing the left. - - relatedTag - Downward - Rightward - Upward - - - - Oblique - Slanting or inclined in direction, course, or position that is neither parallel nor perpendicular nor right-angular. - - relatedTag - Rotated - - - - Rightward - Going toward or situated on the right. - - relatedTag - Downward - Leftward - Upward - - - - Rotated - Positioned offset around an axis or center. - - - Upward - Moving, pointing, or leading to a higher place, point, or level. - - relatedTag - Downward - Leftward - Rightward - - - - Vertically-oriented - Oriented perpendicular to the plane of the horizon. - - relatedTag - Horizontally-oriented - - - - - - Physical-value - The value of some physical property of something. - - Weight - The relative mass or the quantity of matter contained by something. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - weightUnits - - - - - Temperature - A measure of hot or cold based on the average kinetic energy of the atoms or molecules in the system. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - temperatureUnits - - - - - - Quantitative-value - Something capable of being estimated or expressed with numeric values. - - Fraction - A numerical value between 0 and 1. - - # - - takesValue - - - valueClass - numericClass - - - - - Item-count - The integer count of something which is usually grouped with the entity it is counting. (Item-count/3, A) indicates that 3 of A have occurred up to this point. - - # - - takesValue - - - valueClass - numericClass - - - - - Item-index - The index of an item in a collection, sequence or other structure. (A (Item-index/3, B)) means that A is item number 3 in B. - - # - - takesValue - - - valueClass - numericClass - - - - - Item-interval - An integer indicating how many items or entities have passed since the last one of these. An item interval of 0 indicates the current item. - - # - - takesValue - - - valueClass - numericClass - - - - - Percentage - A fraction or ratio with 100 understood as the denominator. - - # - - takesValue - - - valueClass - numericClass - - - - - Ratio - A quotient of quantities of the same kind for different components within the same system. - - # - - takesValue - - - valueClass - numericClass - - - - - - Statistical-value - A value based on or employing the principles of statistics. - - extensionAllowed - - - Data-maximum - The largest possible quantity or degree. - - # - - takesValue - - - valueClass - numericClass - - - - - Data-mean - The sum of a set of values divided by the number of values in the set. - - # - - takesValue - - - valueClass - numericClass - - - - - Data-median - The value which has an equal number of values greater and less than it. - - # - - takesValue - - - valueClass - numericClass - - - - - Data-minimum - The smallest possible quantity. - - # - - takesValue - - - valueClass - numericClass - - - - - Probability - A measure of the expectation of the occurrence of a particular event. - - # - - takesValue - - - valueClass - numericClass - - - - - Standard-deviation - A measure of the range of values in a set of numbers. Standard deviation is a statistic used as a measure of the dispersion or variation in a distribution, equal to the square root of the arithmetic mean of the squares of the deviations from the arithmetic mean. - - # - - takesValue - - - valueClass - numericClass - - - - - Statistical-accuracy - A measure of closeness to true value expressed as a number between 0 and 1. - - # - - takesValue - - - valueClass - numericClass - - - - - Statistical-precision - A quantitative representation of the degree of accuracy necessary for or associated with a particular action. - - # - - takesValue - - - valueClass - numericClass - - - - - Statistical-recall - Sensitivity is a measurement datum qualifying a binary classification test and is computed by substracting the false negative rate to the integral numeral 1. - - # - - takesValue - - - valueClass - numericClass - - - - - Statistical-uncertainty - A measure of the inherent variability of repeated observation measurements of a quantity including quantities evaluated by statistical methods and by other means. - - # - - takesValue - - - valueClass - numericClass - - - - - - Spatiotemporal-value - A property relating to space and/or time. - - Rate-of-change - The amount of change accumulated per unit time. - - Acceleration - Magnitude of the rate of change in either speed or direction. The direction of change should be given separately. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - accelerationUnits - - - - - Frequency - Frequency is the number of occurrences of a repeating event per unit time. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - frequencyUnits - - - - - Jerk-rate - Magnitude of the rate at which the acceleration of an object changes with respect to time. The direction of change should be given separately. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - jerkUnits - - - - - Sampling-rate - The number of digital samples taken or recorded per unit of time. - - # - - takesValue - - - unitClass - frequencyUnits - - - - - Refresh-rate - The frequency with which the image on a computer monitor or similar electronic display screen is refreshed, usually expressed in hertz. - - # - - takesValue - - - valueClass - numericClass - - - - - Speed - A scalar measure of the rate of movement of the object expressed either as the distance travelled divided by the time taken (average speed) or the rate of change of position with respect to time at a particular point (instantaneous speed). The direction of change should be given separately. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - speedUnits - - - - - Temporal-rate - The number of items per unit of time. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - frequencyUnits - - - - - - Spatial-value - Value of an item involving space. - - Angle - The amount of inclination of one line to another or the plane of one object to another. - - # - - takesValue - - - unitClass - angleUnits - - - valueClass - numericClass - - - - - Distance - A measure of the space separating two objects or points. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Position - A reference to the alignment of an object, a particular situation or view of a situation, or the location of an object. Coordinates with respect a specified frame of reference or the default Screen-frame if no frame is given. - - X-position - The position along the x-axis of the frame of reference. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Y-position - The position along the y-axis of the frame of reference. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Z-position - The position along the z-axis of the frame of reference. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - - Size - The physical magnitude of something. - - Area - The extent of a 2-dimensional surface enclosed within a boundary. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - areaUnits - - - - - Depth - The distance from the surface of something especially from the perspective of looking from the front. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Length - The linear extent in space from one end of something to the other end, or the extent of something from beginning to end. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Width - The extent or measurement of something from side to side. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Height - The vertical measurement or distance from the base to the top of an object. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - physicalLengthUnits - - - - - Volume - The amount of three dimensional space occupied by an object or the capacity of a space or container. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - volumeUnits - - - - - - - Temporal-value - A characteristic of or relating to time or limited by time. - - Delay - Time during which some action is awaited. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Duration - The period of time during which something occurs or continues. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Time-interval - The period of time separating two instances, events, or occurrences. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Time-value - A value with units of time. Usually grouped with tags identifying what the value represents. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - - - - Data-variability-attribute - An attribute describing how something changes or varies. - - Abrupt - Marked by sudden change. - - - Constant - Continually recurring or continuing without interruption. Not changing in time or space. - - - Continuous - Uninterrupted in time, sequence, substance, or extent. - - relatedTag - Discrete - Discontinuous - - - - Decreasing - Becoming smaller or fewer in size, amount, intensity, or degree. - - relatedTag - Increasing - - - - Deterministic - No randomness is involved in the development of the future states of the element. - - relatedTag - Random - Stochastic - - - - Discontinuous - Having a gap in time, sequence, substance, or extent. - - relatedTag - Continuous - - - - Discrete - Constituting a separate entities or parts. - - relatedTag - Continuous - Discontinuous - - - - Flickering - Moving irregularly or unsteadily or burning or shining fitfully or with a fluctuating light. - - - Estimated-value - Something that has been calculated or measured approximately. - - - Exact-value - A value that is viewed to the true value according to some standard. - - - Fractal - Having extremely irregular curves or shapes for which any suitably chosen part is similar in shape to a given larger or smaller part when magnified or reduced to the same size. - - - Increasing - Becoming greater in size, amount, or degree. - - relatedTag - Decreasing - - - - Random - Governed by or depending on chance. Lacking any definite plan or order or purpose. - - relatedTag - Deterministic - Stochastic - - - - Repetitive - A recurring action that is often non-purposeful. - - - Stochastic - Uses a random probability distribution or pattern that may be analysed statistically but may not be predicted precisely to determine future states. - - relatedTag - Deterministic - Random - - - - Varying - Differing in size, amount, degree, or nature. - - - - - Environmental-property - Relating to or arising from the surroundings of an agent. - - Indoors - Located inside a building or enclosure. - - - Outdoors - Any area outside a building or shelter. - - - Real-world - Located in a place that exists in real space and time under realistic conditions. - - - Virtual-world - Using technology that creates immersive, computer-generated experiences that a person can interact with and navigate through. The digital content is generally delivered to the user through some type of headset and responds to changes in head position or through interaction with other types of sensors. Existing in a virtual setting such as a simulation or game environment. - - - Augmented-reality - Using technology that enhances real-world experiences with computer-derived digital overlays to change some aspects of perception of the natural environment. The digital content is shown to the user through a smart device or glasses and responds to changes in the environment. - - - Motion-platform - A mechanism that creates the feelings of being in a real motion environment. - - - Urban - Relating to, located in, or characteristic of a city or densely populated area. - - - Rural - Of or pertaining to the country as opposed to the city. - - - Terrain - Characterization of the physical features of a tract of land. - - Composite-terrain - Tracts of land characterized by a mixure of physical features. - - - Dirt-terrain - Tracts of land characterized by a soil surface and lack of vegetation. - - - Grassy-terrain - Tracts of land covered by grass. - - - Gravel-terrain - Tracts of land covered by a surface consisting a loose aggregation of small water-worn or pounded stones. - - - Leaf-covered-terrain - Tracts of land covered by leaves and composited organic material. - - - Muddy-terrain - Tracts of land covered by a liquid or semi-liquid mixture of water and some combination of soil, silt, and clay. - - - Paved-terrain - Tracts of land covered with concrete, asphalt, stones, or bricks. - - - Rocky-terrain - Tracts of land consisting or full of rock or rocks. - - - Sloped-terrain - Tracts of land arranged in a sloping or inclined position. - - - Uneven-terrain - Tracts of land that are not level, smooth, or regular. - - - - - Informational-property - Something that pertains to a task. - - extensionAllowed - - - Description - An explanation of what the tag group it is in means. If the description is at the top-level of an event string, the description applies to the event. - - requireChild - - - # - - takesValue - - - valueClass - textClass - - - - - ID - An alphanumeric name that identifies either a unique object or a unique class of objects. Here the object or class may be an idea, physical countable object (or class), or physical uncountable substance (or class). - - requireChild - - - # - - takesValue - - - valueClass - textClass - - - - - Label - A string of 20 or fewer characters identifying something. Labels usually refer to general classes of things while IDs refer to specific instances. A term that is associated with some entity. A brief description given for purposes of identification. An identifying or descriptive marker that is attached to an object. - - requireChild - - - # - - takesValue - - - valueClass - nameClass - - - - - Metadata - Data about data. Information that describes another set of data. - - CogAtlas - The Cognitive Atlas ID number of something. - - # - - takesValue - - - - - CogPo - The CogPO ID number of something. - - # - - takesValue - - - - - Creation-date - The date on which data creation of this element began. - - requireChild - - - # - - takesValue - - - valueClass - dateTimeClass - - - - - Experimental-note - A brief written record about the experiment. - - # - - takesValue - - - valueClass - textClass - - - - - Library-name - Official name of a HED library. - - # - - takesValue - - - valueClass - nameClass - - - - - OBO-identifier - The identifier of a term in some Open Biology Ontology (OBO) ontology. - - # - - takesValue - - - valueClass - nameClass - - - - - Pathname - The specification of a node (file or directory) in a hierarchical file system, usually specified by listing the nodes top-down. - - # - - takesValue - - - - - Subject-identifier - A sequence of characters used to identify, name, or characterize a trial or study subject. - - # - - takesValue - - - - - Version-identifier - An alphanumeric character string that identifies a form or variant of a type or original. - - # - Usually is a semantic version. - - takesValue - - - - - - Parameter - Something user-defined for this experiment. - - Parameter-label - The name of the parameter. - - # - - takesValue - - - valueClass - nameClass - - - - - Parameter-value - The value of the parameter. - - # - - takesValue - - - valueClass - textClass - - - - - - - Organizational-property - Relating to an organization or the action of organizing something. - - Collection - A tag designating a grouping of items such as in a set or list. - - # - Name of the collection. - - takesValue - - - valueClass - nameClass - - - - - Condition-variable - An aspect of the experiment or task that is to be varied during the experiment. Task-conditions are sometimes called independent variables or contrasts. - - # - Name of the condition variable. - - takesValue - - - valueClass - nameClass - - - - - Control-variable - An aspect of the experiment that is fixed throughout the study and usually is explicitly controlled. - - # - Name of the control variable. - - takesValue - - - valueClass - nameClass - - - - - Def - A HED-specific utility tag used with a defined name to represent the tags associated with that definition. - - requireChild - - - # - Name of the definition. - - takesValue - - - valueClass - nameClass - - - - - Def-expand - A HED specific utility tag that is grouped with an expanded definition. The child value of the Def-expand is the name of the expanded definition. - - requireChild - - - tagGroup - - - # - - takesValue - - - valueClass - nameClass - - - - - Definition - A HED-specific utility tag whose child value is the name of the concept and the tag group associated with the tag is an English language explanation of a concept. - - requireChild - - - topLevelTagGroup - - - # - Name of the definition. - - takesValue - - - valueClass - nameClass - - - - - Event-context - A special HED tag inserted as part of a top-level tag group to contain information about the interrelated conditions under which the event occurs. The event context includes information about other events that are ongoing when this event happens. - - topLevelTagGroup - - - unique - - - - Event-stream - A special HED tag indicating that this event is a member of an ordered succession of events. - - # - Name of the event stream. - - takesValue - - - valueClass - nameClass - - - - - Experimental-intertrial - A tag used to indicate a part of the experiment between trials usually where nothing is happening. - - # - Optional label for the intertrial block. - - takesValue - - - valueClass - nameClass - - - - - Experimental-trial - Designates a run or execution of an activity, for example, one execution of a script. A tag used to indicate a particular organizational part in the experimental design often containing a stimulus-response pair or stimulus-response-feedback triad. - - # - Optional label for the trial (often a numerical string). - - takesValue - - - valueClass - nameClass - - - - - Indicator-variable - An aspect of the experiment or task that is measured as task conditions are varied during the experiment. Experiment indicators are sometimes called dependent variables. - - # - Name of the indicator variable. - - takesValue - - - valueClass - nameClass - - - - - Recording - A tag designating the data recording. Recording tags are usually have temporal scope which is the entire recording. - - # - Optional label for the recording. - - takesValue - - - valueClass - nameClass - - - - - Task - An assigned piece of work, usually with a time allotment. A tag used to indicate a linkage the structured activities performed as part of the experiment. - - # - Optional label for the task block. - - takesValue - - - valueClass - nameClass - - - - - Time-block - A tag used to indicate a contiguous time block in the experiment during which something is fixed or noted. - - # - Optional label for the task block. - - takesValue - - - valueClass - nameClass - - - - - - Sensory-property - Relating to sensation or the physical senses. - - Sensory-attribute - A sensory characteristic associated with another entity. - - Auditory-attribute - Pertaining to the sense of hearing. - - Loudness - Perceived intensity of a sound. - - # - - takesValue - - - valueClass - numericClass - nameClass - - - - - Pitch - A perceptual property that allows the user to order sounds on a frequency scale. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - frequencyUnits - - - - - Sound-envelope - Description of how a sound changes over time. - - Sound-envelope-attack - The time taken for initial run-up of level from nil to peak usually beginning when the key on a musical instrument is pressed. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Sound-envelope-decay - The time taken for the subsequent run down from the attack level to the designated sustain level. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Sound-envelope-release - The time taken for the level to decay from the sustain level to zero after the key is released. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - Sound-envelope-sustain - The time taken for the main sequence of the sound duration, until the key is released. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - timeUnits - - - - - - Timbre - The perceived sound quality of a singing voice or musical instrument. - - # - - takesValue - - - valueClass - nameClass - - - - - Sound-volume - The sound pressure level (SPL) usually the ratio to a reference signal estimated as the lower bound of hearing. - - # - - takesValue - - - valueClass - numericClass - - - unitClass - intensityUnits - - - - - - Gustatory-attribute - Pertaining to the sense of taste. - - Bitter - Having a sharp, pungent taste. - - - Salty - Tasting of or like salt. - - - Savory - Belonging to a taste that is salty or spicy rather than sweet. - - - Sour - Having a sharp, acidic taste. - - - Sweet - Having or resembling the taste of sugar. - - - - Olfactory-attribute - Having a smell. - - - Somatic-attribute - Pertaining to the feelings in the body or of the nervous system. - - Pain - The sensation of discomfort, distress, or agony, resulting from the stimulation of specialized nerve endings. - - - Stress - The negative mental, emotional, and physical reactions that occur when environmental stressors are perceived as exceeding the adaptive capacities of the individual. - - - - Tactile-attribute - Pertaining to the sense of touch. - - Tactile-pressure - Having a feeling of heaviness. - - - Tactile-temperature - Having a feeling of hotness or coldness. - - - Tactile-texture - Having a feeling of roughness. - - - Tactile-vibration - Having a feeling of mechanical oscillation. - - - - Vestibular-attribute - Pertaining to the sense of balance or body position. - - - Visual-attribute - Pertaining to the sense of sight. - - Color - The appearance of objects (or light sources) described in terms of perception of their hue and lightness (or brightness) and saturation. - - CSS-color - One of 140 colors supported by all browsers. For more details such as the color RGB or HEX values, check: https://www.w3schools.com/colors/colors_groups.asp. - - Blue-color - CSS color group. - - CadetBlue - CSS-color 0x5F9EA0. - - - SteelBlue - CSS-color 0x4682B4. - - - LightSteelBlue - CSS-color 0xB0C4DE. - - - LightBlue - CSS-color 0xADD8E6. - - - PowderBlue - CSS-color 0xB0E0E6. - - - LightSkyBlue - CSS-color 0x87CEFA. - - - SkyBlue - CSS-color 0x87CEEB. - - - CornflowerBlue - CSS-color 0x6495ED. - - - DeepSkyBlue - CSS-color 0x00BFFF. - - - DodgerBlue - CSS-color 0x1E90FF. - - - RoyalBlue - CSS-color 0x4169E1. - - - Blue - CSS-color 0x0000FF. - - - MediumBlue - CSS-color 0x0000CD. - - - DarkBlue - CSS-color 0x00008B. - - - Navy - CSS-color 0x000080. - - - MidnightBlue - CSS-color 0x191970. - - - - Brown-color - CSS color group. - - Cornsilk - CSS-color 0xFFF8DC. - - - BlanchedAlmond - CSS-color 0xFFEBCD. - - - Bisque - CSS-color 0xFFE4C4. - - - NavajoWhite - CSS-color 0xFFDEAD. - - - Wheat - CSS-color 0xF5DEB3. - - - BurlyWood - CSS-color 0xDEB887. - - - Tan - CSS-color 0xD2B48C. - - - RosyBrown - CSS-color 0xBC8F8F. - - - SandyBrown - CSS-color 0xF4A460. - - - GoldenRod - CSS-color 0xDAA520. - - - DarkGoldenRod - CSS-color 0xB8860B. - - - Peru - CSS-color 0xCD853F. - - - Chocolate - CSS-color 0xD2691E. - - - Olive - CSS-color 0x808000. - - - SaddleBrown - CSS-color 0x8B4513. - - - Sienna - CSS-color 0xA0522D. - - - Brown - CSS-color 0xA52A2A. - - - Maroon - CSS-color 0x800000. - - - - Cyan-color - CSS color group. - - Aqua - CSS-color 0x00FFFF. - - - Cyan - CSS-color 0x00FFFF. - - - LightCyan - CSS-color 0xE0FFFF. - - - PaleTurquoise - CSS-color 0xAFEEEE. - - - Aquamarine - CSS-color 0x7FFFD4. - - - Turquoise - CSS-color 0x40E0D0. - - - MediumTurquoise - CSS-color 0x48D1CC. - - - DarkTurquoise - CSS-color 0x00CED1. - - - - Green-color - CSS color group. - - GreenYellow - CSS-color 0xADFF2F. - - - Chartreuse - CSS-color 0x7FFF00. - - - LawnGreen - CSS-color 0x7CFC00. - - - Lime - CSS-color 0x00FF00. - - - LimeGreen - CSS-color 0x32CD32. - - - PaleGreen - CSS-color 0x98FB98. - - - LightGreen - CSS-color 0x90EE90. - - - MediumSpringGreen - CSS-color 0x00FA9A. - - - SpringGreen - CSS-color 0x00FF7F. - - - MediumSeaGreen - CSS-color 0x3CB371. - - - SeaGreen - CSS-color 0x2E8B57. - - - ForestGreen - CSS-color 0x228B22. - - - Green - CSS-color 0x008000. - - - DarkGreen - CSS-color 0x006400. - - - YellowGreen - CSS-color 0x9ACD32. - - - OliveDrab - CSS-color 0x6B8E23. - - - DarkOliveGreen - CSS-color 0x556B2F. - - - MediumAquaMarine - CSS-color 0x66CDAA. - - - DarkSeaGreen - CSS-color 0x8FBC8F. - - - LightSeaGreen - CSS-color 0x20B2AA. - - - DarkCyan - CSS-color 0x008B8B. - - - Teal - CSS-color 0x008080. - - - - Gray-color - CSS color group. - - Gainsboro - CSS-color 0xDCDCDC. - - - LightGray - CSS-color 0xD3D3D3. - - - Silver - CSS-color 0xC0C0C0. - - - DarkGray - CSS-color 0xA9A9A9. - - - DimGray - CSS-color 0x696969. - - - Gray - CSS-color 0x808080. - - - LightSlateGray - CSS-color 0x778899. - - - SlateGray - CSS-color 0x708090. - - - DarkSlateGray - CSS-color 0x2F4F4F. - - - Black - CSS-color 0x000000. - - - - Orange-color - CSS color group. - - Orange - CSS-color 0xFFA500. - - - DarkOrange - CSS-color 0xFF8C00. - - - Coral - CSS-color 0xFF7F50. - - - Tomato - CSS-color 0xFF6347. - - - OrangeRed - CSS-color 0xFF4500. - - - - Pink-color - CSS color group. - - Pink - CSS-color 0xFFC0CB. - - - LightPink - CSS-color 0xFFB6C1. - - - HotPink - CSS-color 0xFF69B4. - - - DeepPink - CSS-color 0xFF1493. - - - PaleVioletRed - CSS-color 0xDB7093. - - - MediumVioletRed - CSS-color 0xC71585. - - - - Purple-color - CSS color group. - - Lavender - CSS-color 0xE6E6FA. - - - Thistle - CSS-color 0xD8BFD8. - - - Plum - CSS-color 0xDDA0DD. - - - Orchid - CSS-color 0xDA70D6. - - - Violet - CSS-color 0xEE82EE. - - - Fuchsia - CSS-color 0xFF00FF. - - - Magenta - CSS-color 0xFF00FF. - - - MediumOrchid - CSS-color 0xBA55D3. - - - DarkOrchid - CSS-color 0x9932CC. - - - DarkViolet - CSS-color 0x9400D3. - - - BlueViolet - CSS-color 0x8A2BE2. - - - DarkMagenta - CSS-color 0x8B008B. - - - Purple - CSS-color 0x800080. - - - MediumPurple - CSS-color 0x9370DB. - - - MediumSlateBlue - CSS-color 0x7B68EE. - - - SlateBlue - CSS-color 0x6A5ACD. - - - DarkSlateBlue - CSS-color 0x483D8B. - - - RebeccaPurple - CSS-color 0x663399. - - - Indigo - CSS-color 0x4B0082. - - - - Red-color - CSS color group. - - LightSalmon - CSS-color 0xFFA07A. - - - Salmon - CSS-color 0xFA8072. - - - DarkSalmon - CSS-color 0xE9967A. - - - LightCoral - CSS-color 0xF08080. - - - IndianRed - CSS-color 0xCD5C5C. - - - Crimson - CSS-color 0xDC143C. - - - Red - CSS-color 0xFF0000. - - - FireBrick - CSS-color 0xB22222. - - - DarkRed - CSS-color 0x8B0000. - - - - Yellow-color - CSS color group. - - Gold - CSS-color 0xFFD700. - - - Yellow - CSS-color 0xFFFF00. - - - LightYellow - CSS-color 0xFFFFE0. - - - LemonChiffon - CSS-color 0xFFFACD. - - - LightGoldenRodYellow - CSS-color 0xFAFAD2. - - - PapayaWhip - CSS-color 0xFFEFD5. - - - Moccasin - CSS-color 0xFFE4B5. - - - PeachPuff - CSS-color 0xFFDAB9. - - - PaleGoldenRod - CSS-color 0xEEE8AA. - - - Khaki - CSS-color 0xF0E68C. - - - DarkKhaki - CSS-color 0xBDB76B. - - - - White-color - CSS color group. - - White - CSS-color 0xFFFFFF. - - - Snow - CSS-color 0xFFFAFA. - - - HoneyDew - CSS-color 0xF0FFF0. - - - MintCream - CSS-color 0xF5FFFA. - - - Azure - CSS-color 0xF0FFFF. - - - AliceBlue - CSS-color 0xF0F8FF. - - - GhostWhite - CSS-color 0xF8F8FF. - - - WhiteSmoke - CSS-color 0xF5F5F5. - - - SeaShell - CSS-color 0xFFF5EE. - - - Beige - CSS-color 0xF5F5DC. - - - OldLace - CSS-color 0xFDF5E6. - - - FloralWhite - CSS-color 0xFFFAF0. - - - Ivory - CSS-color 0xFFFFF0. - - - AntiqueWhite - CSS-color 0xFAEBD7. - - - Linen - CSS-color 0xFAF0E6. - - - LavenderBlush - CSS-color 0xFFF0F5. - - - MistyRose - CSS-color 0xFFE4E1. - - - - - Color-shade - A slight degree of difference between colors, especially with regard to how light or dark it is or as distinguished from one nearly like it. - - Dark-shade - A color tone not reflecting much light. - - - Light-shade - A color tone reflecting more light. - - - - Grayscale - Using a color map composed of shades of gray, varying from black at the weakest intensity to white at the strongest. - - # - White intensity between 0 and 1. - - takesValue - - - valueClass - numericClass - - - - - HSV-color - A color representation that models how colors appear under light. - - Hue - Attribute of a visual sensation according to which an area appears to be similar to one of the perceived colors. - - # - Angular value between 0 and 360. - - takesValue - - - valueClass - numericClass - - - - - Saturation - Colorfulness of a stimulus relative to its own brightness. - - # - B value of RGB between 0 and 1. - - takesValue - - - valueClass - numericClass - - - - - HSV-value - An attribute of a visual sensation according to which an area appears to emit more or less light. - - # - - takesValue - - - valueClass - numericClass - - - - - - RGB-color - A color from the RGB schema. - - RGB-red - The red component. - - # - R value of RGB between 0 and 1. - - takesValue - - - valueClass - numericClass - - - - - RGB-blue - The blue component. - - # - B value of RGB between 0 and 1. - - takesValue - - - valueClass - numericClass - - - - - RGB-green - The green component. - - # - G value of RGB between 0 and 1. - - takesValue - - - valueClass - numericClass - - - - - - - Luminance - A quality that exists by virtue of the luminous intensity per unit area projected in a given direction. - - - Opacity - A measure of impenetrability to light. - - - - - Sensory-presentation - The entity has a sensory manifestation. - - Auditory-presentation - The sense of hearing is used in the presentation to the user. - - Loudspeaker-separation - The distance between two loudspeakers. Grouped with the Distance tag. - - suggestedTag - Distance - - - - Monophonic - Relating to sound transmission, recording, or reproduction involving a single transmission path. - - - Silent - The absence of ambient audible sound or the state of having ceased to produce sounds. - - - Stereophonic - Relating to, or constituting sound reproduction involving the use of separated microphones and two transmission channels to achieve the sound separation of a live hearing. - - - - Gustatory-presentation - The sense of taste used in the presentation to the user. - - - Olfactory-presentation - The sense of smell used in the presentation to the user. - - - Somatic-presentation - The nervous system is used in the presentation to the user. - - - Tactile-presentation - The sense of touch used in the presentation to the user. - - - Vestibular-presentation - The sense balance used in the presentation to the user. - - - Visual-presentation - The sense of sight used in the presentation to the user. - - 2D-view - A view showing only two dimensions. - - - 3D-view - A view showing three dimensions. - - - Background-view - Parts of the view that are farthest from the viewer and usually the not part of the visual focus. - - - Bistable-view - Something having two stable visual forms that have two distinguishable stable forms as in optical illusions. - - - Foreground-view - Parts of the view that are closest to the viewer and usually the most important part of the visual focus. - - - Foveal-view - Visual presentation directly on the fovea. A view projected on the small depression in the retina containing only cones and where vision is most acute. - - - Map-view - A diagrammatic representation of an area of land or sea showing physical features, cities, roads. - - Aerial-view - Elevated view of an object from above, with a perspective as though the observer were a bird. - - - Satellite-view - A representation as captured by technology such as a satellite. - - - Street-view - A 360-degrees panoramic view from a position on the ground. - - - - Peripheral-view - Indirect vision as it occurs outside the point of fixation. - - - - - - Task-property - Something that pertains to a task. - - extensionAllowed - - - Task-attentional-demand - Strategy for allocating attention toward goal-relevant information. - - Bottom-up-attention - Attentional guidance purely by externally driven factors to stimuli that are salient because of their inherent properties relative to the background. Sometimes this is referred to as stimulus driven. - - relatedTag - Top-down-attention - - - - Covert-attention - Paying attention without moving the eyes. - - relatedTag - Overt-attention - - - - Divided-attention - Integrating parallel multiple stimuli. Behavior involving responding simultaneously to multiple tasks or multiple task demands. - - relatedTag - Focused-attention - - - - Focused-attention - Responding discretely to specific visual, auditory, or tactile stimuli. - - relatedTag - Divided-attention - - - - Orienting-attention - Directing attention to a target stimulus. - - - Overt-attention - Selectively processing one location over others by moving the eyes to point at that location. - - relatedTag - Covert-attention - - - - Selective-attention - Maintaining a behavioral or cognitive set in the face of distracting or competing stimuli. Ability to pay attention to a limited array of all available sensory information. - - - Sustained-attention - Maintaining a consistent behavioral response during continuous and repetitive activity. - - - Switched-attention - Having to switch attention between two or more modalities of presentation. - - - Top-down-attention - Voluntary allocation of attention to certain features. Sometimes this is referred to goal-oriented attention. - - relatedTag - Bottom-up-attention - - - - - Task-effect-evidence - The evidence supporting the conclusion that the event had the specified effect. - - Computational-evidence - A type of evidence in which data are produced, and/or generated, and/or analyzed on a computer. - - - External-evidence - A phenomenon that follows and is caused by some previous phenomenon. - - - Intended-effect - A phenomenon that is intended to follow and be caused by some previous phenomenon. - - - Behavioral-evidence - An indication or conclusion based on the behavior of an agent. - - - - Task-event-role - The purpose of an event with respect to the task. - - Experimental-stimulus - Part of something designed to elicit a response in the experiment. - - - Incidental - A sensory or other type of event that is unrelated to the task or experiment. - - - Instructional - Usually associated with a sensory event intended to give instructions to the participant about the task or behavior. - - - Mishap - Unplanned disruption such as an equipment or experiment control abnormality or experimenter error. - - - Participant-response - Something related to a participant actions in performing the task. - - - Task-activity - Something that is part of the overall task or is necessary to the overall experiment but is not directly part of a stimulus-response cycle. Examples would be taking a survey or provided providing a silva sample. - - - Warning - Something that should warn the participant that the parameters of the task have been or are about to be exceeded such as a warning message about getting too close to the shoulder of the road in a driving task. - - - - Task-action-type - How an agent action should be interpreted in terms of the task specification. - - Appropriate-action - An action suitable or proper in the circumstances. - - relatedTag - Inappropriate-action - - - - Correct-action - An action that was a correct response in the context of the task. - - relatedTag - Incorrect-action - Indeterminate-action - - - - Correction - An action offering an improvement to replace a mistake or error. - - - Done-indication - An action that indicates that the participant has completed this step in the task. - - relatedTag - Ready-indication - - - - Incorrect-action - An action considered wrong or incorrect in the context of the task. - - relatedTag - Correct-action - Indeterminate-action - - - - Imagined-action - Form a mental image or concept of something. This is used to identity something that only happened in the imagination of the participant as in imagined movements in motor imagery paradigms. - - - Inappropriate-action - An action not in keeping with what is correct or proper for the task. - - relatedTag - Appropriate-action - - - - Indeterminate-action - An action that cannot be distinguished between two or more possibibities in the current context. This tag might be applied when an outside evaluator or a classification algorithm cannot determine a definitive result. - - relatedTag - Correct-action - Incorrect-action - Miss - Near-miss - - - - Omitted-action - An expected response was skipped. - - - Miss - An action considered to be a failure in the context of the task. For example, if the agent is supposed to try to hit a target and misses. - - relatedTag - Near-miss - - - - Near-miss - An action barely satisfied the requirements of the task. In a driving experiment for example this could pertain to a narrowly avoided collision or other accident. - - relatedTag - Miss - - - - Ready-indication - An action that indicates that the participant is ready to perform the next step in the task. - - relatedTag - Done-indication - - - - - Task-relationship - Specifying organizational importance of sub-tasks. - - Background-subtask - A part of the task which should be performed in the background as for example inhibiting blinks due to instruction while performing the primary task. - - - Primary-subtask - A part of the task which should be the primary focus of the participant. - - - - Task-stimulus-role - The role the stimulus plays in the task. - - Cue - A signal for an action, a pattern of stimuli indicating a particular response. - - - Distractor - A person or thing that distracts or a plausible but incorrect option in a multiple-choice question. In pyschological studies this is sometimes referred to as a foil. - - - Expected - Considered likely, probable or anticipated. Something of low information value as in frequent non-targets in an RSVP paradigm. - - relatedTag - Unexpected - - - suggestedTag - Target - - - - Extraneous - Irrelevant or unrelated to the subject being dealt with. - - - Feedback - An evaluative response to an inquiry, process, event, or activity. - - - Go-signal - An indicator to proceed with a planned action. - - relatedTag - Stop-signal - - - - Meaningful - Conveying significant or relevant information. - - - Newly-learned - Representing recently acquired information or understanding. - - - Non-informative - Something that is not useful in forming an opinion or judging an outcome. - - - Non-target - Something other than that done or looked for. Also tag Expected if the Non-target is frequent. - - relatedTag - Target - - - - Not-meaningful - Not having a serious, important, or useful quality or purpose. - - - Novel - Having no previous example or precedent or parallel. - - - Oddball - Something unusual, or infrequent. - - relatedTag - Unexpected - - - suggestedTag - Target - - - - Planned - Something that was decided on or arranged in advance. - - relatedTag - Unplanned - - - - Penalty - A disadvantage, loss, or hardship due to some action. - - - Priming - An implicit memory effect in which exposure to a stimulus influences response to a later stimulus. - - - Query - A sentence of inquiry that asks for a reply. - - - Reward - A positive reinforcement for a desired action, behavior or response. - - - Stop-signal - An indicator that the agent should stop the current activity. - - relatedTag - Go-signal - - - - Target - Something fixed as a goal, destination, or point of examination. - - - Threat - An indicator that signifies hostility and predicts an increased probability of attack. - - - Timed - Something planned or scheduled to be done at a particular time or lasting for a specified amount of time. - - - Unexpected - Something that is not anticipated. - - relatedTag - Expected - - - - Unplanned - Something that has not been planned as part of the task. - - relatedTag - Planned - - - - - - - Relation - Concerns the way in which two or more people or things are connected. - - extensionAllowed - - - Comparative-relation - Something considered in comparison to something else. The first entity is the focus. - - Approximately-equal-to - (A, (Approximately-equal-to, B)) indicates that A and B have almost the same value. Here A and B could refer to sizes, orders, positions or other quantities. - - - Less-than - (A, (Less-than, B)) indicates that A is smaller than B. Here A and B could refer to sizes, orders, positions or other quantities. - - - Less-than-or-equal-to - (A, (Less-than-or-equal-to, B)) indicates that the relative size or order of A is smaller than or equal to B. - - - Greater-than - (A, (Greater-than, B)) indicates that the relative size or order of A is bigger than that of B. - - - Greater-than-or-equal-to - (A, (Greater-than-or-equal-to, B)) indicates that the relative size or order of A is bigger than or the same as that of B. - - - Equal-to - (A, (Equal-to, B)) indicates that the size or order of A is the same as that of B. - - - Not-equal-to - (A, (Not-equal-to, B)) indicates that the size or order of A is not the same as that of B. - - - - Connective-relation - Indicates two entities are related in some way. The first entity is the focus. - - Belongs-to - (A, (Belongs-to, B)) indicates that A is a member of B. - - - Connected-to - (A, (Connected-to, B)) indicates that A is related to B in some respect, usually through a direct link. - - - Contained-in - (A, (Contained-in, B)) indicates that A is completely inside of B. - - - Described-by - (A, (Described-by, B)) indicates that B provides information about A. - - - From-to - (A, (From-to, B)) indicates a directional relation from A to B. A is considered the source. - - - Group-of - (A, (Group-of, B)) indicates A is a group of items of type B. - - - Implied-by - (A, (Implied-by, B)) indicates B is suggested by A. - - - Includes - (A, (Includes, B)) indicates that A has B as a member or part. - - - Interacts-with - (A, (Interacts-with, B)) indicates A and B interact, possibly reciprocally. - - - Member-of - (A, (Member-of, B)) indicates A is a member of group B. - - - Part-of - (A, (Part-of, B)) indicates A is a part of the whole B. - - - Performed-by - (A, (Performed-by, B)) indicates that the action or procedure A was carried out by agent B. - - - Performed-using - (A, (Performed-using, B)) indicates that the action or procedure A was accomplished using B. - - - Related-to - (A, (Related-to, B)) indicates A has some relationship to B. - - - Unrelated-to - (A, (Unrelated-to, B)) indicates that A is not related to B. For example, A is not related to Task. - - - - Directional-relation - A relationship indicating direction of change of one entity relative to another. The first entity is the focus. - - Away-from - (A, (Away-from, B)) indicates that A is going or has moved away from B. The meaning depends on A and B. - - - Towards - (A, (Towards, B)) indicates that A is going to or has moved to B. The meaning depends on A and B. - - - - Logical-relation - Indicating a logical relationship between entities. The first entity is usually the focus. - - And - (A, (And, B)) means A and B are both in effect. - - - Or - (A, (Or, B)) means at least one of A and B are in effect. - - - - Spatial-relation - Indicating a relationship about position between entities. - - Above - (A, (Above, B)) means A is in a place or position that is higher than B. - - - Across-from - (A, (Across-from, B)) means A is on the opposite side of something from B. - - - Adjacent-to - (A, (Adjacent-to, B)) indicates that A is next to B in time or space. - - - Ahead-of - (A, (Ahead-of, B)) indicates that A is further forward in time or space in B. - - - Around - (A, (Around, B)) means A is in or near the present place or situation of B. - - - Behind - (A, (Behind, B)) means A is at or to the far side of B, typically so as to be hidden by it. - - - Below - (A, (Below, B)) means A is in a place or position that is lower than the position of B. - - - Between - (A, (Between, (B, C))) means A is in the space or interval separating B and C. - - - Bilateral-to - (A, (Bilateral, B)) means A is on both sides of B or affects both sides of B. - - - Bottom-edge-of - (A, (Bottom-edge-of, B)) means A is on the bottom most part or or near the boundary of B. - - relatedTag - Left-edge-of - Right-edge-of - Top-edge-of - - - - Boundary-of - (A, (Boundary-of, B)) means A is on or part of the edge or boundary of B. - - - Center-of - (A, (Center-of, B)) means A is at a point or or in an area that is approximately central within B. - - - Close-to - (A, (Close-to, B)) means A is at a small distance from or is located near in space to B. - - - Far-from - (A, (Far-from, B)) means A is at a large distance from or is not located near in space to B. - - - In-front-of - (A, (In-front-of, B)) means A is in a position just ahead or at the front part of B, potentially partially blocking B from view. - - - Left-edge-of - (A, (Left-edge-of, B)) means A is located on the left side of B on or near the boundary of B. - - relatedTag - Bottom-edge-of - Right-edge-of - Top-edge-of - - - - Left-side-of - (A, (Left-side-of, B)) means A is located on the left side of B usually as part of B. - - relatedTag - Right-side-of - - - - Lower-center-of - (A, (Lower-center-of, B)) means A is situated on the lower center part of B (due south). This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-left-of - Lower-right-of - Upper-center-of - Upper-right-of - - - - Lower-left-of - (A, (Lower-left-of, B)) means A is situated on the lower left part of B. This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-center-of - Lower-right-of - Upper-center-of - Upper-left-of - Upper-right-of - - - - Lower-right-of - (A, (Lower-right-of, B)) means A is situated on the lower right part of B. This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-center-of - Lower-left-of - Upper-left-of - Upper-center-of - Upper-left-of - Lower-right-of - - - - Outside-of - (A, (Outside-of, B)) means A is located in the space around but not including B. - - - Over - (A, (Over, B)) means A above is above B so as to cover or protect or A extends over the a general area as from a from a vantage point. - - - Right-edge-of - (A, (Right-edge-of, B)) means A is located on the right side of B on or near the boundary of B. - - relatedTag - Bottom-edge-of - Left-edge-of - Top-edge-of - - - - Right-side-of - (A, (Right-side-of, B)) means A is located on the right side of B usually as part of B. - - relatedTag - Left-side-of - - - - To-left-of - (A, (To-left-of, B)) means A is located on or directed toward the side to the west of B when B is facing north. This term is used when A is not part of B. - - - To-right-of - (A, (To-right-of, B)) means A is located on or directed toward the side to the east of B when B is facing north. This term is used when A is not part of B. - - - Top-edge-of - (A, (Top-edge-of, B)) means A is on the uppermost part or or near the boundary of B. - - relatedTag - Left-edge-of - Right-edge-of - Bottom-edge-of - - - - Top-of - (A, (Top-of, B)) means A is on the uppermost part, side, or surface of B. - - - Upper-center-of - (A, (Upper-center-of, B)) means A is situated on the upper center part of B (due north). This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-center-of - Lower-left-of - Lower-right-of - Upper-center-of - Upper-right-of - - - - Upper-left-of - (A, (Upper-left-of, B)) means A is situated on the upper left part of B. This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-center-of - Lower-left-of - Lower-right-of - Upper-center-of - Upper-right-of - - - - Upper-right-of - (A, (Upper-right-of, B)) means A is situated on the upper right part of B. This relation is often used to specify qualitative information about screen position. - - relatedTag - Center-of - Lower-center-of - Lower-left-of - Upper-left-of - Upper-center-of - Lower-right-of - - - - Underneath - (A, (Underneath, B)) means A is situated directly below and may be concealed by B. - - - Within - (A, (Within, B)) means A is on the inside of or contained in B. - - - - Temporal-relation - A relationship that includes a temporal or time-based component. - - After - (A, (After B)) means A happens at a time subsequent to a reference time related to B. - - - Asynchronous-with - (A, (Asynchronous-with, B)) means A happens at times not occurring at the same time or having the same period or phase as B. - - - Before - (A, (Before B)) means A happens at a time earlier in time or order than B. - - - During - (A, (During, B)) means A happens at some point in a given period of time in which B is ongoing. - - - Synchronous-with - (A, (Synchronous-with, B)) means A happens at occurs at the same time or rate as B. - - - Waiting-for - (A, (Waiting-for, B)) means A pauses for something to happen in B. - - - - - - - accelerationUnits - - defaultUnits - m-per-s^2 - - - m-per-s^2 - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - angleUnits - - defaultUnits - radian - - - radian - - SIUnit - - - conversionFactor - 1.0 - - - - rad - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - degree - - conversionFactor - 0.0174533 - - - - - areaUnits - - defaultUnits - m^2 - - - m^2 - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - currencyUnits - Units indicating the worth of something. - - defaultUnits - $ - - - dollar - - conversionFactor - 1.0 - - - - $ - - unitPrefix - - - unitSymbol - - - conversionFactor - 1.0 - - - - euro - - - point - - - - electricPotentialUnits - - defaultUnits - uv - - - v - - SIUnit - - - unitSymbol - - - conversionFactor - 0.000001 - - - - Volt - - SIUnit - - - conversionFactor - 0.000001 - - - - - frequencyUnits - - defaultUnits - Hz - - - hertz - - SIUnit - - - conversionFactor - 1.0 - - - - Hz - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - intensityUnits - - defaultUnits - dB - - - dB - Intensity expressed as ratio to a threshold. May be used for sound intensity. - - unitSymbol - - - conversionFactor - 1.0 - - - - candela - Units used to express light intensity. - - SIUnit - - - - cd - Units used to express light intensity. - - SIUnit - - - unitSymbol - - - - - jerkUnits - - defaultUnits - m-per-s^3 - - - m-per-s^3 - - unitSymbol - - - conversionFactor - 1.0 - - - - - magneticFieldUnits - Units used to magnetic field intensity. - - defaultUnits - fT - - - tesla - - SIUnit - - - conversionFactor - 10^-15 - - - - T - - SIUnit - - - unitSymbol - - - conversionFactor - 10^-15 - - - - - memorySizeUnits - - defaultUnits - B - - - byte - - SIUnit - - - conversionFactor - 1.0 - - - - B - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - physicalLengthUnits - - defaultUnits - m - - - foot - - conversionFactor - 0.3048 - - - - inch - - conversionFactor - 0.0254 - - - - metre - - SIUnit - - - conversionFactor - 1.0 - - - - m - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - mile - - conversionFactor - 1609.34 - - - - - speedUnits - - defaultUnits - m-per-s - - - m-per-s - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - mph - - unitSymbol - - - conversionFactor - 0.44704 - - - - kph - - unitSymbol - - - conversionFactor - 0.277778 - - - - - temperatureUnits - - degree Celsius - - SIUnit - - - conversionFactor - 1.0 - - - - oC - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - timeUnits - - defaultUnits - s - - - second - - SIUnit - - - conversionFactor - 1.0 - - - - s - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - day - - conversionFactor - 86400 - - - - minute - - conversionFactor - 60 - - - - hour - Should be in 24-hour format. - - conversionFactor - 3600 - - - - - volumeUnits - - defaultUnits - m^3 - - - m^3 - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - - weightUnits - - defaultUnits - g - - - g - - SIUnit - - - unitSymbol - - - conversionFactor - 1.0 - - - - gram - - SIUnit - - - conversionFactor - 1.0 - - - - pound - - conversionFactor - 453.592 - - - - lb - - conversionFactor - 453.592 - - - - - - - deca - SI unit multiple representing 10^1. - - SIUnitModifier - - - conversionFactor - 10.0 - - - - da - SI unit multiple representing 10^1. - - SIUnitSymbolModifier - - - conversionFactor - 10.0 - - - - hecto - SI unit multiple representing 10^2. - - SIUnitModifier - - - conversionFactor - 100.0 - - - - h - SI unit multiple representing 10^2. - - SIUnitSymbolModifier - - - conversionFactor - 100.0 - - - - kilo - SI unit multiple representing 10^3. - - SIUnitModifier - - - conversionFactor - 1000.0 - - - - k - SI unit multiple representing 10^3. - - SIUnitSymbolModifier - - - conversionFactor - 1000.0 - - - - mega - SI unit multiple representing 10^6. - - SIUnitModifier - - - conversionFactor - 10^6 - - - - M - SI unit multiple representing 10^6. - - SIUnitSymbolModifier - - - conversionFactor - 10^6 - - - - giga - SI unit multiple representing 10^9. - - SIUnitModifier - - - conversionFactor - 10^9 - - - - G - SI unit multiple representing 10^9. - - SIUnitSymbolModifier - - - conversionFactor - 10^9 - - - - tera - SI unit multiple representing 10^12. - - SIUnitModifier - - - conversionFactor - 10^12 - - - - T - SI unit multiple representing 10^12. - - SIUnitSymbolModifier - - - conversionFactor - 10^12 - - - - peta - SI unit multiple representing 10^15. - - SIUnitModifier - - - conversionFactor - 10^15 - - - - P - SI unit multiple representing 10^15. - - SIUnitSymbolModifier - - - conversionFactor - 10^15 - - - - exa - SI unit multiple representing 10^18. - - SIUnitModifier - - - conversionFactor - 10^18 - - - - E - SI unit multiple representing 10^18. - - SIUnitSymbolModifier - - - conversionFactor - 10^18 - - - - zetta - SI unit multiple representing 10^21. - - SIUnitModifier - - - conversionFactor - 10^21 - - - - Z - SI unit multiple representing 10^21. - - SIUnitSymbolModifier - - - conversionFactor - 10^21 - - - - yotta - SI unit multiple representing 10^24. - - SIUnitModifier - - - conversionFactor - 10^24 - - - - Y - SI unit multiple representing 10^24. - - SIUnitSymbolModifier - - - conversionFactor - 10^24 - - - - deci - SI unit submultiple representing 10^-1. - - SIUnitModifier - - - conversionFactor - 0.1 - - - - d - SI unit submultiple representing 10^-1. - - SIUnitSymbolModifier - - - conversionFactor - 0.1 - - - - centi - SI unit submultiple representing 10^-2. - - SIUnitModifier - - - conversionFactor - 0.01 - - - - c - SI unit submultiple representing 10^-2. - - SIUnitSymbolModifier - - - conversionFactor - 0.01 - - - - milli - SI unit submultiple representing 10^-3. - - SIUnitModifier - - - conversionFactor - 0.001 - - - - m - SI unit submultiple representing 10^-3. - - SIUnitSymbolModifier - - - conversionFactor - 0.001 - - - - micro - SI unit submultiple representing 10^-6. - - SIUnitModifier - - - conversionFactor - 10^-6 - - - - u - SI unit submultiple representing 10^-6. - - SIUnitSymbolModifier - - - conversionFactor - 10^-6 - - - - nano - SI unit submultiple representing 10^-9. - - SIUnitModifier - - - conversionFactor - 10^-9 - - - - n - SI unit submultiple representing 10^-9. - - SIUnitSymbolModifier - - - conversionFactor - 10^-9 - - - - pico - SI unit submultiple representing 10^-12. - - SIUnitModifier - - - conversionFactor - 10^-12 - - - - p - SI unit submultiple representing 10^-12. - - SIUnitSymbolModifier - - - conversionFactor - 10^-12 - - - - femto - SI unit submultiple representing 10^-15. - - SIUnitModifier - - - conversionFactor - 10^-15 - - - - f - SI unit submultiple representing 10^-15. - - SIUnitSymbolModifier - - - conversionFactor - 10^-15 - - - - atto - SI unit submultiple representing 10^-18. - - SIUnitModifier - - - conversionFactor - 10^-18 - - - - a - SI unit submultiple representing 10^-18. - - SIUnitSymbolModifier - - - conversionFactor - 10^-18 - - - - zepto - SI unit submultiple representing 10^-21. - - SIUnitModifier - - - conversionFactor - 10^-21 - - - - z - SI unit submultiple representing 10^-21. - - SIUnitSymbolModifier - - - conversionFactor - 10^-21 - - - - yocto - SI unit submultiple representing 10^-24. - - SIUnitModifier - - - conversionFactor - 10^-24 - - - - y - SI unit submultiple representing 10^-24. - - SIUnitSymbolModifier - - - conversionFactor - 10^-24 - - - - - - dateTimeClass - Date-times should conform to ISO8601 date-time format YYYY-MM-DDThh:mm:ss. Any variation on the full form is allowed. - - allowedCharacter - digits - T - - - : - - - - nameClass - Value class designating values that have the characteristics of node names. The allowed characters are alphanumeric, hyphen, and underbar. - - allowedCharacter - letters - digits - _ - - - - - - numericClass - Value must be a valid numerical value. - - allowedCharacter - digits - E - e - + - - - . - - - - posixPath - Posix path specification. - - allowedCharacter - digits - letters - / - : - - - - textClass - Value class designating values that have the characteristics of text such as in descriptions. - - allowedCharacter - letters - digits - blank - + - - - : - ; - . - / - ( - ) - ? - * - % - $ - @ - - - - - - allowedCharacter - A schema attribute of value classes specifying a special character that is allowed in expressing the value of a placeholder. Normally the allowed characters are listed individually. However, the word letters designates the upper and lower case alphabetic characters and the word digits designates the digits 0-9. The word blank designates the blank character. - - valueClassProperty - - - - conversionFactor - The multiplicative factor to multiply these units to convert to default units. - - unitProperty - - - unitModifierProperty - - - - deprecated - This tag is out of date and should no longer be used. - - boolProperty - - - - defaultUnits - A schema attribute of unit classes specifying the default units to use if the placeholder has a unit class but the substituted value has no units. - - unitClassProperty - - - - extensionAllowed - A schema attribute indicating that users can add unlimited levels of child nodes under this tag. This tag is propagated to child nodes with the exception of the hashtag placeholders. - - boolProperty - - - - recommended - A schema attribute indicating that the event-level HED string should include this tag. - - boolProperty - - - - relatedTag - A schema attribute suggesting HED tags that are closely related to this tag. This attribute is used by tagging tools. - - - requireChild - A schema attribute indicating that one of the node elements descendants must be included when using this tag. - - boolProperty - - - - required - A schema attribute indicating that every event-level HED string should include this tag. - - boolProperty - - - - SIUnit - A schema attribute indicating that this unit element is an SI unit and can be modified by multiple and submultiple names. Note that some units such as byte are designated as SI units although they are not part of the standard. - - boolProperty - - - unitProperty - - - - SIUnitModifier - A schema attribute indicating that this SI unit modifier represents a multiple or submultiple of a base unit rather than a unit symbol. - - boolProperty - - - unitModifierProperty - - - - SIUnitSymbolModifier - A schema attribute indicating that this SI unit modifier represents a multiple or submultiple of a unit symbol rather than a base symbol. - - boolProperty - - - unitModifierProperty - - - - suggestedTag - A schema attribute that indicates another tag that is often associated with this tag. This attribute is used by tagging tools to provide tagging suggestions. - - - tagGroup - A schema attribute indicating the tag can only appear inside a tag group. - - boolProperty - - - - takesValue - A schema attribute indicating the tag is a hashtag placeholder that is expected to be replaced with a user-defined value. - - boolProperty - - - - topLevelTagGroup - A schema attribute indicating that this tag (or its descendants) can only appear in a top-level tag group. A tag group can have at most one tag with this attribute. - - boolProperty - - - - unique - A schema attribute indicating that only one of this tag or its descendants can be used in the event-level HED string. - - boolProperty - - - - unitClass - A schema attribute specifying which unit class this value tag belongs to. - - - unitPrefix - A schema attribute applied specifically to unit elements to designate that the unit indicator is a prefix (e.g., dollar sign in the currency units). - - boolProperty - - - unitProperty - - - - unitSymbol - A schema attribute indicating this tag is an abbreviation or symbol representing a type of unit. Unit symbols represent both the singular and the plural and thus cannot be pluralized. - - boolProperty - - - unitProperty - - - - valueClass - A schema attribute specifying which value class this value tag belongs to. - - - - - boolProperty - Indicates that the schema attribute represents something that is either true or false and does not have a value. Attributes without this value are assumed to have string values. - - - unitClassProperty - Indicates that the schema attribute is meant to be applied to unit classes. - - - unitModifierProperty - Indicates that the schema attribute is meant to be applied to unit modifier classes. - - - unitProperty - Indicates that the schema attribute is meant to be applied to units within a unit class. - - - valueClassProperty - Indicates that the schema attribute is meant to be applied to value classes. - - - This is an updated version of the schema format. The properties are now part of the schema. The schema attributes are designed to be checked in software rather than hard-coded. The schema attributes, themselves have properties. - - - diff --git a/tests/test_summarize_testdata.py b/tests/test_summarize_testdata.py new file mode 100644 index 00000000..9ccb23b1 --- /dev/null +++ b/tests/test_summarize_testdata.py @@ -0,0 +1,67 @@ +import os +import json +import unittest + + +class MyTestCase(unittest.TestCase): + @classmethod + def setUpClass(cls): + test_dir = os.path.realpath(os.path.join(os.path.dirname(os.path.realpath(__file__)), + '../docs/source/_static/data/error_tests')) + cls.test_files = [os.path.join(test_dir, f) for f in os.listdir(test_dir) + if os.path.isfile(os.path.join(test_dir, f))] + + @staticmethod + def get_test_info(test_file, details=True): + indent = " " + with open(test_file, "r") as fp: + test_info = json.load(fp) + out_list = [f"{test_info[0]['error_code']}"] + for info in test_info: + out_list.append(f"\n{indent}{info['description']}") + out_list.append(f"{indent}HED {info['schema']}") + out_list.append(f"{indent}Definitions:") + for defs in info["definitions"]: + out_list.append(f"{indent*2}{defs}") + if "string_tests" in info["tests"]: + out_list = out_list + MyTestCase.get_test_details(info["tests"]["string_tests"], "string_tests", indent) + if "sidecar_tests" in info["tests"]: + out_list = out_list + \ + MyTestCase.get_test_details(info["tests"]["sidecar_tests"], "sidecar_tests", indent) + if "event_tests" in info["tests"]: + out_list = out_list + \ + MyTestCase.get_test_details(info["tests"]["event_tests"], "event_tests", indent) + return "\n".join(out_list) + + @staticmethod + def get_test_details(test_item, title, indent, details=True): + num_fail_tests = len(test_item.get("fails", 0)) + num_pass_tests = len(test_item.get("passes", 0)) + detail_list = [f"{indent*2}{title}: fail_tests={num_fail_tests} pass_tests={num_pass_tests}"] + if num_fail_tests > 0: + detail_list.append(f"{indent*3}fail_tests:") + for test in test_item["fails"]: + detail_list.append(f"{indent*4}{test}") + if num_pass_tests > 0: + detail_list.append(f"{indent * 3}pass_tests:") + for test in test_item["passes"]: + detail_list.append(f"{indent * 4}{test}") + return detail_list + + def test_summary(self): + for test_file in self.test_files: + out_str = self.get_test_info(test_file) + print(out_str) + self.assertEqual(True, True) # add assertion here + + def test_summary_full(self): + for test_file in self.test_files: + print(test_file) + out_str = self.get_test_info(test_file, details=True) + print(out_str + '\n') + + self.assertEqual(True, True) # add assertion here + + +if __name__ == '__main__': + unittest.main()