Merge branch 'main' into promote_herd

Author: rly

common/table.yaml

@@ -136,6 +136,19 @@ groups:
   - data_type_inc: VectorData
     doc: Vector columns, including index columns, of this dynamic table.
     quantity: '*'
+  groups:
+  - name: meanings_tables
+    doc: Group containing MeaningsTable objects that provide meanings for
+      values in VectorData columns within this DynamicTable.
+    quantity: '?'
+    groups:
+    - data_type_inc: MeaningsTable
+      doc: MeaningsTable objects that provide meanings for values
+        in VectorData columns within this DynamicTable. Tables should be named
+        according to the column they provide meanings for with a "_meanings" suffix.
+        e.g., if a VectorData column is named "stimulus_type", the corresponding
+        MeaningsTable should be named "stimulus_type_meanings".
+      quantity: '*'
 
 - data_type_def: AlignedDynamicTable
   data_type_inc: DynamicTable
@@ -165,3 +178,25 @@ groups:
       container. The name of the category is given by the name of the DynamicTable
       and its description by the description attribute of the DynamicTable.
     quantity: '*'
+
+- data_type_def: MeaningsTable
+  data_type_inc: DynamicTable
+  doc: A table to store information about the meanings of values in a linked VectorData object.
+    All possible values of the linked VectorData object should be present in the 'value' column
+    of this table, even if the value is not observed in the data. Additional columns may be
+    added to store additional metadata about each value. The name of the MeaningsTable
+    should correspond to the name of the linked VectorData object with a "_meanings" suffix.
+    e.g., if the linked VectorData object is named "stimulus_type", the corresponding
+    MeaningsTable should be named "stimulus_type_meanings".
+  datasets:
+  - name: value
+    data_type_inc: VectorData
+    doc: The value of a row in the linked VectorData object.
+  - name: meaning
+    data_type_inc: VectorData
+    dtype: text
+    doc: The meaning of the value in the linked VectorData object.
+  links:
+  - name: target
+    target_type: VectorData
+    doc: Link to the VectorData object for which this table provides meanings.

docs/source/hdmf_common_release_notes.rst

@@ -5,9 +5,13 @@ hdmf-common Release Notes
 
 1.9.0 (Upcoming)
 ----------------------
-- Change the dtype of `ElementIdentifiers` and `DynamicTableRegion` from "int" to "int32". Under HDMF
+- Changed the dtype of ``ElementIdentifiers`` and ``DynamicTableRegion`` from "int" to "int32". Under HDMF
   schema language 2.x, "int" means "int32" so this change has no functional impact, except when displaying the
   spec, such as in error messages.
+- Added ``MeaningsTable``, a table for storing meanings for values in linked ``VectorData`` objects.
+  This is useful for annotating categorical data stored in a ``DynamicTable``. Added a group named "meanings_tables"
+  to ``DynamicTable`` to hold ``MeaningsTable`` objects that provide meanings for ``VectorData`` columns in the
+  ``DynamicTable``.
 - Minor changes to data type docstrings to improve clarity.
 - Promoted ``HERD`` from the HDMF-experimental namespace to a stable data type in the HDMF-common
   namespace.