spatial-graph 0.0.1__tar.gz

spatial_graph-0.0.1/.cruft.json

@@ -0,0 +1,20 @@
+{
+  "template": "https://github.com/adjavon/pycookie/",
+  "commit": "d7bd6b8521627b130001b270383b72bfed608ab3",
+  "checkout": null,
+  "context": {
+    "cookiecutter": {
+      "full_name": "Jan Funke",
+      "email": "funkej@janelia.hhmi.org",
+      "github_username": "funkelab",
+      "project_name": "spatial_graph",
+      "project_slug": "spatial_graph",
+      "project_short_description": "A spatial graph datastructure for python.",
+      "_copy_without_render": [
+        ".github/workflows/*"
+      ],
+      "_template": "https://github.com/adjavon/pycookie/"
+    }
+  },
+  "directory": null
+}

spatial_graph-0.0.1/.github/workflows/ci.yaml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+    tags: [v*]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run pre-commit
+        run: pipx run pre-commit run --all-files
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          pip install ".[dev]"
+      - name: Test with pytest
+        run: |
+          pytest --color=yes -v tests
+
+  deploy:
+    name: Deploy
+    needs: test
+    if: success() && startsWith(github.ref, 'refs/tags/') && github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: 👷 Build
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: 🚢 Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+           password: ${{ secrets.PYPI_API_TOKEN }}
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: "./dist/*"

spatial_graph-0.0.1/.gitignore

@@ -0,0 +1,13 @@
+*.sw[pmno]
+*.pyc
+*.egg-info
+*.dat
+*.lock
+*.so
+*_wrapper.cpp
+*_wrapper.c
+.coverage
+build
+dist
+.vscode
+docs/_build/

spatial_graph-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+ci:
+  autoupdate_schedule: monthly
+  autofix_commit_msg: "style(pre-commit.ci): auto fixes [...]"
+  autoupdate_commit_msg: "ci(pre-commit.ci): autoupdate"
+
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.7.2
+    hooks:
+      - id: ruff
+        args: [--fix, --unsafe-fixes]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy

spatial_graph-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Funke lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spatial_graph-0.0.1/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: spatial-graph
+Version: 0.0.1
+Summary: A spatial graph datastructure for python.
+Project-URL: homepage, https://github.com/funkelab/spatial_graph
+Project-URL: repository, https://github.com/funkelab/spatial_graph
+Author-email: Jan Funke <funkej@janelia.hhmi.org>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: cheetah3
+Requires-Dist: numpy
+Requires-Dist: setuptools>=75.8.0
+Requires-Dist: witty>=v0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spatial_graph
+
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml)
+
+`spatial_graph` provides a data structure for directed and undirected graphs,
+where each node has an nD position (in time or space).
+
+Design Principles
+=================
+
+Goals
+-----
+
+* support for arbitrary number of dimensions
+* typed node identifiers and attributes
+    * any fixed-length type that is supported by `numpy`
+* efficient node/edge queries by
+    * ROI
+    * kNN (by points / lines)
+* numpy-like interface for efficient:
+    * graph population and manipulation
+    * query results
+    * attribute access
+* minimal memory footprint
+* minimal dependencies
+    * `cython` / `witty` / `cheetah3` for runtime compilation
+    * numpy for array interfaces
+* PYX API for graph algorithms in C/C++
+
+Non-Goals
+---------
+
+* graph algorithms
+* I/O
+* non-typed arguments
+* non-spatial graphs
+* out-of-memory support
+* networkx compatibility
+
+Python API
+==========
+
+Graph creation:
+
+```python
+graph = sg.SpatialGraph(
+    ndims=3,
+    node_dtype="uint64",
+    node_attr_dtypes={"position": "double[3]"},
+    edge_attr_dtypes={"score": "float32"},
+    position_attr="position",
+    directed=False,
+)
+```
+
+Adding nodes/edges:
+
+```python
+graph.add_nodes(
+    np.array([1, 2, 3, 4, 5], dtype="uint64"),
+    position=np.array(
+        [
+            [0.1, 0.1, 0.1],
+            [0.2, 0.2, 0.2],
+            [0.3, 0.3, 0.3],
+            [0.4, 0.4, 0.4],
+            [0.5, 0.5, 0.5],
+        ],
+        dtype="double",
+    ),
+)
+
+graph.add_edges(
+    np.array([[1, 2], [3, 4], [5, 1]], dtype="uint64"),
+    score=np.array([0.2, 0.3, 0.4], dtype="float32"),
+)
+```
+
+Query nodes/edges in ROI:
+
+```python
+# nodes/edges will be numpy arrays of dtype uint64 and shape (n,)/(n, 2)
+nodes = graph.query_nodes_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+edges = graph.query_edges_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+```
+
+Query nodes/edges by position:
+
+```python
+nodes = graph.query_nearest_nodes(np.array([0.3, 0.3, 0.3]), k=3)
+edges = graph.query_nearest_edges(np.array([0.3, 0.3, 0.3]), k=3)
+```
+
+Access node/edge attributes:
+
+```python
+node_positions = graph.node_attrs[nodes].position
+edge_scores = graph.edge_attrs[edges].score
+```
+
+Delete nodes/edges:
+
+```python
+graph.remove_nodes(nodes[:1000])
+```
+
+Implementation Details
+======================
+
+A `SpatialGraph` consists of three data structures:
+* The `Graph` itself, holding nodes, edges, and their attributes ([graphlite](https://github.com/haasdo95/graphlite)).
+* Two R-trees for spatial node and edge queries (based on [rtree.c](https://github.com/tidwall/rtree.c)).

spatial_graph-0.0.1/README.md

@@ -0,0 +1,112 @@
+# spatial_graph
+
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yaml)
+
+`spatial_graph` provides a data structure for directed and undirected graphs,
+where each node has an nD position (in time or space).
+
+Design Principles
+=================
+
+Goals
+-----
+
+* support for arbitrary number of dimensions
+* typed node identifiers and attributes
+    * any fixed-length type that is supported by `numpy`
+* efficient node/edge queries by
+    * ROI
+    * kNN (by points / lines)
+* numpy-like interface for efficient:
+    * graph population and manipulation
+    * query results
+    * attribute access
+* minimal memory footprint
+* minimal dependencies
+    * `cython` / `witty` / `cheetah3` for runtime compilation
+    * numpy for array interfaces
+* PYX API for graph algorithms in C/C++
+
+Non-Goals
+---------
+
+* graph algorithms
+* I/O
+* non-typed arguments
+* non-spatial graphs
+* out-of-memory support
+* networkx compatibility
+
+Python API
+==========
+
+Graph creation:
+
+```python
+graph = sg.SpatialGraph(
+    ndims=3,
+    node_dtype="uint64",
+    node_attr_dtypes={"position": "double[3]"},
+    edge_attr_dtypes={"score": "float32"},
+    position_attr="position",
+    directed=False,
+)
+```
+
+Adding nodes/edges:
+
+```python
+graph.add_nodes(
+    np.array([1, 2, 3, 4, 5], dtype="uint64"),
+    position=np.array(
+        [
+            [0.1, 0.1, 0.1],
+            [0.2, 0.2, 0.2],
+            [0.3, 0.3, 0.3],
+            [0.4, 0.4, 0.4],
+            [0.5, 0.5, 0.5],
+        ],
+        dtype="double",
+    ),
+)
+
+graph.add_edges(
+    np.array([[1, 2], [3, 4], [5, 1]], dtype="uint64"),
+    score=np.array([0.2, 0.3, 0.4], dtype="float32"),
+)
+```
+
+Query nodes/edges in ROI:
+
+```python
+# nodes/edges will be numpy arrays of dtype uint64 and shape (n,)/(n, 2)
+nodes = graph.query_nodes_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+edges = graph.query_edges_in_roi(np.array([[0.0, 0.0, 0.0], [0.25, 0.25, 0.25]]))
+```
+
+Query nodes/edges by position:
+
+```python
+nodes = graph.query_nearest_nodes(np.array([0.3, 0.3, 0.3]), k=3)
+edges = graph.query_nearest_edges(np.array([0.3, 0.3, 0.3]), k=3)
+```
+
+Access node/edge attributes:
+
+```python
+node_positions = graph.node_attrs[nodes].position
+edge_scores = graph.edge_attrs[edges].score
+```
+
+Delete nodes/edges:
+
+```python
+graph.remove_nodes(nodes[:1000])
+```
+
+Implementation Details
+======================
+
+A `SpatialGraph` consists of three data structures:
+* The `Graph` itself, holding nodes, edges, and their attributes ([graphlite](https://github.com/haasdo95/graphlite)).
+* Two R-trees for spatial node and edge queries (based on [rtree.c](https://github.com/tidwall/rtree.c)).

spatial_graph-0.0.1/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "spatial-graph"
+version = "0.0.1"
+description = "A spatial graph datastructure for python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+    { email = "funkej@janelia.hhmi.org", name = "Jan Funke" },
+]
+dependencies = [
+  "witty>=v0.2.0",
+  "cheetah3",
+  "numpy",
+  "setuptools>=75.8.0",
+]
+
+[project.urls]
+homepage = "https://github.com/funkelab/spatial_graph"
+repository = "https://github.com/funkelab/spatial_graph"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.4",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

spatial_graph-0.0.1/spatial_graph/__init__.py

@@ -0,0 +1,15 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("spatial_graph")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+
+from .rtree import PointRTree
+from .rtree import LineRTree
+from .graph import Graph
+from .spatial_graph import SpatialGraph
+
+
+__all__ = ["PointRTree", "LineRTree", "Graph", "SpatialGraph"]

spatial_graph-0.0.1/spatial_graph/dtypes.py

@@ -0,0 +1,130 @@
+import numpy as np
+
+
+class DType:
+    def __init__(self, dtype_str):
+        self.as_string = dtype_str
+        self.is_array = self.__is_array(dtype_str)
+
+        if self.is_array:
+            self.base, self.size = self.__parse_array_dtype(dtype_str)
+            self.shape = (self.size,)
+        else:
+            self.base = dtype_str
+            self.size = None
+            self.shape = ()
+
+    def __is_array(self, dtype):
+        if "[" in dtype:
+            if "]" not in dtype:
+                raise RuntimeError(f"invalid array(?) dtype {dtype}")
+            return True
+        return False
+
+    def __parse_array_dtype(self, dtype):
+        dtype, size = dtype.split("[")
+        size = int(size.split("]")[0])
+
+        return dtype, size
+
+    @property
+    def base_c_type(self):
+        """Convert the base of this DType into the equivalent C/C++ type."""
+
+        if self.base == "float32" or self.base == "float":
+            return "float"
+        elif self.base == "float64" or self.base == "double":
+            return "double"
+        else:
+            # this might not work for all of them, this is just a fallback
+            return np.dtype(self.base).name + "_t"
+
+    def to_c_decl(self, name):
+        """Convert this dtype to the equivalent C/C++ declaration with the
+        given name:
+
+            "base_c_type name"        if not an array
+            "base_c_type name[size]"  if an array type
+        """
+        # is this an array type?
+        if self.is_array:
+            suffix = f"[{self.size}]"
+        else:
+            suffix = ""
+
+        return self.base_c_type + " " + name + suffix
+
+    def to_pyxtype(self, use_memory_view=False, add_dim=False):
+        """Convert this dtype to the equivalent PYX type.
+
+            "base_c_type"
+            "base_c_type[size]"     if an array type
+            "base_c_type[::1]"      if an array type and use_memory_view
+            "base_c_type[::1]"      if not an array type and add_dim
+            "base_c_type[:, ::1]"   if an array type and add_dim
+
+        Args:
+
+            use_memory_view:
+
+                If set, will produce "dtype[::1]" instead of "dtype[dim]" for
+                array types.
+
+            add_dim:
+
+                Append a dim to the type, e.g., "int32_t[::1]" instead of
+                "int32_t" for dtype "int32". If this DType is already an array,
+                will create a 2D array, e.g., "int32_t[:, ::1]".
+        """
+
+        # is this an array type?
+        if self.is_array:
+            if add_dim:
+                suffix = "[:, ::1]"
+            else:
+                if use_memory_view:
+                    suffix = "[::1]"
+                else:
+                    suffix = f"[{self.size}]"
+        else:
+            suffix = "[::1]" if add_dim else ""
+
+        return self.base_c_type + suffix
+
+    def to_rvalue(self, name, array_index=None):
+        """Convert this dtype into an r-value to be used in PYX files for
+        assignments.
+
+            "name"                  default
+            "name[array_index]"     if array_index is given
+            "{name[0], ..., name[size-1]}"
+                                    if an array type
+            "{name[array_index, 0], ..., name[array_index, size-1]}"
+                                    if an array type and array_index is given
+        """
+
+        if self.is_array:
+            if array_index:
+                return (
+                    "{"
+                    + ", ".join(
+                        [name + f"[{array_index}, {i}]" for i in range(self.size)]
+                    )
+                    + "}"
+                )
+            else:
+                return (
+                    "{" + ", ".join([name + f"[{i}]" for i in range(self.size)]) + "}"
+                )
+        else:
+            if array_index:
+                return f"{name}[{array_index}]"
+            else:
+                return name
+
+
+def dtypes_to_struct(struct_name, dtypes):
+    pyx_code = f"cdef struct {struct_name}:\n"
+    for name, dtype in dtypes.items():
+        pyx_code += f"    {dtype.to_pyxtype()} {name}\n"
+    return pyx_code

spatial_graph-0.0.1/spatial_graph/graph/__init__.py

@@ -0,0 +1,3 @@
+from .graph import Graph
+
+__all__ = ["Graph"]