From 38d5985f45192907d8b18933909f01dfb54218c5 Mon Sep 17 00:00:00 2001
From: Kay Robbins <1189050+VisLab@users.noreply.github.com>
Date: Tue, 28 May 2024 10:55:46 -0500
Subject: [PATCH] Corrections from readers
---
docs/source/08_HED_ontology.md | 56 +++++++++++++++++++---------------
1 file changed, 31 insertions(+), 25 deletions(-)
diff --git a/docs/source/08_HED_ontology.md b/docs/source/08_HED_ontology.md
index 5dc5813..30fc7d0 100644
--- a/docs/source/08_HED_ontology.md
+++ b/docs/source/08_HED_ontology.md
@@ -96,18 +96,18 @@ The spreadsheet format consists of 10 tab-separated value (tsv) files each conta
the information for one type of HED entity as summarized in the following table.
-| tsv file name | Contents |
-|------------------------|--------------------------------------------------------------------------------|
-| `xxx_AnnotationProperty` | Properties that |
-| `xxx_AttributeProperty` | Definitions of the schema attribute properties in `Properties` |
-| `xxx_DataProperty` | Schema attributes whose value is a literal such as boolean, string or numeric. |
-| `xxx_ObjectProperty` | Schema attributes whose value is another schema entity such as a HED tag. |
-| `xxx_Structure` | Structural entities including the header, prologue, and epilogue. |
-| `xxx_Tag` | Definitions of the HED tags (vocabulary) in the schema. |
-| `xxx_Unit` | Definitions of the HED unit entities. |
-| `xxx_UnitClass` | Definitions of the HED unit classes. |
-| `xxx_UnitModifier` | Definitions of the HED unit modifiers. |
-| `xxx_ValueClass` | Definitions of the HED value classes. |
+| tsv file name | Contents |
+|------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| `xxx_AnnotationProperty` | These correspond to schema attributes that are not inherited. |
+| `xxx_AttributeProperty` | Definitions of the schema attribute properties corresponding
to the `Properties` section in the MediaWiki File. |
+| `xxx_DataProperty` | Schema attributes whose value is a literal such as boolean, string or numeric. |
+| `xxx_ObjectProperty` | Schema attributes whose value is another schema entity such as a HED tag. |
+| `xxx_Structure` | Structural entities including the header, prologue, and epilogue. |
+| `xxx_Tag` | Definitions of the HED tags (vocabulary) in the schema. |
+| `xxx_Unit` | Definitions of the HED unit entities. |
+| `xxx_UnitClass` | Definitions of the HED unit classes. |
+| `xxx_UnitModifier` | Definitions of the HED unit modifiers. |
+| `xxx_ValueClass` | Definitions of the HED value classes. |
The `xxx_` prefix identifies the schema version.
For example, the prefix for standard schema version 8.3.0 is `HED8.3.0_` and
@@ -119,7 +119,7 @@ Most schema developers will only edit the `xxx_Tag.tsv` file or the `xxx_Structu
#### 8.1.4.3. Spreadsheet format
Each HED spreadsheet must start with a 1-line header containing the column names of the file.
-The first two column names are always `hedId` and `rdfs:label`
+The first two column names are always `hedId` and `rdfs:label`.
| tsv file name | Required column names |
|------------------------|------------------------------------------------------------------------------------------------------------|
@@ -128,7 +128,7 @@ The first two column names are always `hedId` and `rdfs:label`
| `xxx_DataProperty` | `hedId`, `rdfs:label`, `Type`, `omn:Domain`, `omn:Range`, `Properties`, `dc:description` |
| `xxx_ObjectProperty` | `hedId`, `rdfs:label`, `Type`, `omn:Domain`, `omn:Range`, `Properties`, `dc:description` |
| `xxx_Structure` | `hedId`, `rdfs:label`, `Attributes`, `dc:description` |
-| `xxx_Tag` | `hedId`, `Level`, `rdfs:label`, `omn:SubClassOf`, `Attributes`, `dc:description`, `omn:EquivalentTo` |
+| `xxx_Tag` | `hedId`, `rdfs:label`, `Level`, `omn:SubClassOf`, `Attributes`, `dc:description`, `omn:EquivalentTo` |
| `xxx_Unit` | `hedId`, `rdfs:label`, `omn:SubClassOf`, `hadUnitClass`, `Attributes`, `dc:description`, `omn:EquivalentTo` |
| `xxx_UnitClass` | `hedId`, `rdfs:label`, `omn:SubClassOf`, `Attributes`, `dc:description`, `omn:EquivalentTo` |
| `xxx_UnitModifier` | `hedId`, `rdfs:label`, `omn:SubClassOf`, `Attributes`, `dc:description`, `omn:EquivalentTo` |
@@ -150,7 +150,8 @@ include them in the ontology. However, these columns do not impact the HED schem
#### 8.1.4.4. Spreadsheet <--> Mediawiki
Each non-blank line in a HED Mediawiki file corresponds to a single HED entity such as a HED tag.
-Similarly, each row in a HED The fields of the HED MediaWiki format have a specific mapping to columns in a HED spreadsheet
+Similarly, each row in a HED spreadsheet file corresponds to a single HED entity.
+The fields of the HED MediaWiki format have a specific mapping to columns in a HED spreadsheet
as illustrated in the following example:
![hed mediawiki to spreadsheet](_static/images/HEDSpreadsheetMediawiki.png)
@@ -219,11 +220,12 @@ The next section describes the ontology structure in more detail.
## 8.2. HED schema to ontology
-Each HED element (tag, unit, unit class, unit modifier, or value class) is associated with a
-unique persistent globally unique identifier --- the `hedId` schema attribute value in the
-HED schema and the entity ID in the HED ontology.
-The structural elements, common to all schemas also have unique assigned identifiers.
-The HED schema attributes are part of the HED structural ontology and
+Each element of a HED schema (i.e., tag, unit, unit class, unit modifier, value class, schema attribute,
+schema attribute property, schema header, epilogue, and prologue) is assigned a
+unique persistent globally unique identifier (GUID).
+This GUID appears as the entity identifier in the ontology and as the `hedId` attribute value in the HED schema.
+In addition to the HED elements the HED ontology also has some overall structural elements
+that are also assigned `hedId` values.
The examples in this section
and `hed:` to represent schema-specific elements.
@@ -249,10 +251,11 @@ The following table summarizes how the HED schema and HED ontology are mapped.
- Class with `DataProperty` values for:
* `version` - (required) semantic version of schema.
* `library` - (optional) library name if library.
- * `withStandard` - (optional) semantic version of library's standard partner).
+ * `withStandard` - (optional) semantic version of library's standard partner.
* `merged`- (optional) library has been merged with its standard schema partner.
* - **Tag**
- - * Defined in the `schema` section of the HED schema.
+ - Class representing HED tags:
+ * Defined in the `schema` section of the HED schema.
* Uses subclassing to represent HED schema structure.
* Top-level tags extend `HedTag` (`heds:HED_0000005`).
* A rooted library tag extends its root in the standard schema.
@@ -296,7 +299,7 @@ The following table summarizes how the HED schema and HED ontology are mapped.
The HED schema hierarchy is captured by subclassing in the HED ontology.
Top-level tag nodes in the HED schema are direct subclasses of the `HedTag` class (`heds:HED_0000005`).
-A descendent of a top-level tag node is a direct subclass of its parent tag node in the HED schema.
+A descendant of a top-level tag node is a direct subclass of its parent tag node in the HED schema.
The ontology subclass relationship enforces the HED requirement that each tag in the
HED schema must satisfy the **is-a** relationship with its parent in the HED schema.
@@ -306,7 +309,7 @@ to illustrate how subclassing is represented in the various HED formats.
#### 8.2.2.1. Mediawiki tag format
The **MediaWiki** representation uses ordering and asterisks to mark parentage relationships.
-In other words, the HED Wikimedia schema tree is given in depth-first search order.
+In other words, the HED MediaWiki schema tree is given in depth-first search order.
The parent of a tag prefixed by *X* number of asterisks is a direct child of the first tag
above it with *X-1* asterisks.
Top level tags are enclosed by three quotes and have no parent within the schema (i.e., *X* = 0).
@@ -508,7 +511,10 @@ In the MediaWiki format, schema attributes appear in the `Schema Attributes` sec
```
Note: this example has line breaks added to fit on the page. Each element in Mediawiki must appear on one line.
````
-The `extensionAllowed` attribute has a unique `hedId
+The `extensionAllowed` attribute has a unique `hedId` value `HED_0010307`. The `tagDomain` attribute indicates that
+`extensionAllowed` is only a schema attribute of HED tags.
+The `boolRange` attribute indicates that `extenstionAllowed` is true if present and false if absent.
+
#### 8.2.3.5. XML attribute format