diff --git a/docs/source/03_HED_formats.md b/docs/source/03_HED_formats.md index ad3bde5..bc8600b 100644 --- a/docs/source/03_HED_formats.md +++ b/docs/source/03_HED_formats.md @@ -835,11 +835,11 @@ 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. +Note, however, that transforming from a `Def` tag to a `Def-expand` group requires the definition, +while transforming from a `Def-expand` group to `Def` tag does not. For definitions that include a placeholder, a value must be substituted for -the `#` placeholder in `Def` and `Def-expand-group` when final +the `#` placeholder in `Def` tag and `Def-expand` group when final annotation assembly occurs. See [**DEF_INVALID**](./Appendix_B.md#def_invalid) and @@ -855,17 +855,17 @@ 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. +`Def` tag 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. +`Onset` group with the same `Def` tag or `Def-expand` group anchor. -The `Onset` tag group may only contain its `Def` or `Def-expand-group` anchor and +The `Onset` tag group may only contain its `Def` tag 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 +The `Offset` tag group may only contain its `Def` tag or `Def-expand` group anchor in addition to the `Offset` tag. These requirements imply that `Onset` and `Offset` must be the only tags diff --git a/docs/source/05_Advanced_annotation.md b/docs/source/05_Advanced_annotation.md index 43e66aa..f255884 100644 --- a/docs/source/05_Advanced_annotation.md +++ b/docs/source/05_Advanced_annotation.md @@ -398,7 +398,7 @@ the same as the value used for its `Onset`. `````` -### 5.3.2. Using `Duration` +### 5.3.3. 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. @@ -468,7 +468,7 @@ neural response, which is the case for many events involving visual or auditory The use of the `Duration` tag will not be fully supported by validators until HED standard schema version 8.2.0. -### 5.3.3. Using `Delay` +### 5.3.4. Using `Delay` 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. diff --git a/docs/source/07_Library_schemas.md b/docs/source/07_Library_schemas.md index 5d79371..6e9e8d7 100644 --- a/docs/source/07_Library_schemas.md +++ b/docs/source/07_Library_schemas.md @@ -90,7 +90,7 @@ which may be useful for debugging, but is usually not explicitly created. The following table summarizes the different partnered library schema formats and their uses. File names and link examples are specifically for the SCORE -library. For other libraries, substitue the library name for the word *score*. +library. For other libraries, substitute the library name for the word *score*. | Format | Merged
status | Canonical filename | Handling | | ------ | ------------- | ------------------ | -------- | @@ -108,15 +108,39 @@ There are four significant differences between merged and unmerged MediaWiki for unit modifiers, value classes, schema attributes, and schema properties) that it explicitly extends.
 
-3. Nodes with the `rooted` property must be top-level tags in the schema -in the unmerged schema. In the merged schema, the subtrees under these `rooted` -nodes are placed directly under the respective nodes of the same name -in the standard schema. +3. In the unmerged schema, nodes with the `rooted=XXX` schema attribute must be top-level tags, +and `XXX` must correspond to a node in the standard schema. In the merged schema, nodes with the `rooted=XXX` schema attribute are placed directly +under the standard schema node `XXX`.
 
4. Nodes in the unmerged version cannot have the `inLibrary` attribute. In contrast, nodes from the library schema are given the `inLibrary` attribute during the merging process. +The following excerpt from an unmerged library schema in MediaWiki format shows a library schema node (`Data-mode`) rooted to `Statistical-value` in the +standard schema. + +````{admonition} Example of a rooted node in an unmerged schema in MediaWiki format. +```html + . . . +'''Data-mode''' {rooted=Statistical-value}[A value that occurs most often in data.] +* # {takesValue, valueClass=numericClass} + . . . +``` +```` +Notice that the indentation asterisks (*) indicate that the node's children are at the first level. +In the merged schema, these are adjusted accordingly as shown in the following: + +````{admonition} When merged with the standard schema, the indentation levels are adjusted. +```html + . . . +*** Statistical-value {extensionAllowed}[A value based on or employing the principles of statistics.] +**** Data-mode''' {inLibrary}[A value that occurs most often in data.] +***** # {takesValue, valueClass=numericClass, inLibrary} + . . . +``` +```` + + Similar differences occur between the merged and unmerged XML formats, but only the merged XML format is useful. @@ -161,7 +185,7 @@ HED standard schema 8.2.0: | `withStandard` | Header attribute | | | `unmerged` | Header attribute | | | `inLibrary` | Element attribute | | -| `rooted` | Node attribute | | +| `rooted=XXX` | Node attribute | | | `reserved` | Node attribute | . | diff --git a/docs/source/Appendix_A.md b/docs/source/Appendix_A.md index 05490c5..60223fa 100644 --- a/docs/source/Appendix_A.md +++ b/docs/source/Appendix_A.md @@ -231,14 +231,20 @@ Only the schema attributes listed in the following table can be handled by curre - 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.) + - 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. +* - `deprecatedFrom`* + - element + - This element is deprecated. The value of the attribute
is the latest schema version in which the element
appeared before it was deprecated.. * - `extensionAllowed` - node - A tag can have unlimited levels of child nodes added. +* - `inLibrary` + - element + - This schema element is from the named library schema,
not the standard schema. (Added/removed by tools.) * - `recommended` - node - Event-level HED strings should include this tag. @@ -251,6 +257,12 @@ Only the schema attributes listed in the following table can be handled by curre * - `required` - node - Event-level HED string must include this tag. +* - `reserved` + - node + - This tag has special meaning and requires
special handling by tools. +* - `rooted`* + - node + - A top-level library schema node should appear
under this standard schema node when merged. * - `SIUnit` - unit - This unit represents an SI unit and can be modified. @@ -299,7 +311,7 @@ However, the following group designations are allowed as values for this attribu 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. +For example, the `timeUnits` has the attribute `defaultUnits=s` in HED versions. Tools may assume that tag `Duration/3` is equivalent to `Duration/3 s` because `Duration` has `defaultUnits` of `s`. @@ -314,7 +326,7 @@ In addition to the attributes listed above, some schema attributes have been dep 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). +`````{list-table} Schema attributes deprecated for versions ≥ 8.0.0 (* indicates attribute has a value). :widths: 20 15 45 :header-rows: 1 @@ -448,8 +460,7 @@ keyword `HED` followed by a blank-separated list of name-value pairs. - Description * - library - optional - - Name of library used in XML file names. - + - Name of library used in XML file names. The value should only have lowercase alphabetic characters. * - version - required @@ -460,7 +471,13 @@ keyword `HED` followed by a blank-separated list of name-value pairs. * - xsi - optional - xsi:noNamespaceSchemaLocation points to an XSD file. - + * - withStandard + - optional + - The version of the standard schema partner if this is a partnered library schema. + * - unmerged + - optional + - If true, this is an unmerged partnered library schema. + If omitted, assumed false. ```` The following example gives a sample *header-line* for standard schema version 8.0.0 in `.mediawiki` format. @@ -774,6 +791,17 @@ directory of the [**hed-schemas**](https://github.com/hed-standard/hedschemas) G 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. +The `library` and `version` values are used to form the official xml file name `HED_testlib_1.0.2.xml`. + +Library schemas may also be partnered as is `HED_testlib_2.0.0.xml`. + +````{admonition} **Example:** Partnered library schema testlib version 2.0.0 in .xml format. +```xml + +``` +```` + + ### A.3.3. The prologue and epilogue The `...` and `...` elements diff --git a/docs/source/Appendix_B.md b/docs/source/Appendix_B.md index 2a4aa27..67f2dfe 100644 --- a/docs/source/Appendix_B.md +++ b/docs/source/Appendix_B.md @@ -119,19 +119,18 @@ 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. +**c.** An `Onset` or `Offset` tag is not grouped with exactly one `Def` tag or `Def-expand` group. +**d.** An `Onset` or an `Inset` tag group contains 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` +**h.** An `Onset` or an `Inset` tag group with has tags besides the anchor `Def` tag or `Def-expand` group that are not in a tag group. -**i.** An `Onset`, `Inset` or `Offset` with a given `Def` or `Def-expand-group` anchor +**i.** An `Onset` or `Offset` with a given `Def` tag or `Def-expand` group anchor appears in an event marker with the same time as with another `Onset`, `Inset`, or `Offset` that uses the same anchor. -**j.** An `Inset` tag is not grouped with a `Def` or `Def-expand` of an ongoing `Onset`. -**k.** An `Inset` group has more than a single tag group in addition to its defining `Def` or `Def-expand`. +**j.** An `Inset` tag is not grouped with a `Def` tag or a `Def-expand` group corresponding to an ongoing `Onset`. **Note:** if the `Onset` tag group's definition is in expanded form, the `Def-expand` will be an additional internal tag group. diff --git a/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json b/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json index e47ad7b..5b7c5b5 100644 --- a/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json +++ b/tests/json_tests/ONSET_OFFSET_INSET_ERROR.json @@ -1,7 +1,7 @@ [ { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-not-tag-group", + "name": "onset-offset-inset-error-not-tag-group", "description": "An Onset or Offset tag does not appear in a tag group.", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -98,7 +98,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-nested-group", + "name": "onset-offset-inset-error-nested-group", "description": "An Onset or Offset tag appears in a nested tag group (not a top-level tag group).", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -185,7 +185,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-wrong-number-of-defs", + "name": "onset-offset-inset-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.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -277,7 +277,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-error-onset-has-more-groups", + "name": "onset-offset-inset-error-onset-has-more-groups", "description": "An Onset group has more than one additional tag group.", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -373,7 +373,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-offset-has-groups", + "name": "onset-offset-inset-error-offset-has-groups", "description": "An Offset appears with one or more tags or additional tag groups.", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -485,7 +485,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-mismatch", + "name": "onset-offset-inset-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.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -563,7 +563,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-extra tags", + "name": "onset-offset-inset-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.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -652,7 +652,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "onset-offset-error-duplicated-onset-or-offset", + "name": "onset-offset-inset-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.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -749,7 +749,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "inset-outside-its-event", + "name": "onset-offset-inset-error-inset-outside-its-event", "description": "An Inset tag is not grouped with a Def or Def-expand of an ongoing Onset.", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"], @@ -770,7 +770,7 @@ "fails": [ [ ["onset", "duration", "HED"], - [ 4.5, 0, "(Def/MyColor, Offset)"], + [ 4.5, 0, "(Inset, (Red))"], [ 6.5, 0, "Red, (Def/MyColor, Offset)"], [ 5.5, 0, "(Def/MyColor, Offset)"] ] @@ -830,7 +830,7 @@ }, { "error_code": "ONSET_OFFSET_INSET_ERROR", - "name": "inset-group-has-extras", + "name": "onset-offset-inset-error-inset-group-has-extras", "description": "An Inset group has tags or groups in addition to its defining Def or Def-expand.", "schema": "8.2.0", "definitions": ["(Definition/Acc/#, (Acceleration/#, Red))", "(Definition/MyColor, (Label/Pie))"],