Merge pull request #582 from fractal-analytics-platform/529-write-doc…

…s-page-for-fractal-tasks-core-rois-v1

Define table specifications

CHANGELOG.md

@@ -13,6 +13,10 @@
 * Remove assumptions on ROI-table columns from `get_ROI_table_with_translation` helper function of `calculate_registration_image_based` task (\#591).
 * Testing:
     * Cache Zenodo data, within GitHub actions (\#585).
+* Documentation:
+    * Define V1 of table specs (\#582).
+    * Add mathjax support (\#582).
+    * Add cross-reference inventories to external APIs (\#582).
 
 # 0.13.0
 

docs/javascripts/mathjax.js

@@ -0,0 +1,16 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.typesetPromise()
+})

fractal_tasks_core/__init__.py

@@ -7,3 +7,4 @@
 
 __VERSION__ = "0.13.1"
 __OME_NGFF_VERSION__ = "0.4"
+__FRACTAL_TABLE_VERSION__ = "1"

fractal_tasks_core/lib_ngff.py

@@ -6,7 +6,7 @@
 from typing import Optional
 from typing import Union
 
-import zarr
+import zarr.hierarchy
 from pydantic import BaseModel
 from pydantic import Field
 from pydantic import validator
@@ -422,7 +422,7 @@ def load_NgffWellMeta(zarr_path: str) -> NgffWellMeta:
         raise e
 
 
-def detect_ome_ngff_type(group: zarr.Group) -> str:
+def detect_ome_ngff_type(group: zarr.hierarchy.Group) -> str:
     """
     Given a Zarr group, find whether it is an OME-NGFF plate, well or image.
 

fractal_tasks_core/lib_regions_of_interest.py

@@ -183,6 +183,10 @@ def convert_ROIs_from_3D_to_2D(
     """
     TBD
 
+    Note that this function is only relevant when the ROIs in adata span the
+    whole extent of the Z axis.
+    TODO: check this explicitly.
+
     Args:
         adata: TBD
         pixel_size_z: TBD

fractal_tasks_core/lib_write.py

@@ -18,11 +18,13 @@
 from typing import Union
 
 import anndata as ad
-import zarr
+import zarr.hierarchy
 from anndata.experimental import write_elem
 from zarr.errors import ContainsGroupError
 from zarr.errors import GroupNotFoundError
 
+from fractal_tasks_core import __FRACTAL_TABLE_VERSION__
+
 
 class OverwriteNotAllowedError(RuntimeError):
     pass
@@ -34,7 +36,7 @@ def open_zarr_group_with_overwrite(
     overwrite: bool,
     logger: Optional[logging.Logger] = None,
     **open_group_kwargs: Any,
-) -> zarr.Group:
+) -> zarr.hierarchy.Group:
     """
     Wrap `zarr.open_group` and add `overwrite` argument.
 
@@ -122,7 +124,7 @@ def open_zarr_group_with_overwrite(
 
 
 def _write_elem_with_overwrite(
-    group: zarr.Group,
+    group: zarr.hierarchy.Group,
     key: str,
     elem: Any,
     *,
@@ -184,7 +186,7 @@ def _write_elem_with_overwrite(
 
 
 def write_table(
-    image_group: zarr.Group,
+    image_group: zarr.hierarchy.Group,
     table_name: str,
     table: ad.AnnData,
     overwrite: bool = False,
@@ -291,11 +293,14 @@ def write_table(
         # Update table_group attributes with table_attrs key/value pairs
         table_group.attrs.update(**table_attrs)
 
+    # Always add information about the fractal-roi-table version
+    table_group.attrs.update(fractal_table_version=__FRACTAL_TABLE_VERSION__)
+
     return table_group
 
 
 def prepare_label_group(
-    image_group: zarr.Group,
+    image_group: zarr.hierarchy.Group,
     label_name: str,
     overwrite: bool = False,
     label_attrs: Optional[dict[str, Any]] = None,

mkdocs.yml

@@ -4,20 +4,28 @@ repo_url: https://github.com/fractal-analytics-platform/fractal-tasks-core
 repo_name: fractal-tasks-core
 
 markdown_extensions:
-- admonition
-- pymdownx.details
-- pymdownx.emoji
-- pymdownx.magiclink
-- pymdownx.snippets:
-    check_paths: true
-    base_path:
-      - fractal_tasks_core/__FRACTAL_MANIFEST__.json
-- pymdownx.superfences
-- pymdownx.tabbed:
-    alternate_style: true
-- pymdownx.tasklist
-- toc:
-    permalink: true
+  - admonition
+  - pymdownx.details
+  - pymdownx.emoji
+  - pymdownx.magiclink
+  - pymdownx.snippets:
+      check_paths: true
+      base_path:
+        - fractal_tasks_core/__FRACTAL_MANIFEST__.json
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex:
+      generic: true
+  - footnotes
+
+extra_javascript:
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 
 theme:
   name: "material"
@@ -51,6 +59,7 @@ nav:
   - Run tasks in Python scripts: tasks_in_scripts.md
   - Write a custom task: custom_task.md
   - Task manifest: manifest.md
+  - Tables: tables.md
   - Code reference: reference/fractal_tasks_core/
   - Development: development.md
   - Changelog: changelog.md
@@ -71,6 +80,13 @@ plugins:
       default_handler: python
       handlers:
         python:
+          import:
+            - url: https://docs.python.org/objects.inv
+            - url: https://numpy.org/doc/stable/objects.inv
+            - url: https://zarr.readthedocs.io/en/stable/objects.inv
+            - url: https://anndata.readthedocs.io/en/latest/objects.inv
+            - url: https://docs.dask.org/en/stable/objects.inv
+            # - url: https://docs.pydantic.dev/latest/objects.inv # This points to V2
           options:
             show_signature_annotations: false
             docstring_section_style: "spacy"

tests/test_unit_zarr.py

@@ -4,6 +4,7 @@
 import zarr
 from devtools import debug
 
+from fractal_tasks_core import __FRACTAL_TABLE_VERSION__
 from fractal_tasks_core.lib_write import _write_elem_with_overwrite
 from fractal_tasks_core.lib_write import open_zarr_group_with_overwrite
 from fractal_tasks_core.lib_write import OverwriteNotAllowedError
@@ -127,6 +128,10 @@ def test_write_table(tmp_path):
     assert image_group["tables"].attrs.asdict() == dict(tables=["table_a"])
     for key in ["region", "instance_key", "type"]:
         assert key not in table_a_group.attrs.keys()
+    assert (
+        table_a_group.attrs["fractal_table_version"]
+        == __FRACTAL_TABLE_VERSION__
+    )
 
     # Run write_table again, with overwrite=True
     table_a_group = write_table(