ossify 0.2.7__tar.gz → 0.2.8__tar.gz

{ossify-0.2.7 → ossify-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ossify
-Version: 0.2.7
+Version: 0.2.8
 Summary: Mesh and skeleton analysis
 Author-email: Casey Schneider-Mizell <caseysm@gmail.com>
 License-File: LICENSE

{ossify-0.2.7 → ossify-0.2.8}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 allow-direct-references = true
 [project]
 name = "ossify"
-version = "0.2.7"
+version = "0.2.8"
 description = "Mesh and skeleton analysis"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -95,7 +95,7 @@ default-groups = ["dev", "docs", "lint", "profile", "viz"]
 
 
 [tool.bumpversion]
-current_version = "0.2.7"
+current_version = "0.2.8"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
 serialize = ["{major}.{minor}.{patch}"]
 regex = false

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/__init__.py

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

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/base.py

@@ -398,6 +398,7 @@ class Cell:
         features: Optional[Union[dict, pd.DataFrame]] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        faces_as_positional: Optional[bool] = None,
         linkage: Optional[Link] = None,
         spatial_columns: Optional[list] = None,
     ) -> Self:
@@ -408,11 +409,25 @@ class Cell:
         vertices : Union[np.ndarray, pd.DataFrame, MeshLayer]
             The vertices of the mesh, or a MeshLayer object.
         faces : Union[np.ndarray, pd.DataFrame]
-            The faces of the mesh. If faces are provided as a dataframe, faces should be in dataframe indices.
+            The triangular faces of the mesh. **If ``vertex_index`` is given
+            these are positional indices into ``vertices``** and are remapped
+            onto the vertex index for you; otherwise they are vertex indices
+            already -- the index of ``vertices`` when it is a DataFrame, or
+            positional when it is a plain array. Mesh formats such as OBJ and
+            PLY give positional faces, so ``vertex_index`` is usually what you
+            want when labelling mesh vertices with ids.
         features : Optional[Union[dict, pd.DataFrame]]
             Additional features for the mesh. If passed as dictionary, the key is the feature name and the values are an array of feature values.
         vertex_index : Optional[Union[str, np.ndarray]]
-            The column to use as a vertex index for the mesh, if vertices are a dataframe.
+            Vertex indices to label the mesh's vertices by: either the name of
+            a column in ``vertices``, or an array with one value per vertex.
+            Supplying this changes how ``faces`` are read -- see above.
+        faces_as_positional : Optional[bool]
+            Whether ``faces`` are positional indices into ``vertices``. The
+            default, None, infers it as described above: positional exactly
+            when ``vertex_index`` is supplied. Pass it explicitly when the two
+            spaces overlap -- a ``vertex_index`` whose values are also valid
+            positions cannot be told apart any other way.
         linkage : Optional[Link]
             The linkage information for the mesh.
         spatial_columns: Optional[list] = None
@@ -435,6 +450,7 @@ class Cell:
                     name=self.MESH_LN,
                     vertices=vertices,
                     faces=faces,
+                    faces_as_positional=faces_as_positional,
                     features=features,
                     morphsync=self._morphsync,
                     spatial_columns=spatial_columns,
@@ -453,6 +469,7 @@ class Cell:
         root: Optional[int] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        edges_as_positional: Optional[bool] = None,
         linkage: Optional[Link] = None,
         spatial_columns: Optional[list] = None,
         inherited_properties: Optional[dict] = None,
@@ -465,13 +482,28 @@ class Cell:
         vertices : Union[np.ndarray, pd.DataFrame, SkeletonLayer]
             The vertices of the skeleton, or a SkeletonLayer object.
         edges : Union[np.ndarray, pd.DataFrame]
-            The edges of the skeleton.
+            The edges of the skeleton, as pairs of vertices. **If ``vertex_index``
+            is given these are positional indices into ``vertices``** and are
+            remapped onto the vertex index for you; otherwise they are vertex
+            indices already -- the index of ``vertices`` when it is a DataFrame,
+            or positional when it is a plain array.
         features : Optional[Union[dict, pd.DataFrame]]
             The features for the skeleton.
         root : Optional[int]
-            The root vertex for the skeleton, required of the edges are not already consistent with a single root.
+            The root of the skeleton, as a **vertex index** -- note this is the
+            opposite convention to ``edges``, which are positional when
+            ``vertex_index`` is given. Required if the edges are not already
+            consistent with a single root.
         vertex_index : Optional[Union[str, np.ndarray]]
-            The vertex index for the skeleton.
+            Vertex indices to label the skeleton's vertices by: either the name of
+            a column in ``vertices``, or an array with one value per vertex.
+            Supplying this changes how ``edges`` are read -- see above.
+        edges_as_positional : Optional[bool]
+            Whether ``edges`` are positional indices into ``vertices``. The
+            default, None, infers it as described above: positional exactly
+            when ``vertex_index`` is supplied. Pass it explicitly when the two
+            spaces overlap -- a ``vertex_index`` whose values are also valid
+            positions cannot be told apart any other way.
         linkage : Optional[Link]
             The linkage information for the skeleton. Typically, you will define the source vertices for the skeleton if using a graph-to-skeleton mapping.
         spatial_columns: Optional[list] = None
@@ -495,6 +527,7 @@ class Cell:
                     name=self.SKEL_LN,
                     vertices=vertices,
                     edges=edges,
+                    edges_as_positional=edges_as_positional,
                     features=features,
                     root=root,
                     morphsync=self._morphsync,
@@ -514,6 +547,7 @@ class Cell:
         features: Optional[Union[dict, pd.DataFrame]] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        edges_as_positional: Optional[bool] = None,
         spatial_columns: Optional[list] = None,
         linkage: Optional[Link] = None,
     ) -> Self:
@@ -526,11 +560,23 @@ class Cell:
         vertices : Union[np.ndarray, pd.DataFrame, SkeletonLayer]
             The vertices of the graph.
         edges : Union[np.ndarray, pd.DataFrame]
-            The edges of the graph.
+            The edges of the graph, as pairs of vertices. **If ``vertex_index``
+            is given these are positional indices into ``vertices``** and are
+            remapped onto the vertex index for you; otherwise they are vertex
+            indices already -- the index of ``vertices`` when it is a DataFrame,
+            or positional when it is a plain array.
         features : Optional[Union[dict, pd.DataFrame]]
             The features for the graph.
         vertex_index : Optional[Union[str, np.ndarray]]
-            The vertex index for the graph.
+            Vertex indices to label the graph's vertices by: either the name of
+            a column in ``vertices``, or an array with one value per vertex.
+            Supplying this changes how ``edges`` are read -- see above.
+        edges_as_positional : Optional[bool]
+            Whether ``edges`` are positional indices into ``vertices``. The
+            default, None, infers it as described above: positional exactly
+            when ``vertex_index`` is supplied. Pass it explicitly when the two
+            spaces overlap -- a ``vertex_index`` whose values are also valid
+            positions cannot be told apart any other way.
         spatial_columns: Optional[list] = None
             The spatial columns for the graph, if vertices are a dataframe.
 
@@ -552,6 +598,7 @@ class Cell:
                     name=self.GRAPH_LN,
                     vertices=vertices,
                     edges=edges,
+                    edges_as_positional=edges_as_positional,
                     features=features,
                     morphsync=self._morphsync,
                     spatial_columns=spatial_columns,

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/data_layers.py

@@ -89,26 +89,6 @@ class EdgeMixin(ABC):
             return np.empty((0, 2), dtype=int)
         return self.layer.edges_positional
 
-    def _map_edges_to_index(
-        self, edges: np.ndarray, vertex_indices: np.ndarray
-    ) -> np.ndarray:
-        """Remap positional edges to vertex indices.
-
-        Parameters
-        ----------
-        edges : np.ndarray
-            Edge array with positional indices.
-        vertex_indices : np.ndarray
-            Array of vertex indices to map to.
-
-        Returns
-        -------
-        np.ndarray
-            Edge array with vertex indices instead of positional indices.
-        """
-        index_map = {ii: v for ii, v in enumerate(vertex_indices)}
-        return fastremap.remap(edges, index_map)
-
     @property
     def csgraph(self) -> sparse.csr_matrix:
         """
@@ -318,26 +298,6 @@ class FaceMixin(ABC):
         self._csgraph = None
         self._trimesh = None
 
-    def _map_faces_to_index(
-        self, faces: np.ndarray, vertex_indices: np.ndarray
-    ) -> np.ndarray:
-        """Remap positional faces to vertex indices.
-
-        Parameters
-        ----------
-        faces : np.ndarray
-            Face array with positional indices.
-        vertex_indices : np.ndarray
-            Array of vertex indices to map to.
-
-        Returns
-        -------
-        np.ndarray
-            Face array with vertex indices instead of positional indices.
-        """
-        index_map = {ii: v for ii, v in enumerate(vertex_indices)}
-        return fastremap.remap(faces, index_map)
-
     def surface_area(
         self,
         vertices: Optional[np.ndarray] = None,
@@ -444,6 +404,75 @@ class PointMixin(ABC):
                 )
             self._process_linkage(linkage)
 
+    def _index_connectivity(
+        self,
+        connectivity: np.ndarray,
+        vertices: pd.DataFrame,
+        as_positional: Optional[bool],
+        vertex_index: Optional[Union[str, np.ndarray]],
+        what: str = "edges",
+    ) -> np.ndarray:
+        """Put edges or faces into vertex-index space at construction.
+
+        Every layer type takes connectivity that may be written either as
+        positional indices into ``vertices`` or as vertex indices, so the rule
+        lives here once rather than in each constructor.
+
+        ``as_positional=None`` keeps the historical behaviour -- positional
+        exactly when ``vertex_index`` was supplied -- so callers that never
+        pass the flag are unaffected. An explicit ``True``/``False`` overrides
+        it, and is the only way to disambiguate a vertex index whose values
+        are also valid positions.
+
+        Parameters
+        ----------
+        connectivity : np.ndarray
+            Edge pairs or face triples.
+        vertices : pd.DataFrame
+            The processed vertex table; its index supplies the vertex indices.
+        as_positional : Optional[bool]
+            Whether ``connectivity`` holds positional indices. None infers it.
+        vertex_index : Optional[Union[str, np.ndarray]]
+            The vertex index argument, used only for the inference above.
+        what : str
+            Name used in error messages -- "edges" or "faces".
+
+        Returns
+        -------
+        np.ndarray
+            ``connectivity`` in vertex-index space.
+        """
+        positional = (
+            vertex_index is not None if as_positional is None else bool(as_positional)
+        )
+        if not positional:
+            return connectivity
+
+        arr = np.asarray(connectivity)
+        if arr.size:
+            # Without this check, values that are actually vertex indices
+            # surface as KeyError from inside fastremap, which says nothing
+            # about the convention that was violated.
+            low, high = int(arr.min()), int(arr.max())
+            if low < 0 or high >= len(vertices):
+                if as_positional is None:
+                    hint = (
+                        f"`{what}` are read as positional indices because "
+                        f"`vertex_index` was given; pass "
+                        f"{what}_as_positional=False if they are vertex "
+                        "indices already."
+                    )
+                else:
+                    hint = (
+                        f"`{what}_as_positional=True` was given, so `{what}` "
+                        "must be positional indices."
+                    )
+                raise ValueError(
+                    f"{what} contain values outside the valid positional range "
+                    f"0..{len(vertices) - 1} (found {low}..{high}). {hint}"
+                )
+        return fastremap.remap(arr, dict(enumerate(vertices.index)))
+
     def _vertices_to_positional(
         self,
         vertices: Optional[np.ndarray],
@@ -798,8 +827,17 @@ class PointMixin(ABC):
             right_index=True,
             how="left",
         )
+        # "majority" is ossify's own reducer, not something pandas understands,
+        # so it has to be swapped for the callable wherever it appears -- including
+        # inside a per-feature dict, which is the documented way to give different
+        # features different aggregations.
         if agg == "majority":
             agg = utils.majority_agg()
+        elif isinstance(agg, dict):
+            agg = {
+                key: utils.majority_agg() if value == "majority" else value
+                for key, value in agg.items()
+            }
         # Group by target layer and aggregate, then reindex to ensure all target vertices are included
         grouped_result = mapping_merged.groupby(layer).agg(agg)
         target_layer_index = self._morphsync.layers[layer].nodes.index
@@ -1498,6 +1536,7 @@ class GraphLayer(PointMixin, EdgeMixin):
         spatial_columns: Optional[list] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        edges_as_positional: Optional[bool] = None,
         features: Optional[Union[dict, pd.DataFrame]] = None,
         morphsync: MorphSync = None,
         linkage: Optional[Link] = None,
@@ -1515,8 +1554,9 @@ class GraphLayer(PointMixin, EdgeMixin):
         self._cell = None
 
         if not existing:
-            if vertex_index:
-                edges = self._map_edges_to_index(edges, vertices.index)
+            edges = self._index_connectivity(
+                edges, vertices, edges_as_positional, vertex_index, "edges"
+            )
             self._morphsync.add_graph(
                 graph=(vertices, edges),
                 name=self.layer_name,
@@ -1869,6 +1909,7 @@ class SkeletonLayer(GraphLayer):
         root: Optional[int] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        edges_as_positional: Optional[bool] = None,
         features: Optional[Union[dict, pd.DataFrame]] = None,
         morphsync: MorphSync = None,
         linkage: Optional[dict] = None,
@@ -1885,8 +1926,9 @@ class SkeletonLayer(GraphLayer):
 
         if inherited_properties is None:
             # Add as a morphsync layer
-            if vertex_index:
-                edges = self._map_edges_to_index(edges, vertices.index)
+            edges = self._index_connectivity(
+                edges, vertices, edges_as_positional, vertex_index, "edges"
+            )
             self._morphsync.add_graph(
                 graph=(vertices, edges),
                 name=self.layer_name,
@@ -2247,24 +2289,38 @@ class SkeletonLayer(GraphLayer):
         Parameters
         ----------
         root : Optional[int]
-            Proposed root node index. If None, attempts to infer from graph structure.
+            Proposed root, as a **vertex index** -- the same space as
+            ``vertex_index``, not a positional index. Note this differs from
+            ``edges``, which are positional when ``vertex_index`` is supplied.
+            If None, attempts to infer from graph structure.
 
         Returns
         -------
         int
-            The root node index.
+            The root vertex index.
 
         Raises
         ------
         ValueError
-            If no root specified and multiple potential roots found.
+            If the given root is not one of this layer's vertices, or if no
+            root was specified and multiple potential roots were found.
         """
         if root is not None:
-            return int(root)
+            root = int(root)
+            # Numpy membership rather than building a Python set: a layer can
+            # have millions of vertices and this runs on every construction.
+            if not np.any(self.vertex_index == root):
+                raise ValueError(
+                    f"root {root} is not a vertex of this layer. `root` is a "
+                    "vertex index, not a positional index -- note that `edges` "
+                    "use the opposite convention when `vertex_index` is given."
+                )
+            return root
         else:
             potential_roots = np.flatnonzero(self.csgraph_binary.sum(axis=1) == 0)
             if len(potential_roots) == 1:
-                return int(potential_roots[0])
+                # ``potential_roots`` is positional; the root is a vertex index.
+                return int(self.vertex_index[potential_roots[0]])
             else:
                 raise ValueError(
                     "No root specified and edges are not consistent with a single root. Please set a valid root."
@@ -2336,6 +2392,16 @@ class SkeletonLayer(GraphLayer):
                 edges_positional_new[:, ii]
             ]
 
+        # The edges just changed direction, but ``csgraph``/``csgraph_binary``
+        # were built (by the connected_components call above) from the *old*
+        # orientation. Everything read off the directed graph -- branch points,
+        # end points, segments, cover paths -- would otherwise be computed from
+        # a stale graph that disagrees with ``edges_positional``. Drop only the
+        # edge-derived caches: the DAG cache holds root/parent state that the
+        # callers set around this method.
+        self._csgraph = None
+        self._csgraph_binary = None
+
     def reroot(self, new_root: int, as_positional=False) -> Self:
         """Reroot to a new index. Important: that this will reset any inherited properties from an unmasked skeleton!
 
@@ -2641,7 +2707,7 @@ class SkeletonLayer(GraphLayer):
             A list of cover paths, each path is a list of vertex indices, ordered as the typical `cover_paths` method.
         """
         sources, as_positional = self._vertices_to_positional(sources, as_positional)
-        cps = gf.compute_cover_paths(
+        cps = gf.build_cover_paths(
             sources,
             self.parent_node_array,
             self.distance_to_root(as_positional=True),
@@ -3479,6 +3545,7 @@ class MeshLayer(FaceMixin, PointMixin):
         spatial_columns: Optional[list] = None,
         *,
         vertex_index: Optional[Union[str, np.ndarray]] = None,
+        faces_as_positional: Optional[bool] = None,
         features: Optional[Union[dict, pd.DataFrame]] = None,
         morphsync: MorphSync = None,
         linkage: Optional[Link] = None,
@@ -3496,8 +3563,9 @@ class MeshLayer(FaceMixin, PointMixin):
         self._cell = None
 
         if not existing:
-            if vertex_index:
-                faces = self._map_faces_to_index(faces, vertices.index)
+            faces = self._index_connectivity(
+                faces, vertices, faces_as_positional, vertex_index, "faces"
+            )
             self._morphsync.add_mesh(
                 mesh=(vertices, faces),
                 name=self.layer_name,

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/plot.py

@@ -981,7 +981,31 @@ def plot_points(
             # Single color string
             scatter_kws["color"] = colors
         else:
-            scatter_kws["c"] = colors
+            colors_arr = np.asarray(colors)
+            single_rgba = (
+                colors_arr.ndim == 1
+                and colors_arr.shape[0] in (3, 4)
+                and np.issubdtype(colors_arr.dtype, np.number)
+                and colors_arr.shape[0] != len(points_proj)
+            )
+            if single_rgba:
+                # One bare RGB/RGBA tuple means "this exact color", but as `c`
+                # it is ambiguous with one scalar value per point, and
+                # matplotlib warns. A 2-D single row is its documented way to
+                # say the former. Reached via root_marker, whose color is read
+                # off the root vertex as a single RGBA.
+                colors_arr = colors_arr.reshape(1, -1)
+            if (
+                colors_arr.ndim == 2
+                and colors_arr.shape[1] in (3, 4)
+                and np.issubdtype(colors_arr.dtype, np.number)
+            ):
+                # Explicit RGB/RGBA values are not colormapped, so a cmap set
+                # from a string palette above would be silently ignored --
+                # matplotlib says so out loud. Drop it and its norm.
+                for key in ("cmap", "vmin", "vmax"):
+                    scatter_kws.pop(key, None)
+            scatter_kws["c"] = colors_arr
 
     ax.scatter(
         x=points_proj[:, 0],

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/translate.py

@@ -1,7 +1,6 @@
 from enum import IntEnum
 from typing import TYPE_CHECKING, Literal, Optional, Tuple, Union
 
-import fastremap
 import numpy as np
 import pandas as pd
 
@@ -310,13 +309,10 @@ def load_cell_from_client(
         l2_df = l2_df.reset_index()
 
     if restore_graph:
-        l2_graph = client.chunkedgraph.level2_chunk_graph(root_id)
-        l2_map = {v: k for k, v in l2_df["l2_id"].to_dict().items()}
-
-        edges = fastremap.remap(
-            l2_graph,
-            l2_map,
-        )
+        # The chunkedgraph gives edges as l2_id pairs, which is what the graph
+        # is indexed by, so hand them over as-is rather than round-tripping
+        # them through positional indices and straight back again.
+        edges = client.chunkedgraph.level2_chunk_graph(root_id)
     else:
         edges = []
 
@@ -335,6 +331,7 @@ def load_cell_from_client(
             spatial_columns=l2_spatial_columns,
             edges=edges,
             vertex_index="l2_id",
+            edges_as_positional=False,
         )
         .add_skeleton(
             vertices=np.array(sk["vertices"]),

{ossify-0.2.7 → ossify-0.2.8}/src/ossify/utils.py

@@ -79,7 +79,10 @@ def process_vertices(
             )
         spatial_columns = vertices.columns
     else:
-        if vertex_index:
+        # Only a string names a column to hold out of the implicit features; an
+        # array-like vertex_index supplies the ids directly. Plain truthiness
+        # raises on an array of more than one element.
+        if isinstance(vertex_index, str):
             implicit_feature_columns = list(
                 vertices.columns[
                     ~vertices.columns.isin(spatial_columns + [vertex_index])