refinements to array metamodel

Author: cmungall

linkml_model/model/schema/array.yaml

@@ -1,14 +1,31 @@
-id: https://w3id.org/linkml/linkml-arrays
-name: linkml-arrays
-title: linkml-arrays
+id: https://w3id.org/linkml/lib/arrays
+name: arrays
+title: LinkML Arrays
 description: |-
-  LinkML schema to store one-dimensional series and two-dimensional arrays.
+  LinkML templates for storing one-dimensional series, two-dimensional arrays,
+  and arrays of higher dimensionality.
+
+  Status: Experimental
+
+  Note that this model is not intended to be imported direcly. Instead,
+  use `implements` to denote conformance.
+  
+status: testing
+#contributors:
+#  - github:rly
+#  - github:oruebel
+#  - github:jmchandonia
+#  - github:realmarcin
+#  - github:mavaylon1
+#  - github:ialarmedalien
+#  - github:cmungall
 
 prefixes:
-  arrays: https://w3id.org/linkml/linkml-arrays
   linkml: https://w3id.org/linkml/
+  github: https://github.com/
+  gom: https://w3id.org/gom#
 
-default_prefix: arrays
+default_prefix: linkml
 default_range: string
 
 imports:
@@ -19,37 +36,240 @@ classes:
   Any:
     class_uri: linkml:Any
 
-  OneDimensionalSeries:
-    attributes:
-      name:  # the row label
-        key: true  # unique when nested (unlike identifier, which is a global identifier)
-      length:
-        range: integer
-      values:
-        range: Any
-        multivalued: true
+  DataStructure:
+    abstract: true
+
+  Array:
+    description: >-
+      a data structure consisting of a collection of *elements*, each identified by at least one array index tuple.
+    abstract: true
+    is_a: DataStructure
+    slots:
+      - dimensionality
+      - elements
+      - array_linearization_order
+    slot_usage:
+      elements:
         required: true
+        description: >-
+          the collection of values that make up the array. The elements have a *direct* representation which is
+          an ordered sequence of values. The elements also have an *array interpretation*, where each
+          element has a unique index which is determined by array_linearization_order
 
+
+  OneDimensionalSeries:
+    is_a: Array
+    description: >-
+      An array that has one dimension
+    aliases:
+      - axis
+      - 1D array
+      - vector
+      - series
+      - row
+    slots:
+      - series_label
+      - length
+      # TODO: consider offset and rate
+    slot_usage:
+      dimensionality:
+        equals_expression: "1"
+    
   TwoDimensionalArray:
-    attributes:
-      axis0:
-        aliases:
-        - x
-        range: OneDimensionalSeries
-        rank: 0
-        required: true
-        inlined: true
-        inlined_as_list: true
-      axis1:
-        aliases:
-        - y
-        range: OneDimensionalSeries
-        rank: 1
-        required: true
-        inlined: true
-        inlined_as_list: true
-      values:
-        # this will be serialized as one big long list that should be interpreted as a 2D array
+    is_a: Array
+    description: >-
+      An array that has two dimensions
+    aliases:
+      - table
+      - matrix
+      - grid
+    slots:
+      - axis0
+      - axis1
+    slot_usage:
+      dimensionality:
+        equals_expression: "2"
+      elements:
+        description: >-
+          this will be serialized as one big long list that should be interpreted as a 2D array
+
+  ThreeDimensionalArray:
+    is_a: Array
+    description: >-
+      An array that has two dimensions
+    aliases:
+      - 3D array
+    slots:
+      - axis0
+      - axis1
+      - axis2
+    slot_usage:
+      dimensionality:
+        equals_expression: "3"
+
+  OrderedArray:
+    mixin: true
+    description: >-
+      A mixin that describes an array whose elements are mapped from a linear sequence to an array index
+      via a specified mapping
+      
+  ColumnOrderedArray:
+    mixin: true
+    description: >-
+      An array ordering that is column-order
+    slots:
+      - array_linearization_order
+    slot_usage:
+      array_linearization_order:
+        equals_string: COLUMN_MAJOR_ARRAY_ORDER
+        
+  RowOrderedArray:
+    mixin: true
+    description: >-
+      An array ordering that is row-order or generalizations thereof
+    slots:
+      - array_linearization_order
+    slot_usage:
+      array_linearization_order:
+        equals_string: ROW_MAJOR_ARRAY_ORDER
+        
+  MultiDimensionalArray:
+    is_a: Array
+    abstract: true
+    description: >-
+      An array that has more than two dimensions
+
+  ObjectAsTuple:
+    comments:
+      - not modeled as an array since this is used as a metaclass
+    implements:
+      - OneDimensionalSeries
+
+  ArrayIndex:
+    is_a: ObjectAsTuple
+
+  Operation:
+    abstract: true
+    description: >-
+      Represents the transformation of one or more inputs to one or more outputs determined by
+      zero to many operation parameters
+    slots:
+      - specified_input
+      - specified_output
+      - operation_parameters
+
+  ArrayIndexOperation:
+    description: >-
+      An operation that takes as input an Array and is parameterized by an array index tuple and
+      yields an array element
+    slot_usage:
+      specified_input:
+        range: Array
+        maximum_cardinality: 1
+      specified_output:
         range: Any
-        required: true
-        multivalued: true
+        maximum_cardinality: 1
+      operation_parameters:
+        range: ArrayIndex
+        maximum_cardinality: 1
+      
+slots:
+  dimensionality:
+    description: >-
+      The number of elements in the tuple used to access elements of an array
+    aliases:
+      - rank
+      - dimension
+      - number of axes
+      - number of elements
+    range: integer
+  axis:
+    abstract: true
+    range: OneDimensionalSeries
+    aliases:
+      - dimension
+    description: >-
+      A one dimensional series that contains elements that form one part of a tuple used to access an array
+  axis0:
+    is_a: axis
+    aliases:
+    - x
+    - dimension0
+    description: >-
+      An axis that is the zeroth index of the tuple used to access an array
+    range: OneDimensionalSeries
+    rank: 0
+    required: true
+    inlined: true
+    inlined_as_list: true
+  axis1:
+    is_a: axis
+    aliases:
+    - y
+    description: >-
+      An axis that is the index after the zeroth of the tuple used to access an array
+    range: OneDimensionalSeries
+    rank: 1
+    required: true
+    inlined: true
+    inlined_as_list: true
+  axis2:
+    is_a: axis
+    aliases:
+    - z
+    range: OneDimensionalSeries
+    rank: 2
+    required: true
+    inlined: true
+    inlined_as_list: true
+  elements:
+    # this will be serialized as one big long list that should be interpreted as a 2D array
+    range: Any
+    aliases:
+      - values
+    required: true
+    multivalued: true
+    description: >-
+      A collection of values that make up the contents of an array. These elements may be interpreted
+      as a contiguous linear sequence (direct representation) or as elements to be accessed via an
+      array index
+  series_label:  # the row label
+    key: true
+    description: >-
+      A name that uniquely identifiers a series
+  length:
+    description: >-
+      The number of elements in the array
+    range: integer
+    equals_expression: "length(elements)"
+  array_linearization_order:
+    range: ArrayLinearizationOrderOptions
+    ifabsent: "string(ROW_MAJOR_ARRAY_ORDER)"
+
+  specified_input:
+    range: DataStructure
+    multivalued: true
+  specified_output:
+    range: DataStructure
+    multivalued: true
+  operation_parameters:
+    range: Any
+    multivalued: true
+  
+enums:
+  ArrayLinearizationOrderOptions:
+    description: >-
+      Determines how a linear contiguous representation of the elements of an array map
+      to array indices
+    permissible_values:
+      COLUMN_MAJOR_ARRAY_ORDER:
+        meaning: gom:columnMajorArray
+        description: >-
+          An array layout option in which the elements in each row are stored in consecutive positions,
+          or any generalization thereof to dimensionality greater than 2
+      ROW_MAJOR_ARRAY_ORDER:
+        meaning: gom:rowMajorArray
+        description: >-
+          An array layout option in which the elements in each row are stored in consecutive positions,
+          or any generalization thereof to dimensionality greater than 2
+