ossify 0.2.0__tar.gz → 0.2.2__tar.gz

{ossify-0.2.0 → ossify-0.2.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: ossify
-Version: 0.2.0
+Version: 0.2.2
 Summary: Mesh and skeleton analysis
 Author-email: Casey Schneider-Mizell <caseysm@gmail.com>
 License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.11
-Requires-Dist: caveclient>=7.6.0
+Requires-Dist: caveclient>=8.2.1
 Requires-Dist: cloud-files>=5.8.0
 Requires-Dist: fastremap>=1.15.1
 Requires-Dist: matplotlib>=3.10.6

{ossify-0.2.0 → ossify-0.2.2}/pyproject.toml

@@ -6,12 +6,12 @@ build-backend = "hatchling.build"
 allow-direct-references = true
 [project]
 name = "ossify"
-version = "0.2.0"
+version = "0.2.2"
 description = "Mesh and skeleton analysis"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "caveclient>=7.6.0",
+    "caveclient>=8.2.1",
     "numpy>=2.0.2",
     "scipy>=1.15",
     "trimesh>=4.6.2",
@@ -95,7 +95,7 @@ default-groups = ["dev", "docs", "lint", "profile", "viz"]
 
 
 [tool.bumpversion]
-current_version = "0.2.0"
+current_version = "0.2.2"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 regex = false
@@ -136,8 +136,22 @@ cmd = "uv run bump-my-version bump"
 help = "Bump the version number in the project. Use with 'patch', 'minor', or 'major' to specify the version change."
 
 [tool.poe.tasks.test]
-cmd = "uv run pytest --cov=ossify tests"
-help = "Run pytest with code coverage."
+cmd = "uv run pytest --cov=ossify --cov-branch --cov-report=term-missing tests"
+help = "Run pytest with branch coverage and a missing-lines report."
+
+[tool.pytest.ini_options]
+# src-layout: put the package on the path so tests import ossify from src/
+# during collection without relying on the editable install being present.
+pythonpath = ["src"]
+
+[tool.coverage.run]
+branch = true
+source = ["ossify"]
+
+[tool.coverage.report]
+# Surface partially-covered branches, not just uncovered lines.
+show_missing = true
+skip_covered = false
 
 [tool.poe.tasks.doc-preview]
 cmd = "uv run mkdocs serve"

{ossify-0.2.0 → ossify-0.2.2}/src/ossify/__init__.py

@@ -5,7 +5,7 @@ from .base import *
 from .file_io import *
 from .translate import *
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 
 def __getattr__(name):

{ossify-0.2.0 → ossify-0.2.2}/src/ossify/base.py

@@ -848,6 +848,25 @@ class Cell:
             )
         return pd.concat(remap_features, axis=1)
 
+    def _close(self) -> None:
+        """Release this Cell's data and break the layer<->cell reference cycle.
+
+        Layers hold a back-reference to their Cell (and vice versa), so a Cell
+        is only reclaimed by the cyclic garbage collector, not by refcounting.
+        ``mask_context`` calls this on exit so the temporary masked copy is torn
+        down immediately -- freeing its (potentially large) data as soon as the
+        block ends rather than lingering until the next gc pass. The Cell must
+        not be used after it is closed.
+        """
+        if self._morphsync is None:
+            return
+        for obj in list(self._all_objects.values()):
+            obj._cell = None
+            obj._morphsync = None
+        self._managed_layers.clear()
+        self._annotations._layers.clear()
+        self._morphsync = None
+
     @contextlib.contextmanager
     def mask_context(
         self,
@@ -856,6 +875,10 @@ class Cell:
     ) -> Generator[Self, None, None]:
         """Create a masked version of the MeshWork object in a context state.
 
+        The masked Cell is a temporary scoped to the ``with`` block: it is torn
+        down when the block exits (including on error), so do not retain it or
+        any of its layers past the context.
+
         Parameters
         ----------
         layer: str
@@ -872,7 +895,7 @@ class Cell:
         try:
             yield nrn_out
         finally:
-            pass
+            nrn_out._close()
 
     def _cleanup_links(self, layer_name: str) -> None:
         """Remove all links involving the specified layer from MorphSync."""

{ossify-0.2.0 → ossify-0.2.2}/src/ossify/data_layers.py

@@ -200,9 +200,11 @@ class EdgeMixin(ABC):
             )
         if limit is None:
             limit = np.inf
+        # source_target_distances returns a (len(sources), len(targets)) matrix
+        # and indexes by these arrays, so scalar inputs must be promoted to 1-d.
         return gf.source_target_distances(
-            sources=sources,
-            targets=targets,
+            sources=np.atleast_1d(sources),
+            targets=np.atleast_1d(targets),
             csgraph=self.csgraph_undirected,
             limit=limit,
         )
@@ -305,6 +307,16 @@ class FaceMixin(ABC):
             )
         return self._csgraph
 
+    def _reset_derived_properties(self) -> None:
+        """Reset cached properties derived from vertex positions.
+
+        The distance-weighted ``csgraph`` and the ``trimesh`` object both embed
+        vertex coordinates, so they must be dropped when the geometry changes
+        (e.g. after a spatial transform).
+        """
+        self._csgraph = None
+        self._trimesh = None
+
     def _map_faces_to_index(
         self, faces: np.ndarray, vertex_indices: np.ndarray
     ) -> np.ndarray:
@@ -472,7 +484,12 @@ class PointMixin(ABC):
                 vertex_index_map = self.vertex_index_map
             else:
                 vertex_index_map = {v: i for i, v in enumerate(vertex_index)}
-            vertices = fastremap.remap(vertices, vertex_index_map)
+            # fastremap.remap rejects 0-d arrays, so a scalar vertex would crash
+            # here. Remap on a 1-d view and restore the caller's shape, keeping
+            # scalar-in -> scalar-out (as the positional path already does).
+            vertices = fastremap.remap(
+                np.atleast_1d(vertices), vertex_index_map
+            ).reshape(vertices.shape)
         vertices = np.array(vertices)
         return vertices, as_positional
 
@@ -1090,9 +1107,10 @@ class PointMixin(ABC):
             new_morphsync.layers.pop(l)
         new_morphsync.links = {}
 
-        return self.__class__._from_existing(
-            new_morphsync=new_morphsync, old_obj=self._cell
-        )
+        # Copy this layer alone, detached from any Cell: build it from this
+        # layer's own metadata (``_from_existing`` reads ``.nodes``/``.edges``/
+        # etc.), not from ``self._cell`` (a Cell has no such layer attributes).
+        return self.__class__._from_existing(new_morphsync=new_morphsync, old_obj=self)
 
     def transform(
         self, transform: Union[np.ndarray, Callable], inplace: bool = False
@@ -1111,8 +1129,22 @@ class PointMixin(ABC):
             target.layer.nodes[target.spatial_columns] = transform(
                 target.layer.vertices
             )
+        # Moving vertices changes Euclidean distances, so any geometry-derived
+        # caches (distance-weighted csgraph, trimesh, base graphs) are now stale.
+        target._invalidate_spatial_caches()
         return target
 
+    def _invalidate_spatial_caches(self) -> None:
+        """Invalidate caches derived from vertex positions.
+
+        Called after a spatial transform. Distance-weighted graphs and mesh
+        objects depend on coordinates and must be rebuilt. Layers without such
+        caches (e.g. plain point clouds) do nothing.
+        """
+        reset = getattr(self, "_reset_derived_properties", None)
+        if reset is not None:
+            reset()
+
     @contextlib.contextmanager
     def mask_context(self, mask: np.ndarray) -> Generator[Self, None, None]:
         """Context manager to temporarily apply a mask via the current layer.
@@ -1136,7 +1168,7 @@ class PointMixin(ABC):
         try:
             yield new_self
         finally:
-            pass
+            new_self._close()
 
     def _register_cell(self, mws: "Cell") -> None:
         """Register a Cell object with this layer.
@@ -1148,6 +1180,18 @@ class PointMixin(ABC):
         """
         self._cell = mws
 
+    def _close(self) -> None:
+        """Release this layer's data and detach it from any Cell.
+
+        Used by ``mask_context`` (when it yields a bare layer rather than a
+        Cell) so the temporary masked copy is torn down when the block exits.
+        The layer must not be used after it is closed. See ``Cell._close``.
+        """
+        if self._morphsync is None:
+            return
+        self._cell = None
+        self._morphsync = None
+
     def get_unmapped_vertices(
         self,
         target_layers: Optional[Union[str, List[str]]] = None,
@@ -2117,6 +2161,17 @@ class SkeletonLayer(GraphLayer):
         super()._reset_derived_properties()
         self._dag_cache = gf.DAGCache()
 
+    def _invalidate_spatial_caches(self) -> None:
+        # Drops the lazy csgraph/dag caches, then refresh the eagerly-stored
+        # distance-weighted base graph from the transformed coordinates. The
+        # base graph is a snapshot of the original geometry, so this is only
+        # possible when unmasked -- a masked skeleton's base graph spans
+        # vertices that are absent here and cannot be rebuilt. (The binary base
+        # graph is topology-only and unaffected by a spatial transform.)
+        super()._invalidate_spatial_caches()
+        if np.array_equal(self.vertex_index, self.base_vertex_index):
+            self._base_properties["base_csgraph"] = self.csgraph
+
     def _infer_root(self, root: Optional[int]) -> int:
         """Infer the root node from the graph structure or validate provided root.
 
@@ -2227,18 +2282,26 @@ class SkeletonLayer(GraphLayer):
         Self
         """
         self._reset_derived_properties()
-        if not as_positional:
-            new_root = np.flatnonzero(self.vertex_index == new_root)[0]
+        # ``_root``/``base_root`` and ``_apply_root_to_edges`` all work in vertex
+        # index space, so normalize a positional argument up front rather than
+        # converting to positional (which the rest of the class does not expect).
+        if as_positional:
+            new_root = int(self.vertex_index[new_root])
         self._root = new_root
-        self._dag_cache.root = self._root
-        self._apply_root_to_edges(new_root)
+        self._dag_cache.root = self.root_positional
+        self._dag_cache.parent_node_array = self._apply_root_to_edges(new_root)
+        # Rebuild the full base-property snapshot from the rerooted skeleton.
+        # This must include every key ``_set_base_properties`` normally writes --
+        # notably ``base_csgraph_binary`` (used by ``hops_to_root``) -- because a
+        # provided dict replaces ``_base_properties`` wholesale.
         self._set_base_properties(
             base_properties={
-                "base_root": new_root,
+                "base_root": self.root,
+                "base_root_location": self.root_location,
                 "base_vertex_index": self.vertex_index,
                 "base_parent_array": self.parent_node_array,
                 "base_csgraph": self.csgraph,
-                "base_root_location": self.root_location,
+                "base_csgraph_binary": self.csgraph_binary,
             }
         )
         return self

{ossify-0.2.0 → ossify-0.2.2}/src/ossify/translate.py

@@ -23,10 +23,10 @@ if TYPE_CHECKING:
     from caveclient import CAVEclientFull as CAVEclient
 
 
-# Synchronous bulk-skeleton download cap in the CAVE skeleton service
-# (caveclient.skeletonservice.MAX_BULK_SYNCHRONOUS_SKELETONS); larger lists are silently
-# truncated by the endpoint, so callers must chunk at this size.
-_BULK_SKELETON_CHUNK = 10
+# Per-call cap for cached bulk-skeleton downloads via ``client.skeleton.fetch_skeletons``
+# (caveclient.skeletonservice.MAX_BULK_CACHED_SKELETONS); longer lists are silently truncated
+# by the endpoint, so callers must chunk at this size.
+_BULK_SKELETON_CHUNK = 500
 
 
 class SWCCompartment(IntEnum):
@@ -563,23 +563,32 @@ def _get_bulk_skeletons(
     client: "CAVEclient",
     root_ids: list[int],
     skeleton_version: int,
-    generate_missing: bool = False,
+    method: Literal["gcs", "server"] = "gcs",
 ) -> dict[int, dict]:
-    """Download skeletons in bulk, chunked at the synchronous bulk cap.
-
-    Returns ``{int root_id: skeleton_dict}``. Roots whose skeleton is not yet available
-    (async/not-generated) are omitted — with ``generate_missing=False`` (the worker default,
-    assuming a prior ``generate_bulk_skeletons_async`` pre-pass) these simply don't appear.
+    """Download cached skeletons in bulk, chunked at the cached-bulk cap.
+
+    Uses ``client.skeleton.fetch_skeletons``, which retrieves only already-cached skeletons and
+    skips the per-root chunkedgraph validation of the older ``get_bulk_skeletons`` path. With
+    ``method="gcs"`` (the default) skeleton H5 files are downloaded directly from the storage
+    bucket via a short-lived downscoped token, bypassing the service for data transfer — this
+    avoids the request rate limits that throttle bulk loads through the server. ``method="server"``
+    routes the download through the skeleton service instead.
+
+    Skeletons are never generated inline (``generate_missing_skeletons=False`` always). Returns
+    ``{int root_id: skeleton_dict}``; roots whose skeleton is not yet cached (async/not-generated)
+    are omitted — assuming a prior ``generate_bulk_skeletons_async`` pre-pass, these simply don't
+    appear.
     """
     out: dict[int, dict] = {}
     for i in range(0, len(root_ids), _BULK_SKELETON_CHUNK):
         chunk = root_ids[i : i + _BULK_SKELETON_CHUNK]
         with suppress_output():
-            res = client.skeleton.get_bulk_skeletons(
+            res = client.skeleton.fetch_skeletons(
                 chunk,
                 skeleton_version=skeleton_version,
                 output_format="dict",
-                generate_missing_skeletons=generate_missing,
+                method=method,
+                generate_missing_skeletons=False,
             )
         for k, v in res.items():
             out[int(k)] = v
@@ -601,7 +610,7 @@ def load_cell_batch_from_client(
     omit_self_synapses: bool = True,
     skeleton_version: int = 4,
     skip_invalid: bool = False,
-    generate_missing_skeletons: bool = False,
+    skeleton_download_method: Literal["gcs", "server"] = "gcs",
     row_limit: int = 500_000,
 ) -> dict[int, Cell]:
     """Load many cells with the poolable fetches batched into a few queries.
@@ -611,6 +620,9 @@ def load_cell_batch_from_client(
     each cell is then assembled network-free — no skeleton is fetched twice, and the batch is
     validated with a single round trip. All roots share one ``timestamp``.
 
+    All parameters not listed below match :func:`load_cell_from_client` and are applied
+    identically to every cell in the batch.
+
     Parameters
     ----------
     root_ids: list[int]
@@ -622,11 +634,14 @@ def load_cell_batch_from_client(
     skip_invalid: bool
         If True, roots that are not valid at ``timestamp`` — or whose skeleton is not available
         — are dropped from the result instead of raising.
-    generate_missing_skeletons: bool
-        Passed to ``get_bulk_skeletons``. Default False assumes skeletons were already produced
-        by a ``generate_bulk_skeletons_async`` pre-pass; a worker then just downloads them (fast,
-        and degrades gracefully on a cache miss). Set True to block on server-side generation.
-    (all other parameters match :func:`load_cell_from_client`.)
+    skeleton_download_method: "gcs" or "server"
+        How ``fetch_skeletons`` retrieves cached skeletons. ``"gcs"`` (default) downloads H5 files
+        directly from the storage bucket via a downscoped token, bypassing the service for data
+        transfer and avoiding its request rate limits — preferred for bulk loads. ``"server"``
+        routes the download through the skeleton service instead.
+    row_limit: int
+        Passed to :func:`fetch_frames_batch`; guards against a silently-truncated pooled synapse
+        query at/above the server row limit (default 500,000). Set to 0 to disable.
 
     Returns
     -------
@@ -649,18 +664,20 @@ def load_cell_batch_from_client(
             + (" ..." if len(invalid_ids) > 5 else "")
         )
 
-    # 2. Skeletons: one bulk download (chunked at the sync cap) to obtain lvl2_ids, then
-    #    injected into assembly. Assumes a prior generate_bulk_skeletons_async pre-pass.
+    # 2. Skeletons: one cached bulk download (chunked at the cached-bulk cap) to obtain lvl2_ids,
+    #    then injected into assembly. Assumes a prior generate_bulk_skeletons_async pre-pass.
     sk_by_root = _get_bulk_skeletons(
-        client, valid_ids, skeleton_version, generate_missing=generate_missing_skeletons
+        client,
+        valid_ids,
+        skeleton_version,
+        method=skeleton_download_method,
     )
     no_skeleton = [r for r in valid_ids if r not in sk_by_root]
     if no_skeleton and not skip_invalid:
         raise ValueError(
-            f"{len(no_skeleton)} root id(s) have no available skeleton "
-            f"(run generate_bulk_skeletons_async first, or pass generate_missing_skeletons=True "
-            f"or skip_invalid=True): {no_skeleton[:5]}"
-            + (" ..." if len(no_skeleton) > 5 else "")
+            f"{len(no_skeleton)} root id(s) have no cached skeleton "
+            f"(run generate_bulk_skeletons_async first, or pass skip_invalid=True): "
+            f"{no_skeleton[:5]}" + (" ..." if len(no_skeleton) > 5 else "")
         )
     valid_ids = [r for r in valid_ids if r in sk_by_root]
     lvl2_ids_by_root = {r: sk_by_root[r]["lvl2_ids"] for r in valid_ids}