diff --git a/latest/index.bs b/latest/index.bs index e2fc6bcf..ed8b6aa4 100644 --- a/latest/index.bs +++ b/latest/index.bs @@ -175,7 +175,309 @@ For this example we assume an image with 5 dimensions and axes called `t,c,z,y,x └── n +Tables {#table-layout} +---------------------- +The following describes the expected layout for tabular data. +OME-NGFF tables are compatible with the [AnnData model](https://github.com/scverse/anndata). +
+.                             # Root folder, potentially in S3,
+│                             # with a flat list of images.
+│
+└── 123.zarr
+    |
+    ├── .zgroup
+    |
+    ├── .zattrs
+    |
+    └── tables                # The tables group is a container which holds one or multiple tables that are compatible with AnnData.
+        |
+        │                     # The tables group MAY be in the root of the zarr file.
+        ├── .zgroup           # The tables group MAY be in root or in another group.
+        |
+        ├── .zattrs           # `.zattrs` MUST contain "tables", which lists the keys of the subgroups that are tables. In this case, the only table is "my_table".
+                              # hence `.zattrs` should be equal to `{ "tables": [ "my_table" ] }`.
+        |
+        └── my_table
+            │                     # The table group MAY be in the root of the zarr file.
+            ├── .zgroup           # The table group MAY be in root or in another group.
+            |
+            ├── .zattrs           # `.zattrs` MUST contain "type", which is set to `"ngff:region_table"`
+            |                     # `.zattrs` MUST contain "region", which is the path to the data the table is annotating.
+            |                     # "region" MUST be a single path (single region) or an array of paths (multiple regions).
+            |                     # "region" paths MUST be objects with a key "path" and the path value MUST be a string.
+            |                     # `.zattrs` MUST contain "region_key" if "region" is an array. "region_key" is the key in `obs` denoting which region a given row corresponds to.
+            |                     # `.zattrs` MAY contain "instance_key", which is the key in `obs` that denotes which instance in "region" the row corresponds to. If "instance_key" is not provided, the values from the `obs` `.zattrs` "_index" key is used.
+            │
+            ├── 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
+            |
+            ├── layers            # You MAY add a `layers` group, which contains dense matrices with the same shape as X.
+            │   │
+            │   ├── .zgroup
+            │   ├── .zattrs       # `.zattrs` MUST contain `"keys"`, which is an array of the names of the subgroups containing a `layer`.
+            │   │
+            │   └── layer_0       # You MAY add a zarr array for each layer
+            |       |             # Each layer array MUST have the same shape as X
+            |       |             # Each layer array SHOULD be chunked the same as X
+            |       ├── .zarray
+            |       |
+            |       ├── 0.0
+            │       │   ...
+            │       └── n.m
+            │        
+            ├── obs               # You MUST 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` MUST contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+            │   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.2.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` MUST contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+            |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.2.0"` by AnnData.
+            |   │
+            |   ├── array_col     # Columns in the var table MAY be 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
+            |   |
+            |   └── cat_col       # Columns in the var table MAY be categorical
+            |       ├── .zattrs.  # `.zattrs` MUST contain `"encoding-type"`, which is set to `"categorical"` by AnnData.
+            |       |             # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.2.0"` by AnnData.
+            |       |
+            |       ├── categories
+            |       |  ├── .zarray # categories MUST be a 1D zarr array. The rows can be chunked as the user desires.
+            |       |  |
+            |       |  └─ 0
+            |       ├── codes
+            |       |  ├── .zarray # codes MUST be a 1D zarr array. The rows can be chunked as the user desires.
+            |       |  |
+            |       |  └─ 0
+            |       |
+            |       ├── null_col  # Columns in the var table MAY nullable integer
+            |       ├── .zattrs.  # `.zattrs` MUST contain `"encoding-type"`, which is set to `"nullable-integer"` by AnnData.
+            |       |             # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |       |
+            |       ├── mask
+            |       |  ├── .zarray # categories MUST be a 1D zarr array. The rows can be chunked as the user desires.
+            |       |  |
+            |       |  └─ 0
+            |       └── values
+            |          ├── .zarray # codes MUST be a 1D zarr array. The rows can be chunked as the user desires.
+            |          |
+            |          └─ 0
+            |
+            ├── obsm              # You MAY add a obsm group comtainer. The obsm group contains arrays that annotate the rows in X.
+            |   │                 # The rows in each array MUST be index-matched to the rows in X (if present). 
+            |   |
+            │   ├── .zgroup
+            |   |
+            |   ├── .zattrs       # `.zattrs` MUST contain `"encoding-type"`, which is set to `"dict"` by AnnData.           
+            |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |   |                 # `.zattrs` MUST contain `"keys"`, which is an array of the names of the subgroups containing `obsm` arrays.
+            |   │
+            │   └── obsm_0        # You MAY add a zarr array for each obsm matrix.
+            |       |             # Each obsm array MUST have the same number of rows as X.
+            |       |             # The rows in each obsm array SHOULD be chunked the same as the rows in X.
+            |       ├── .zarray
+            |       |
+            |       ├── 0.0
+            │       │   ...
+            │       └── n.m
+            |
+            ├── varm              # You MAY add a varm group comtainer. The varm group contains arrays that annotate the columns in X.
+            |   │                 # The rows in each array MUST be index-matched to the columns in X (if present). 
+            |   |
+            │   ├── .zgroup
+            |   |
+            |   ├── .zattrs       # `.zattrs` MUST contain `"encoding-type"`, which is set to `"dict"` by AnnData.           
+            |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |   |                 # `.zattrs` MUST contain `"keys"`, which is an array of the names of the subgroups containing `varm` arrays.
+            |   │
+            │   └── varm_0        # You MAY add a zarr array for each varm matrix.
+            |       |             # Each varm array MUST have the same number of rows as columns in X.
+            |       |             # The rows in each obsm array SHOULD be chunked the same as the columns in X.
+            |       ├── .zarray
+            |       ├── 0.0
+            │       │   ...
+            │       └── n.m
+            |
+            ├── obsp              # You MAY add a obsp group comtainer. The obsp group contains sparse arrays that annotate the rows in X.
+            |   │                 # The rows in each array MUST be index-matched to the columns in X (if present). 
+            |   |
+            │   ├── .zgroup
+            |   |
+            |   ├── .zattrs       # `.zattrs` MUST contain `"encoding-type"`, which is set to `"dict"` by AnnData.           
+            |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |   |                 # `.zattrs` MUST contain `"keys"`, which is an array of the names of the subgroups containing `obsp` arrays.
+            |   │
+            │   └── obsp_0        # You MAY add a zarr group for each obsp array.
+            |       |             # Each obsp array MUST have the same number of rows as rows in X.
+            |       |
+            │       ├── .zgroup
+            |       |
+            |       ├── .zattrs   # `.zattrs` MUST contain `"encoding-type"`, which is set to `"csr_matrix"` or `"csc_matrix"` for compressed sparse row and compressed sparse column, respectively.          
+            |       │             # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |       |             # `.zattrs` MUST contain `"shape"` which is an array giving the shape of the densified array.
+            |       |
+            |       ├── data      # You MUST add a one-dimensional zarr array named "data". 
+            |       |   |         # `data` MAY be chunked as the user desires.
+            |       |   ├── .zarray
+            |       |   |
+            |       |   ├── 0
+            │       │   |   ...
+            │       |   └── n
+            |       |
+            |       ├── indices   # You MUST add a one-dimensional zarr array named "indices".
+            |       |   |         # `indices` MAY be chunked as the user desires.
+            |       |   ├── .zarray  # `indices` MUST be an `int` dtype.
+            |       |   |
+            |       |   ├── 0
+            │       │   |   ...
+            │       |   └── n
+            |       |
+            |       └── indptr    # You MUST add a one-dimensional zarr array named "indptr".
+            |           |         # `indptr` MAY be chunked as the user desires.
+            |           ├── .zarray  # `indptr` MUST be an `int` dtype.
+            |           |
+            |           ├── 0
+            │           |   ...
+            │           └── n
+            |
+            ├── varp              # You MAY add a varp group comtainer. The varp group contains sparse arrays that annotate the columns in X.
+            |   │                 # The rows in each array MUST be index-matched to the columns in X (if present). 
+            |   |
+            │   ├── .zgroup
+            |   |
+            |   ├── .zattrs       # `.zattrs` MUST contain `"encoding-type"`, which is set to `"dict"` by AnnData.           
+            |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |   |                 # `.zattrs` MUST contain `"keys"`, which is an array of the names of the subgroups containing `varp` arrays.
+            |   │
+            │   └── varp_0        # You MAY add a zarr group for each varp array.
+            |       |             # Each varp array MUST have the same number of rows as columns in X.
+            |       |
+            │       ├── .zgroup
+            |       |
+            |       ├── .zattrs   # `.zattrs` MUST contain `"encoding-type"`, which is set to `"csr_matrix"` or `"csc_matrix"` for compressed sparse row and compressed sparse column, respectively.           
+            |       │             # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+            |       |             # `.zattrs` MUST contain `"shape"` which is an array giving the shape of the densified array.
+            |       |
+            |       ├── data      # You MUST add a one-dimensional zarr array named "data". 
+            |       |   |         # `data` MAY be chunked as the user desires.
+            |       |   ├── .zarray
+            |       |   |
+            |       |   ├── 0
+            │       │   |   ...
+            │       |   └── n
+            |       |
+            |       ├── indices   # You MUST add a one-dimensional zarr array named "indices".
+            |       |   |         # `indices` MAY be chunked as the user desires.
+            |       |   ├── .zarray  # `indices` MUST be an `int` dtype.
+            |       |   |
+            |       |   ├── 0
+            │       │   |   ...
+            │       |   └── n
+            |       |
+            |       └── indptr    # You MUST add a one-dimensional zarr array named "indptr".
+            |           |         # `indptr` MAY be chunked as the user desires.
+            |           ├── .zarray  # `indptr` MUST be an `int` dtype.
+            |           |
+            |           ├── 0
+            │           |   ...
+            │           └── n
+            |
+            └── uns               # You MAY add a uns containter to store unstructured data.
+                |
+                ├── .zgroup
+                |
+                ├── .zattrs       # `.zattrs` MUST contain `"encoding-type"`, which is set to `"dict"` by AnnData.           
+                │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+                │
+                ├── group         # You MAY add zarr groups.
+                |   |             # `uns` groups MAY contain groups, dataframes, dense arrays, and sparse arrays.
+                |   |
+                |   ├── .zgroup
+                |   |
+                |   ├── .zattrs   # `.zattrs` MUST contain `"encoding-type"`, which is set to `"csr_matrix"` by AnnData.           
+                |   │             # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+                |   ...
+                |
+                ├── dataframe_0   # You MAY add dataframe group containers.
+                |   |                 # dataframes MAY be in the `uns` group or in a subgroup.
+                |   │
+                |   ├── .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` MUST contain `"encoding-type"`, which is set to `"dataframe"` by AnnData.
+                |   │                 # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.2.0"` by AnnData.
+                |   │      
+                |   └── col_0         # Each column in the obs table is a 1D zarr array.
+                |       ├── .zarray   # Each columns MUST be chunked the same, but the chunking may be chosen by the user.
+                |       │
+                |       └─ 0
+                |
+                ├── dense_array       # You MAY dense arrays as n n-dimensional zarr arrays.
+                |   │                 # `dense_array` MUST not be a complex type (i.e., MUST be a single type)
+                |   │                 # `dense_array` MAY be chunked as the user desires.
+                |   |                 # `dense array` MAY be in the `uns` group or in a subgroup.
+                |   |
+                |   ├── .zarray
+                |   ├── 0.0
+                |   │   ...
+                |   └── n.m
+                |
+                └── sparse_array  # You MAY add sparse arrays as a zarr group for each sparse array.
+                    |             # sparse arrays MAY be in the `uns` group or in a subgroup.
+                    |
+                    ├── .zgroup
+                    |
+                    ├── .zattrs      # `.zattrs` MUST contain `"encoding-type"`, which is set to `"csr_matrix"` or `"csc_matrix"` for compressed sparse row and compressed sparse column, respectively.           
+                    │                # `.zattrs` MUST contain `"encoding-version"`, which is set to `"0.1.0"` by AnnData.
+                    |                # `.zattrs` MUST contain `"shape"` which is an array giving the shape of the densified array.
+                    |
+                    ├── data         # You MUST add a one-dimensional zarr array named "data". 
+                    |   |            # `data` MAY be chunked as the user desires.
+                    |   ├── .zarray
+                    |   |
+                    |   ├── 0
+                    │   |   ...
+                    |   └── n
+                    |
+                    ├── indices      # You MUST add a one-dimensional zarr array named "indices".
+                    |   |            # `indices` MAY be chunked as the user desires.
+                    |   ├── .zarray  # `indices` MUST be an `int` dtype.
+                    |   |
+                    |   ├── 0
+                    │   |   ...
+                    |   └── n
+                    |
+                    └── indptr       # You MUST add a one-dimensional zarr array named "indptr".
+                        |            # `indptr` MAY be chunked as the user desires.
+                        ├── .zarray  # `indptr` MUST be an `int` dtype.
+                        |
+                        ├── 0
+                        |   ...
+                        └── n
+        
+
+
High-content screening {#hcs-layout} ------------------------------------