Expose read_annotation_file

src/napari_cryoet_data_portal/__init__.py

@@ -6,6 +6,7 @@
     points_annotations_reader,
     read_annotation,
     read_points_annotations_ndjson,
+    read_annotation_file,
     read_tomogram,
     read_tomogram_ome_zarr,
     tomogram_ome_zarr_reader,
@@ -16,6 +17,7 @@
     "DataPortalWidget",
     "points_annotations_reader",
     "read_annotation",
+    "read_annotation_file",
     "read_tomogram",
     "read_tomogram_ome_zarr",
     "read_points_annotations_ndjson",

src/napari_cryoet_data_portal/_reader.py

@@ -212,7 +212,7 @@ def read_annotation(annotation: Annotation, *, tomogram: Optional[Tomogram] = No
     """
     warnings.warn(
         "read_annotation is deprecated from v0.4.0 because of Annotation schema changes. "
-        "Use read_annotation_files instead.",
+        "Use read_annotation_file instead.",
         category=DeprecationWarning)
     point_paths = []
     for s in annotation.annotation_shapes:
@@ -244,7 +244,7 @@ def read_annotation_files(annotation: Annotation, *, tomogram: Optional[Tomogram
         The associated tomogram, which may be used for other metadata.
 
     Yields
-    -------
+    ------
     napari layer data tuple
         The data, attributes, and type name of the layer that would be
         returned by `Points.as_layer_data_tuple` or `Labels.as_layer_data_tuple`.
@@ -256,21 +256,49 @@ def read_annotation_files(annotation: Annotation, *, tomogram: Optional[Tomogram
     >>> for data, attrs, typ in read_annotation_files(annotation):
             layer = Layer.create(data, attrs, typ)
     """
+    warnings.warn(
+        "read_annotation is deprecated from v0.4.0 because of Annotation schema changes. "
+        "Use read_annotation_file instead.",
+        category=DeprecationWarning)
     for s in annotation.annotation_shapes:
         for f in s.annotation_files:
             if layer_data := read_annotation_file(f, tomogram=tomogram):
                 yield layer_data
 
 
-def read_annotation_file(anno_file: AnnotationFile, *, tomogram: Optional[Tomogram]) -> Optional[FullLayerData]:
-    shape = anno_file.annotation_shape
+def read_annotation_file(annotation_file: AnnotationFile, *, tomogram: Optional[Tomogram] = None) -> Optional[FullLayerData]:
+    """Reads a layer from an annotation file.
+
+    Parameters
+    ----------
+    annotation_file : AnnotationFile
+        The tomogram annotation file.
+    tomogram : Tomogram, optional
+        The associated tomogram, which may be used for other metadata.
+
+    Returns
+    -------
+    napari layer data tuple
+        The data, attributes, and type name of the layer that would be
+        returned by `Points.as_layer_data_tuple` or `Labels.as_layer_data_tuple`.
+
+    Examples
+    --------
+    >>> client = Client()
+    >>> annotation_file = client.find_one(AnnotationFile)
+    >>> if layer_data := read_annotation_file(annotation_file):
+            layer = Layer.create(*layer_data)
+    """
+    shape = annotation_file.annotation_shape
+    shape_type = shape.shape_type
     anno = shape.annotation
-    if (shape.shape_type in ("Point", "OrientedPoint")) and (anno_file.format == "ndjson"):
-        return _read_points_annotation_file(anno_file, anno=anno, tomogram=tomogram)
-    elif (shape.shape_type == "SegmentationMask") and (anno_file.format == "zarr"):
-        return _read_labels_annotation_file(anno_file, anno=anno, tomogram=tomogram)
+    format = annotation_file.format
+    if (shape_type in ("Point", "OrientedPoint")) and (format == "ndjson"):
+        return _read_points_annotation_file(annotation_file, anno=anno, tomogram=tomogram)
+    elif (shape_type == "SegmentationMask") and (format == "zarr"):
+        return _read_labels_annotation_file(annotation_file, anno=anno, tomogram=tomogram)
     else:
-        logger.warning("Found unsupported annotation file: %s, %s. Skipping.", shape.shape_type, anno_file.format)
+        logger.warning("Attempted read unsupported annotation file: %s, %s. Skipping.", shape_type, format)
 
 
 def _read_points_annotation_file(anno_file: AnnotationFile, *, anno: Annotation, tomogram: Optional[Tomogram]) -> FullLayerData:

src/napari_cryoet_data_portal/_tests/conftest.py

@@ -1,6 +1,6 @@
 import pytest
 
-from cryoet_data_portal import Annotation, AnnotationShape, Client, Dataset, Tomogram
+from cryoet_data_portal import Annotation, AnnotationFile, AnnotationShape, Client, Dataset, Tomogram
 
 
 @pytest.fixture()
@@ -30,3 +30,11 @@ def annotation_with_points(client: Client) -> Annotation:
         AnnotationShape.shape_type == "Point"
     ]).pop()
     return anno_shape.annotation
+
+
+@pytest.fixture()
+def annotation_file_with_points(client: Client) -> AnnotationFile:
+    anno_file = AnnotationFile.find(client, [
+        AnnotationFile.annotation_shape.shape_type == "Point"
+    ]).pop()
+    return anno_file

src/napari_cryoet_data_portal/_tests/test_reader.py

@@ -2,12 +2,13 @@
 from typing import Callable
 
 import numpy as np
-from cryoet_data_portal import Annotation
+from cryoet_data_portal import Annotation, AnnotationFile
 from napari import Viewer
 from napari.layers import Points
 
 from napari_cryoet_data_portal._reader import (
     read_annotation,
+    read_annotation_file,
     read_annotation_files,
     read_points_annotations_ndjson,
     read_tomogram_ome_zarr,
@@ -61,10 +62,19 @@ def test_read_annotation(annotation_with_points: Annotation):
 
 
 def test_read_annotation_files(annotation_with_points: Annotation):
-    layers = list(read_annotation_files(annotation_with_points))
+    with pytest.warns(DeprecationWarning):
+        layers = list(read_annotation_files(annotation_with_points))
 
     assert len(layers) == 1
     data, attrs, layer_type = layers[0]
     assert len(data) > 0
     assert len(attrs["name"]) > 0
     assert layer_type == "points"
+
+
+def test_read_annotation_file(annotation_file_with_points: AnnotationFile):
+    data, attrs, layer_type = read_annotation_file(annotation_file_with_points)
+
+    assert len(data) > 0
+    assert len(attrs["name"]) > 0
+    assert layer_type == "points"