[FIX]: Hierarchical Event Descriptors (HED) page update

src/appendices/hed.md

@@ -12,7 +12,7 @@ A HED annotation consists of terms selected from a controlled
 hierarchical vocabulary (the HED schema).
 Individual terms are comma-separated and may be grouped using parentheses to indicate
 association.
-See [https://www.hedtags.org/display_hed.html](https://www.hedtags.org/display_hed.html)
+See the [HED Schema Browser](https://www.hedtags.org/display_hed.html)
 to view the HED schema and the
 [HED resources](https://www.hed-resources.org) site for additional information.
 
@@ -24,7 +24,7 @@ or
 `Property/Sensory-property/Sensory-presentation/Visual-presentation`).
 
 HED specific tools MUST treat the short (single term) and long (full path) HED tag forms interchangeably,
-converting between the forms when necessary based on the HED schema.
+converting between the forms, when necessary, based on the HED schema.
 Examples of test datasets using the various forms can be found in
 [hed-examples/datasets](https://github.com/hed-standard/hed-examples/tree/main/datasets)
 on GitHub.
@@ -40,7 +40,7 @@ files in various places in the dataset hierarchy
 Dataset curators MAY also include additional columns and define their
 meanings in associated JSON sidecar files (`events.json`).
 
-Example: An excerpt from an `events.tsv` file containing three columns
+**Example:** An excerpt from an `events.tsv` file containing three columns
 (`trial_type`, `response_time`, and `stim_file`) in addition to
 the required `onset` and `duration` columns.
 
@@ -66,7 +66,7 @@ The HED annotation for a value column must include a `#` placeholder,
 which dedicated HED tools MUST replace by the actual column value when the annotations
 are assembled for analysis.
 
-Example: An accompanying `events.json` sidecar describing both categorical and
+**Example:** An accompanying `events.json` sidecar describing both categorical and
 value columns of the previous example.
 The `duration` column is also annotated as a value column.
 
@@ -108,7 +108,7 @@ Dedicated HED tools MUST assemble the HED annotation for each event (row) by con
 annotations for each column, along with the annotation contained directly in a `HED` column
 of that row as described in the next section.
 
-Example: The fully assembled annotation for the first event in the above
+**Example:** The fully assembled annotation for the first event in the above
 `events.tsv` file with onset `1.2` (the first row) is:
 
 ```Text
@@ -117,7 +117,7 @@ Duration/0.6 s, Sensory-event, Visual-presentation, (Square, Blue),
 Pathname/images/red_square.jpg
 ```
 
-## Annotation using the `HED` column
+### Annotation using the `HED` column
 
 Another tagging strategy is to annotate individual events directly by
 including a `HED` column in the `events.tsv` file.
@@ -165,17 +165,17 @@ field of the `dataset_description.json` file located in the dataset root directo
 This allows for a proper validation of the HED annotations
 (for example using the `bids-validator`).
 
-Example: The following `dataset_description.json` file specifies that the
-[`HED8.1.0.xml`](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.1.0.xml)
+**Example:** The following `dataset_description.json` file specifies that the
+[`HED8.2.0.xml`](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml)
 file from the `standard_schema/hedxml` directory of the
 [`hed-schemas`](https://github.com/hed-standard/hed-schemas)
 repository on GitHub should be used to validate the study event annotations.
 
 ```JSON
 {
   "Name": "A great experiment",
-  "BIDSVersion": "1.7.0",
-  "HEDVersion": "8.1.0"
+  "BIDSVersion": "1.8.0",
+  "HEDVersion": "8.2.0"
 }
 ```
 
@@ -193,10 +193,27 @@ communities of users and are available in the GitHub
 [hed-schemas](https://github.com/hed-standard/hed-schemas) repository.
 Library schema are specified in the form `<library-name<_>library-version>`.
 
-Example: The following `dataset_description.json` file specifies that the
+#### Partnered library schemas
+
+Partnered library schemas were introduced in HED specification version 3.2.0
+and are supported by HED standard schema versions ≥ 8.2.0.
+A partnered library schema version is tied to a specific version of
+the HED standard schema as specified in its header. A given library schema
+version is either partnered or standalone.
+
+**Note:** Whether a particular library schema version is partnered or
+unpartnered is fixed when the library is released and cannot be changed.
+For example,
+[HED-SCDORE version 1.0.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki)
+is unpartnered, but [HED-SCDORE version 1.1.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.1.0.mediawiki)
+is partnered with standard schema version 8.2.0.
+
+##### Unpartnered library schemas example
+
+The following `dataset_description.json` file specifies that the
 [HED8.1.0.xml](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.1.0.xml)
-standard schema should be used along with the
-SCORE library for clinical neurological annotation located at
+standard schema should be used along with the HED-SCDORE library schema
+for clinical neurological annotation located at
 [HED_score_1.0.0.xml](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedxml/HED_score_1.0.0.xml).
 
 ```JSON
@@ -212,16 +229,18 @@ The prefixes MUST be alphanumeric.
 Any number of prefixed schemas may be used in addition to a non-prefixed one.
 
 The following HED annotation from this dataset uses the `sc:` prefix with
-`Photomyogenic-response` and `Wicket-spikes` because these terms are from the
-SCORE library, while `Data-feature` is from the standard HED schema.
+`Eye-blink-artifact` and `Seizure-PNES` because these terms are from the
+HED-SCDORE library schema, while `Data-feature` is from the standard HED schema.
 
 ```Text
-Data-feature, sc:Photomyogenic-response, sc:Wicket-spikes
+Data-feature, sc:Eye-blink-artifact, sc:Seizure-PNES
 ```
 
+##### Single unpartnered library schema example
+
 If only one schema is being used for annotation, the prefix can be omitted entirely.
-The following `dataset_description.json` indicates that only the SCORE library version
-0.0.1 will be used for HED annotation in this dataset.
+The following `dataset_description.json` indicates that only the HED-SCDORE library schema version
+1.0.0 will be used for HED annotation in this dataset.
 
 ```JSON
 {
@@ -231,8 +250,31 @@ The following `dataset_description.json` indicates that only the SCORE library v
 }
 ```
 
-The corresponding notations in the dataset do not have a prefix:
+The corresponding anotations in the dataset do not have a prefix:
+
+```Text
+Eye-blink-artifact, Seizure-PNES
+```
+
+##### Partnered library schema example
+
+The following `dataset_description.json` file specifies that
+the HED-SCORE library schema
+[version 1.1.0](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.1.0.mediawiki) is used.
+This particular library schema version is partnered with standard schema version
+[8.2.0](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml).
+
+```JSON
+{
+  "Name": "A great experiment",
+  "BIDSVersion": "1.8.0",
+  "HEDVersion": "score_1.1.0"
+}
+```
+The corresponding anotations in the dataset uses tags from the
+HED-SCORE library schema (`Eye-blink-artifact` and `Seizure-PNES`) and from the standard HED (`Data-feature`)
+as follows:
 
 ```Text
-Photomyogenic-response, Wicket-spikes
+Data-feature, Eye-blink-artifact, Seizure-PNES
 ```