nwb-linkml/nwb_linkml/schema/hdmf-common.table.yaml

name: hdmf-common.table
id: hdmf-common.table
imports:
- hdmf-common.base
- nwb.language
default_prefix: hdmf-common.table/
classes:
  VectorData:
    name: VectorData
    description: An n-dimensional dataset representing a column of a DynamicTable.
      If used without an accompanying VectorIndex, first dimension is along the rows
      of the DynamicTable and each step along the first dimension is a cell of the
      larger table. VectorData can also be used to represent a ragged array if paired
      with a VectorIndex. This allows for storing arrays of varying length in a single
      cell of the DynamicTable by indexing into this VectorData. The first vector
      is at VectorData[0:VectorIndex[0]]. The second vector is at VectorData[VectorIndex[0]:VectorIndex[1]],
      and so on.
    is_a: Data
    attributes:
      description:
        name: description
        description: Description of what these vectors represent.
        range: text
      array:
        name: array
        range: VectorData_Array
  VectorData_Array:
    name: VectorData_Array
    is_a: Arraylike
    attributes:
      dim0:
        name: dim0
        range: AnyType
        required: true
      dim1:
        name: dim1
        range: AnyType
        required: false
      dim2:
        name: dim2
        range: AnyType
        required: false
      dim3:
        name: dim3
        range: AnyType
        required: false
  VectorIndex:
    name: VectorIndex
    description: Used with VectorData to encode a ragged array. An array of indices
      into the first dimension of the target VectorData, and forming a map between
      the rows of a DynamicTable and the indices of the VectorData. The name of the
      VectorIndex is expected to be the name of the target VectorData object followed
      by "_index".
    is_a: VectorData
    attributes:
      target:
        name: target
        description: Reference to the target dataset that this index applies to.
        range: VectorData
      array:
        name: array
        range: VectorIndex_Array
  VectorIndex_Array:
    name: VectorIndex_Array
    is_a: Arraylike
    attributes:
      num_rows:
        name: num_rows
        range: uint8
        required: true
  ElementIdentifiers:
    name: ElementIdentifiers
    description: A list of unique identifiers for values within a dataset, e.g. rows
      of a DynamicTable.
    is_a: Data
    attributes:
      array:
        name: array
        range: ElementIdentifiers_Array
  ElementIdentifiers_Array:
    name: ElementIdentifiers_Array
    is_a: Arraylike
    attributes:
      num_elements:
        name: num_elements
        range: int
        required: true
  DynamicTableRegion:
    name: DynamicTableRegion
    description: DynamicTableRegion provides a link from one table to an index or
      region of another. The `table` attribute is a link to another `DynamicTable`,
      indicating which table is referenced, and the data is int(s) indicating the
      row(s) (0-indexed) of the target array. `DynamicTableRegion`s can be used to
      associate rows with repeated meta-data without data duplication. They can also
      be used to create hierarchical relationships between multiple `DynamicTable`s.
      `DynamicTableRegion` objects may be paired with a `VectorIndex` object to create
      ragged references, so a single cell of a `DynamicTable` can reference many rows
      of another `DynamicTable`.
    is_a: VectorData
    attributes:
      table:
        name: table
        description: Reference to the DynamicTable object that this region applies
          to.
        range: DynamicTable
      description:
        name: description
        description: Description of what this table region points to.
        range: text
      array:
        name: array
        range: DynamicTableRegion_Array
  DynamicTableRegion_Array:
    name: DynamicTableRegion_Array
    is_a: Arraylike
    attributes:
      num_rows:
        name: num_rows
        range: int
        required: true
  DynamicTable:
    name: DynamicTable
    description: A group containing multiple datasets that are aligned on the first
      dimension (Currently, this requirement if left up to APIs to check and enforce).
      These datasets represent different columns in the table. Apart from a column
      that contains unique identifiers for each row, there are no other required datasets.
      Users are free to add any number of custom VectorData objects (columns) here.
      DynamicTable also supports ragged array columns, where each element can be of
      a different size. To add a ragged array column, use a VectorIndex type to index
      the corresponding VectorData type. See documentation for VectorData and VectorIndex
      for more details. Unlike a compound data type, which is analogous to storing
      an array-of-structs, a DynamicTable can be thought of as a struct-of-arrays.
      This provides an alternative structure to choose from when optimizing storage
      for anticipated access patterns. Additionally, this type provides a way of creating
      a table without having to define a compound type up front. Although this convenience
      may be attractive, users should think carefully about how data will be accessed.
      DynamicTable is more appropriate for column-centric access, whereas a dataset
      with a compound type would be more appropriate for row-centric access. Finally,
      data size should also be taken into account. For small tables, performance loss
      may be an acceptable trade-off for the flexibility of a DynamicTable.
    is_a: Container
    attributes:
      colnames:
        name: colnames
        description: The names of the columns in this table. This should be used to
          specify an order to the columns.
        range: text
      description:
        name: description
        description: Description of what is in this dynamic table.
        range: text
      id:
        name: id
        description: Array of unique identifiers for the rows of this dynamic table.
        multivalued: false
        range: DynamicTable_id
        required: true
      VectorData:
        name: VectorData
        description: Vector columns, including index columns, of this dynamic table.
        multivalued: true
        range: VectorData
        required: false
  DynamicTable_id:
    name: DynamicTable_id
    description: Array of unique identifiers for the rows of this dynamic table.
    is_a: ElementIdentifiers
    attributes:
      array:
        name: array
        range: DynamicTable_id_Array
  DynamicTable_id_Array:
    name: DynamicTable_id_Array
    is_a: Arraylike
    attributes:
      num_rows:
        name: num_rows
        range: int
        required: true
  AlignedDynamicTable:
    name: AlignedDynamicTable
    description: DynamicTable container that supports storing a collection of sub-tables.
      Each sub-table is a DynamicTable itself that is aligned with the main table
      by row index. I.e., all DynamicTables stored in this group MUST have the same
      number of rows. This type effectively defines a 2-level table in which the main
      data is stored in the main table implemented by this type and additional columns
      of the table are grouped into categories, with each category being represented
      by a separate DynamicTable stored within the group.
    is_a: DynamicTable
    attributes:
      categories:
        name: categories
        description: The names of the categories in this AlignedDynamicTable. Each
          category is represented by one DynamicTable stored in the parent group.
          This attribute should be used to specify an order of categories and the
          category names must match the names of the corresponding DynamicTable in
          the group.
        range: text
      DynamicTable:
        name: DynamicTable
        description: A DynamicTable representing a particular category for columns
          in the AlignedDynamicTable parent container. The table MUST be aligned with
          (i.e., have the same number of rows) as all other DynamicTables stored in
          the AlignedDynamicTable parent container. The name of the category is given
          by the name of the DynamicTable and its description by the description attribute
          of the DynamicTable.
        multivalued: true
        range: DynamicTable
        required: false