Table spec proposal

latest/index.bs

@@ -154,6 +154,108 @@ multiple levels of resolutions and optionally associated labels.
                 │   ...       # are supported.
                 └── n
 ```
+Tables {#table-layout}
+----------------------
+The following describes the expected layout for tabular data. OME-NGFF tables are a compatible subset of the [AnnData model](https://github.com/theislab/anndata). OME-NGFF tables implement the X (central dense matrix), the obs table (annotations on the rows of X) and the var table (annotations on the columns of X).
+
+```
+.                             # Root folder, potentially in S3,
+│                             # with a flat list of images by image ID.
+│
+└── 123.zarr
+    └── table                 # The table group is a container which holds a table that is compatible with a subset of AnnData.
+        │                     # The table group MAY be in the root of the zarr file.
+        ├── .zgroup           # The table group MAY be in an image, labels, or points group.
+        ├── .zattrs              
+        │
+        ├── X                 # You MAY add an zarr array `X`.
+        │   │                 # `X` MUST not be a complex type (i.e., MUST be a single type)
+        │   │                 # `X` MAY be chunked as the user desires.
+        │   ├── .zarray
+        │   ├── 0.0
+        │   │   ...
+        │   └── n.m
+        │        
+        ├── obs               # You MAY add an obs group container. The obs group holds a table of annotations on the rows in X.
+        │   │                 # The rows in obs MUST be index-matched to the rows in X.
+        │   ├── .zgroup
+        │   │                     
+        │   ├── .zattrs       # `.zattrs` MUST contain `"_index"`, which is the name of the column in obs to be used as the index.           
+        │   │                 # `.zattrs` MUST contain `"column-order"`, which is a list of the order of the non-_index columns.
+        │   │                 # `.zattrs` MAY contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+        │   │                 # `.zattrs` MAY contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+        │   │      
+        │   └── col_0         # Each column in the obs table is a 1D zarr array. The rows can be chunked as the user desires.
+        │       ├── .zarray   # However, the obs columns SHOULD be chunked in the same way as the rows in X (if present).
+        │       │
+        │       └─ 0
+        └── var               # You MAY add a var group container. The var group holds a table of annotations on the columns in X.
+            │                 # The rows in var MUST be index-matched to the columns in X (if present). 
+            |
+            ├── .zattrs       # `.zattrs` MUST contain `"_index"`, which is the name of the column in obs to be used as the index.           
+            │                 # `.zattrs` MUST contain `"column-order"`, which is a list of the order of the non-_index columns.
+            │                 # `.zattrs` MAY contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+            │                 # `.zattrs` MAY contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            │
+            └── col_0         # Each column in the var table is a 1D zarr array. The rows can be chunked as the user desires.
+                ├── .zarray   # However, the var columns SHOULD be chunked in the same way as the columns in X.
+                │
+                └─ 0
+```
+
+Points {#points-layout}
+-----------------------
+The following describes the expected layout for point annotations in OME-NGFF. Point annotations are tables with some specified columns and layout.
+
+```
+.                             # Root folder, potentially in S3,
+│                             # with a flat list of images by image ID.
+│
+└── 123.zarr
+    └── points                # The points group is a container which holds a table that is compatible with a subset of AnnData.
+        │                     # The points group MAY be in the root of the zarr file.
+        ├── .zgroup           # The table group MAY be in an image or labels group.
+        ├── .zattrs              
+        │
+        ├── X                 # You MUST add an zarr array `X`.
+        │   │                 # `X` MUST contain the coordinates for the points.
+        │   │                 # `X` MAY contain data in addition to the coordinates.
+        │   │                 # `X` MAY be chunked as the user desires.
+        │   ├── .zarray
+        │   ├── 0.0
+        │   │   ...
+        │   └── n.m
+        │        
+        ├── obs               # You MAY add an obs group container. The obs group holds a table of annotations for the points in X.
+        │   │                 # The rows in obs MUST be index-matched to the rows in X.
+        │   │                 
+        │   ├── .zgroup
+        │   │                     
+        │   ├── .zattrs       # `.zattrs` MUST contain `"_index"`, which is the name of the column in obs to be used as the index.           
+        │   │                 # `.zattrs` MUST contain `"column-order"`, which is a list of the order of the non-_index columns.
+        │   │                 # `.zattrs` MAY contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+        │   │                 # `.zattrs` MAY contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+        │   │      
+        │   └── col_0         # Each column in the obs table is a 1D zarr array. The rows can be chunked as the user desires.
+        │       ├── .zarray   # However, the obs columns SHOULD be chunked in the same way as the rows in X.
+        │       │
+        │       └─ 0
+        └── var               # You MUST add a var group container. The var group holds a table of annotations on the columns in X.
+            |                 # The var group MUST contain a column called `column_name` that annotates what each column in X contains.
+            |                 # The `column_name` column must annotate the columns in X containing coordinates with 0_p, 1_p, ..., n_p.
+            │                 # The rows in var MUST be index-matched to the columns in X. 
+            |
+            ├── .zattrs       # `.zattrs` MUST contain `"_index"`, which is the name of the column in obs to be used as the index.           
+            │                 # `.zattrs` MUST contain `"column-order"`, which is a list of the order of the non-_index columns.
+            │                 # `.zattrs` MAY contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+            │                 # `.zattrs` MAY contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            │
+            └── col_0         # Each column in the var table is a 1D zarr array. The rows can be chunked as the user desires.
+                ├── .zarray   # However, the var columns SHOULD be chunked in the same way as the columns in X.
+                │
+                └─ 0
+```
+
 
 High-content screening {#hcs-layout}
 ------------------------------------