Documentation and Refactor

Author: Suhayb-A

examples/example.ipynb

@@ -1,3 +1,2 @@
 from .annotations import Annotations as MapAnnotations
-from .loader.imageio import MultiImageLoader
-from .loader.mmap import MMapLoader
+from .lazy_geo_pd_images.loader import MultiImageLoader

mapmanagercore/__init__.py

@@ -9,6 +9,7 @@ def __init__(self, loadJson : str = None):
         # self.__version__ = 0.1
         # self.__version__ = 0.1  # switched to dict of dicts
         self.__version__ = 0.2  # 20240508 added anchorPointSearchDistance
+        self.__version__ = 0.3  # segmentTracingMaxDistance
 
         if loadJson is not None:
             self._dict = json.loads(loadJson)
@@ -67,6 +68,13 @@ def _getDefauls(self):
                 'currentValue': 4,
                 'description': 'Radius of segment tracing.'
             },
+            
+            # The distance 
+            'segmentTracingMaxDistance': {
+                'defaultValue': 30,
+                'currentValue': 30,
+                'description': 'Max distance to trace a brightest path with relatively low performance cost.'
+            },
 
             # anchor point search distance
             # 'anchorPointSearchDistance': {

mapmanagercore/analysis_params.py

@@ -1,36 +1,50 @@
 from copy import copy
-from typing import Any, Tuple
+from io import BytesIO
+from typing import Any, Tuple, Union
 import zipfile
 import numpy as np
 import pandas as pd
 
 from mapmanagercore.benchmark import timer
-from mapmanagercore.config import COLORS, scaleColors, symbols
+from mapmanagercore.config import Colors, scaleColors, symbols
+from mapmanagercore.lazy_geo_pd_images.loader.zarr import ZarrLoader
 from ..lazy_geo_pandas import LazyGeoFrame
 from ..schemas import Segment, Spine
-from ..lazy_geo_pd_image import LazyImagesGeoPandas
-from ..image_slices import ImageSlice
-from ..loader.base import ImageLoader, Loader
+from ..lazy_geo_pd_images import LazyImagesGeoPandas, ImageLoader
+from ..lazy_geo_pd_images.image_slices import ImageSlice
 import zarr
 import warnings
 from plotly.express.colors import sample_colorscale
+import geopandas as gp
 
 from mapmanagercore.analysis_params import AnalysisParams
-from mapmanagercore.logger import logger
 
 
 class AnnotationsBase(LazyImagesGeoPandas):
     _images: ImageLoader
 
-    def __init__(self, loader: Loader):
-        super().__init__(loader.images())
+    def __init__(self,
+                 loader: ImageLoader,
+                 lineSegments: Union[str, pd.DataFrame] = pd.DataFrame(),
+                 points: Union[str, pd.DataFrame] = pd.DataFrame(),
+                 analysisParams: AnalysisParams = AnalysisParams()):
 
-        self._segments = LazyGeoFrame(
-            Segment, data=loader.segments(), store=self)
-        self._points = LazyGeoFrame(Spine, data=loader.points(), store=self)
+        super().__init__(loader)
+
+        if not isinstance(lineSegments, gp.GeoDataFrame):
+            if not isinstance(lineSegments, pd.DataFrame):
+                lineSegments = pd.read_csv(lineSegments, index_col=False)
+
+        if not isinstance(points, gp.GeoDataFrame):
+            if not isinstance(points, pd.DataFrame):
+                points = pd.read_csv(points, index_col=False)
 
         # abb analysisparams
-        self._analysisParams: AnalysisParams = loader.analysisParams()
+        self._analysisParams: AnalysisParams = analysisParams
+
+        self._segments = LazyGeoFrame(
+            Segment, data=lineSegments, store=self)
+        self._points = LazyGeoFrame(Spine, data=points, store=self)
 
     @property
     def segments(self) -> LazyGeoFrame:
@@ -45,16 +59,25 @@ def analysisParams(self) -> AnalysisParams:
         return self._analysisParams
 
     def filterPoints(self, filter: Any):
+        """
+        Filters the points.
+        """
         c = copy(self)
         c._points = c._points[filter]
         return c
 
     def filterSegments(self, filter: Any):
+        """
+        Filters the segments.
+        """
         c = copy(self)
         c._segments = c._segments[filter]
         return c
 
     def getTimePoint(self, time: int):
+        """
+        Returns the annotations for a single time point.
+        """
         from .single_time_point import SingleTimePointAnnotations
         return SingleTimePointAnnotations(self, time)
 
@@ -83,10 +106,26 @@ def getPixels(self, time: int, channel: int, zRange: Tuple[int, int] = None, z:
 
         return super().getPixels(time, channel, zRange)
 
+    # Serialization
+
+    @classmethod
+    def load(cls, path: str, lazy=False):
+        loader = ZarrLoader(path, lazy=lazy)
+        points = pd.read_pickle(BytesIO(loader.group["points"][:].tobytes()))
+        points = gp.GeoDataFrame(points, geometry="point")
+        lineSegments = pd.read_pickle(
+            BytesIO(loader.group["lineSegments"][:].tobytes()))
+        lineSegments = gp.GeoDataFrame(lineSegments, geometry="segment")
+
+        # abb analysisparams
+        _analysisParams_json = loader.group.attrs['analysisParams']  # json str
+        analysisParams = AnalysisParams(loadJson=_analysisParams_json)
+
+        return cls(loader, lineSegments, points, analysisParams)
+
     def save(self, path: str, compression=zipfile.ZIP_STORED):
         if not path.endswith(".mmap"):
-            raise ValueError(
-                "Invalid file format. Please provide a path ending with '.mmap'.")
+            path += ".mmap"
 
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")
@@ -104,6 +143,8 @@ def save(self, path: str, compression=zipfile.ZIP_STORED):
                 # abb analysisparams
                 group.attrs['analysisParams'] = self._analysisParams.getJson()
 
+    # Context manager
+
     def __enter__(self):
         self._images = self._images.__enter__()
         return self
@@ -115,12 +156,17 @@ def close(self):
         self._images.close()
         return
 
+    # Utility functions
+
     @timer
     def getColors(self, colorOn: str = None, function=False) -> pd.Series:
+        """
+        Returns the colors of the points.
+        """
         if colorOn is None:
             if function:
-                return lambda _: COLORS["spine"]
-            return pd.Series([COLORS["spine"]] * len(self.points), index=self.points.index)
+                return lambda _: Colors.spine
+            return pd.Series([Colors.spine] * len(self.points), index=self.points.index)
 
         categorical = False
         if colorOn not in self.points.columnsAttributes:
@@ -130,12 +176,12 @@ def getColors(self, colorOn: str = None, function=False) -> pd.Series:
         if "colors" in attr:
             colors = attr["colors"]
         elif "categorical" in attr and attr["categorical"]:
-            colors = COLORS["categorical"]
+            colors = Colors.categorical
             categorical = True
         elif "divergent" in attr and attr["divergent"]:
-            colors = COLORS["divergent"]
+            colors = Colors.divergent
         else:
-            colors = COLORS["scalar"]
+            colors = Colors.scalar
 
         if colorOn in self.points.index.names:
             values = pd.Series(self.points.index.get_level_values(
@@ -176,6 +222,9 @@ def extractColor(x):
 
     @timer
     def getSymbols(self, shapeOn: str = None, function=False) -> pd.Series:
+        """
+        Returns the symbols of the points.
+        """
         if shapeOn is None:
             if function:
                 return lambda _: "circle"

mapmanagercore/annotations/base.py

@@ -1,20 +1,23 @@
 from typing import Tuple, Union
-from mapmanagercore.lazy_geo_pandas.schema import MISSING_VALUE
 from ..schemas import Spine, Segment
 from ..config import SegmentId, SpineId
 from .base import AnnotationsBase
 
-from mapmanagercore.logger import logger
-
 Key = Union[SpineId, Tuple[SpineId, int]]
 Keys = Union[Key, list[Key]]
 
 
 class AnnotationsBaseMut(AnnotationsBase):
-    def deleteSpine(self, spineId: Keys, skipLog=False) -> None:
+    def deleteSpine(self, spineId: Keys, skipLog=False):
+        """
+        Delete the spine with the given ID.
+        """
         self._drop("Spine", spineId, skipLog=skipLog)
 
-    def deleteSegment(self, segmentId: Keys, skipLog=False) -> None:
+    def deleteSegment(self, segmentId: Keys, skipLog=False):
+        """
+        Delete the segment with the given ID.
+        """
         try:
             if not self.points[["segmentID"]].reset_index().set_index(["segmentID", "t"]).loc[segmentId].empty:
                 raise ValueError(
@@ -26,47 +29,28 @@ def deleteSegment(self, segmentId: Keys, skipLog=False) -> None:
 
     def updateSpine(self, spineId: Keys, value: Spine, replaceLog=False, skipLog=False):
         """
-        Set the spine with the given ID to the specified value.
-
-        Parameters:
-            spineId (str): The ID of the spine.
-            value (Union[dict, gp.Series, pd.Series]): The value to set for the spine.
+        Set the spine with the given ID to the specified value.            
         """
-
-        # if value.t != MISSING_VALUE:
-        #     raise ValueError(
-        #         f"Invalid type for column 't' must be set on the spine key")
-
-        # if value.spineID != MISSING_VALUE:
-        #     raise ValueError(
-        #         f"Invalid type for column 'spineID' must be set on the spine key")
-
         return self._update("Spine", spineId, value, replaceLog, skipLog)
 
     def updateSegment(self, segmentId: Keys, value: Segment, replaceLog=False, skipLog=False):
         """
         Set the segment with the given ID to the specified value.
-
-        Parameters:
-            segmentId (str): The ID of the spine.
-            value (Union[dict, gp.Series, pd.Series]): The value to set for the spine.
         """
-        # if value.t != MISSING_VALUE:
-        #     raise ValueError(
-        #         f"Invalid type for column 't' must be set on the segment key")
-
-        # if value.segmentID != MISSING_VALUE:
-        #     raise ValueError(
-        #         f"Invalid type for column 'segmentID' must be set on the segment key")
-
         return self._update("Segment", segmentId, value, replaceLog, skipLog)
 
     def newUnassignedSpineId(self) -> SpineId:
+        """
+        Returns a new unassigned spine ID.
+        """
         if len(self.points) == 0:
             return 0
         return self.points.index.get_level_values(0).max() + 1
 
     def newUnassignedSegmentId(self) -> SegmentId:
+        """
+        Returns a new unassigned segment ID.
+        """
         if len(self.segments) == 0:
             return 0
         return self.segments.index.get_level_values(0).max() + 1

mapmanagercore/annotations/mutation.py

@@ -1,18 +1,13 @@
-from io import BytesIO, StringIO
 import json
 from typing import Tuple
-
 import numpy as np
-
 from ..benchmark import timeAll
 from ..config import SpineId
 from .single_time_point.layers import AnnotationsOptions
-from ..image_slices import ImageSlice
+from ..lazy_geo_pd_images.image_slices import ImageSlice
 from ..layers.utils import inRange
-from ..loader.mmap import MMapLoader
 from ..utils import filterMask
 from . import Annotations
-from pyodide.http import pyfetch
 from pyodide.ffi import to_js
 from .single_time_point import SingleTimePointAnnotations
 
@@ -28,9 +23,11 @@ def getAnnotations_js(self, options: AnnotationsOptions):
         return [layer.encodeBin() for layer in layers]
 
     def metadata_json(self):
-        return json.dumps(self.metadata())
+        """Returns the metadata as a JSON string."""
+        return self.metadata().to_json()
 
     def getSpinePosition(self, spineID: SpineId):
+        """Returns the position of a spine in the current time point."""
         if (spineID, self._t) not in self._annotations.points.index:
             return None
         return to_js(list(self._annotations.points[(spineID, self._t), "point"].coords)[0])
@@ -80,10 +77,6 @@ class PyodideAnnotations(Annotations):
     """ PyodideAnnotations contains pyodide specific helper methods to allow JS to use Annotations.
     """
 
-    async def load(path: str):
-        loader = MMapLoader(path)
-        return PyodideAnnotations(loader)
-
     def timePoint_js(self, time: int):
         return PyodideSingleTimePoint(self, time)
 
@@ -102,7 +95,9 @@ def slices_js(self, time: int, channel: int, zRange: Tuple[int, int]) -> ImageSl
         return self.getPixels(time, channel, (zRange[0], zRange[1]))
 
     def table(self):
-        columns = [key for key, value in self.points.columnsAttributes.items() if value["plot"]]
+        """Returns the points as a pandas DataFrame."""
+        columns = [
+            key for key, value in self.points.columnsAttributes.items() if value["plot"]]
         columns.remove("t")
         df = self.points[columns].reset_index()
         for i, type in enumerate(df.dtypes):
@@ -111,6 +106,7 @@ def table(self):
         return df
 
     def getColumn(self, column: str):
+        """Returns the values of a column in the points DataFrame."""
         if column in self.points.index.names:
             result = self.points.index.get_level_values(column).to_list()
         else:
@@ -121,21 +117,13 @@ def getColumn(self, column: str):
         return result
 
     def getColors(self, colorOn: str = None):
+        """Returns the colors of the points in the DataFrame."""
         return super().getColors(colorOn).to_list()
-    
+
     def getSymbols(self, shapeOn: str = None):
+        """Returns the symbols of the points in the DataFrame."""
         return super().getSymbols(shapeOn).to_list()
 
     def columnsAttributes_json(self):
+        """Returns the columnsAttributes as a JSON string."""
         return json.dumps(self.points.columnsAttributes, skipkeys=True)
-
-
-async def loadGeoCsv(path):
-    response = await pyfetch(path)
-    csv_text = await response.text()
-    return StringIO(csv_text)
-
-
-async def fetchBytes(url: str):
-    response = await pyfetch(url)
-    return BytesIO(await response.memoryview())