diff --git a/docs/source/08_HED_ontology.md b/docs/source/08_HED_ontology.md index e88993a..5dc5813 100644 --- a/docs/source/08_HED_ontology.md +++ b/docs/source/08_HED_ontology.md @@ -1,23 +1,11 @@ # 8. The HED ontology ---------DRAFT DRAFT DRAFT DRAFT DRAFT ------------ - -This chapter defines the HED ontology and explains the relationship -between the HED ontology and the HED schema. - -The `hed:` prefix is the abbreviation for HED's -[**IRI**](https://datatracker.ietf.org/doc/html/rfc3987) (International Resource Identifier) prefix. -Terms with this prefix are associated with a particular schema -- either the standard schema or a library schema. -Terms with the `heds:` prefix are structural elements common to all HED schemas. -Both the `hed:` and `heds:` namespaces map to the same PURL (Persistent Uniform Resource Locator) +This chapter defines the HED ontology and its relationship to the HED schema. +HED maps all of its entities (i.e., standard schema, library schemas, structural elements, properties) +into a single namespace with unique [**IRI**](https://datatracker.ietf.org/doc/html/rfc3987) (International Resource Identifier) identifiers as explained in [**8.3 HED global identifiers**](#83-hed-global-identifiers). -Terms with the `rdfs:` prefix are from the -[**RDF Schema**](https://en.wikipedia.org/wiki/RDF_Schema) (i.e., the Resource Description Framework Schema). -Terms with the `dc:` prefix are drawn from the -[**DublinCore Ontology**](https://www.dublincore.org/resources/glossary/ontology/). - -Finally, the GitHub source repository for the HED ontologies is [**hed-ontology**](https://github.com/hed-standard/hed-ontology). +The GitHub source repository for the HED ontologies is [**hed-ontology**](https://github.com/hed-standard/hed-ontology). The GitHub source repository for the HED schemas is [**hed-schemas**](https://github.com/hed-standard/hed-schemas). ## 8.1. HED views and representations @@ -37,9 +25,9 @@ manner to support this work-flow. In the diagram, top-level tags `S1`, `S4`, and `L6` represent general categories and are roots of subtrees organized so that child nodes are more specific terms. -HED supports "search generality", so searches may specify an exact match or matches any term in a particular subtree. -In the latter case a search for `Event` may also match `Sensory-event` or `Agent-action` or any other descendent of -`Event`. +HED supports "search generality", so searches may specify an exact match or matches to any term in a particular subtree. +In the latter case, a search for `Event` may also match any of its descendents +(e.g., `Sensory-event` or `Agent-action`). The [**HED schema viewer**](https://www.hedtags.org/display_hed.html), allows users to focus on top-level categories or expand the hierarchy view to any specified level of detail. @@ -89,23 +77,81 @@ The HED vocabularies have 4 different formats as shown in the following table: | OWL | Complete | Ontology updating
Semantic validation
Documentation generation
Semantic tools | Manual editing
Updated from spreadsheet | The HED schema, which contains the core HED vocabulary and captures the "annotator's view" of HED, -is completely represented in either the HED MediaWiki and HED XML formats. +can be completely represented in the HED Mediawiki, XML, or spreadsheet formats. The HED schema is used for annotation, validation, searching, and most analyses. -Tools access the HED schema in its XML format, but schema developers create -and update the schema in MediaWiki format, which is easier to read and displays as formatted +Tools access the HED schema in its XML format, but schema developers usually create +and update the schema in Mediawiki format, which is easier to read and displays as formatted MarkDown on GitHub. +Alternatively schema developers may opt to create or update schemas from the HED spreadsheets. + +#### 8.1.4.1. The Mediawiki format +The Mediawiki format is line-oriented with each non-blank line corresponding to a HED tag or other HED entity +such as a unit class or schema attribute definition. +See [**A.2. Mediawiki file format**](./Appendix_A.md#a-2-mediawiki-file-format) +for a detailed description of the Mediawiki format. + +#### 8.1.4.2. Spreadsheet files + +The spreadsheet format consists of 10 tab-separated value (tsv) files each containing +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. | + +The `xxx_` prefix identifies the schema version. +For example, the prefix for standard schema version 8.3.0 is `HED8.3.0_` and +the prefix for SCORE library schema 2.0.0 is `HED_score_2.0.0_`. + +Most schema developers will only edit the `xxx_Tag.tsv` file or the `xxx_Structure.tsv` file. -The HED ontology represents the entire HED information space in -[**OWL**](https://www.w3.org/OWL/) (Web Ontology Language). -The HED ontology is available in both [**OWL/RDF**](https://www.w3.org/TR/owl2-mapping-to-rdf/) format -and [**OWL Manchester**](https://www.w3.org/TR/owl2-manchester-syntax/) format -but the examples in this specification use OWL Manchester format for readability. -#### 8.1.4.1. Spreadsheet <--> Mediawiki +#### 8.1.4.3. Spreadsheet format -The HED schema also has a HED spreadsheet representation -(with columns containing a tag's name, parent, attributes, and description). -The mapping between the HED MediaWiki format and the HED spreadsheet is illustrated in the following example: +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` + +| tsv file name | Required column names | +|------------------------|------------------------------------------------------------------------------------------------------------| +| `xxx_AnnotationProperty` | `hedId`, `rdfs:label`, `Type`, `omn:Domain`, `omn:Range`, `dc:description` | +| `xxx_AttributeProperty` | `hedId`, `rdfs:label`, `Type`, `dc:description` | +| `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_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` | +| `xxx_ValueClass` | `hedId`, `rdfs:label`, `omn:SubClassOf`, `Attributes`, `dc:description`, `omn:EquivalentTo` | + +The prefixes on column names have the following meanings: + +| Column name prefix | Meaning | +| ------------------ |--------------------------------------------------------------------------------------------------------------------| +| `rdfs:` | from [**RDF Schema**](https://en.wikipedia.org/wiki/RDF_Schema) (i.e., the Resource Description Framework Schema). | +| `dc:` | from [**DublinCore Ontology**](https://www.dublincore.org/resources/glossary/ontology/). | +|`omn:` | translated directly to OWL Manchester Format. | + +Users may add additional columns corresponding to annotation properties from +the Dublin Core or the RDF schema (e.g., `dc:comment`) and the HED ontology framework will +include them in the ontology. However, these columns do not impact the HED schema. + + +#### 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 +as illustrated in the following example: ![hed mediawiki to spreadsheet](_static/images/HEDSpreadsheetMediawiki.png) @@ -127,11 +173,11 @@ following table: HED schema developers can develop in either HED MediaWiki or HED spreadsheet (tab-separated-value) file format and can use tools to update the representations. -Users may NOT assign or modify the `hedId` in the MediaWiki file. +Users may NOT assign or modify the `hedId`. When creating a new entity such as a tag, leave the `hedId` column blank. If adding a new tag to the MediaWiki file, schema developers should omit the `hedId`. Tools will assign and validate the `hedId` during the update process. -#### 8.1.4.2. Spreadsheet <--> Ontology +#### 8.1.4.5. Tag spreadsheet <--> Ontology HED spreadsheets have been expanded to include additional columns to capture all the information contained in the HED ontology as illustrated in the following example. @@ -140,6 +186,13 @@ the ontology uses the `hedId`. ![hed representations](_static/images/HEDRepresentations.png) +The HED ontology represents the entire HED information space in +[**OWL**](https://www.w3.org/OWL/) (Web Ontology Language). +The HED ontology is available in both [**OWL/RDF**](https://www.w3.org/TR/owl2-mapping-to-rdf/) format +and [**OWL Manchester**](https://www.w3.org/TR/owl2-manchester-syntax/) format, +but the examples in this specification use OWL Manchester format for readability. +Developers must use the HED spreadsheets to create or update a HED ontology. + Most HED entities (i.e., tags, unit classes, units, unit modifiers, and value classes) map to classes in the HED ontology. The HED schema attributes, which describe properties and behavior, are mapped to ontology properties @@ -154,8 +207,8 @@ following table: | Spreadsheet
column | Row value | Ontology format | | ----------- |:------------------:| ------- | | **hedId** | *xxx* | `Class: hed:xxx` | -| **Level** | *n* | Redundant information -- can be recovered using class hierarchy. | | **rdfs:label** | *yyy* | `rdfs:label yyy` in the `Annotations` section | +| **Level** | *n* | Redundant information -- can be recovered using class hierarchy. | | **omn:SubClassOf** | *zzz* | The tag is either a `SubClassOf` or `EquivalentTo` *zzz*
but *zzz* is identified in the ontology
by **hedId** rather name. | | **Attributes** | *uuu*, *vvv*, ... | If non-empty, then these appear as restrictions
in the `EquivalentTo`. See [**8.2.3. Schema attributes**|(./#823-schema-attributes). | | **dc:description** | *www* | `dc:description www` in the `Annotations` section. |