spatial-graph 0.0.1__tar.gz → 0.0.3__tar.gz

spatial_graph-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+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.11", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+      - name: Test with coverage
+        run: uv run pytest -v --cov=spatial_graph --cov-report=xml
+      - uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  benchmarks:
+    runs-on: ubuntu-latest
+    env:
+      UV_NO_SYNC: "1"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: install
+        run: uv sync --no-dev --group test-codspeed
+
+      - name: Run benchmarks
+        uses: CodSpeedHQ/action@v3
+        with:
+          run: uv run pytest -W ignore --codspeed -v --color=yes
+
+  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
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "**/pyproject.toml"
+
+      - name: 👷 Build
+        run: uv 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/*"
+
+  docker-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build and test Docker image
+        run: |
+          docker build -t spatial_graph .
+          docker run --rm spatial_graph

spatial_graph-0.0.3/.github/workflows/docs.yaml

@@ -0,0 +1,29 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    name: Deploy Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+      - uses: astral-sh/setup-uv@v6
+      - name: Deploy documentation
+        run: uv run --group docs mkdocs gh-deploy --strict --force

{spatial_graph-0.0.1 → spatial_graph-0.0.3}/.gitignore

@@ -11,3 +11,8 @@ build
 dist
 .vscode
 docs/_build/
+coverage.xml
+site
+
+# remove me to enforce synchrony across development environments
+uv.lock

{spatial_graph-0.0.1 → spatial_graph-0.0.3}/.pre-commit-config.yaml

@@ -15,13 +15,13 @@ repos:
       - id: check-added-large-files
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.2
+    rev: v0.12.2
     hooks:
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --unsafe-fixes]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.13.0
+    rev: v1.16.1
     hooks:
       - id: mypy

spatial_graph-0.0.3/Dockerfile

@@ -0,0 +1,38 @@
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    MAMBA_ROOT_PREFIX=/opt/conda \
+    PATH=/opt/conda/bin:$PATH
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+      git curl tar bzip2 ca-certificates && \
+    rm -rf /var/lib/apt/lists/*
+
+# auto-detect arch and grab the matching micromamba binary
+RUN set -eux; \
+    arch="$(uname -m)"; \
+    case "$arch" in \
+      x86_64)    url_arch=linux-64 ;; \
+      aarch64|arm64) url_arch=linux-aarch64 ;; \
+      ppc64le)   url_arch=linux-ppc64le ;; \
+      *)         echo "Unsupported arch: $arch"; exit 1 ;; \
+    esac; \
+    curl -Ls "https://micro.mamba.pm/api/micromamba/$url_arch/latest" \
+      | tar -xvj -C /usr/local/bin bin/micromamba; \
+    chmod +x /usr/local/bin/bin/micromamba; \
+    mv /usr/local/bin/bin/micromamba /usr/local/bin/micromamba; \
+    rmdir /usr/local/bin/bin
+
+
+WORKDIR /app
+COPY . /app
+
+RUN micromamba create -y -n test-env -c conda-forge python=3.12 pip compilers
+RUN micromamba run -n test-env pip install -e . --group test
+
+SHELL ["micromamba", "run", "-n", "test-env", "/bin/bash", "-o", "pipefail", "-c"]
+
+
+# when you docker run, this will invoke pytest from inside test-env
+CMD ["micromamba", "run", "-n", "test-env", "pytest", "-q", "-x"]

spatial_graph-0.0.3/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: spatial-graph
+Version: 0.0.3
+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>, Talley Lambert <talley.lambert@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: ct3>=3.3.3
+Requires-Dist: numpy
+Requires-Dist: setuptools>=75.8.0
+Requires-Dist: witty>=v0.2.1
+Description-Content-Type: text/markdown
+
+# spatial-graph
+
+[![License](https://img.shields.io/pypi/l/spatial-graph.svg?color=green)](https://github.com/funkelab/spatial_graph/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/spatial-graph.svg?color=green)](https://pypi.org/project/spatial-graph)
+[![Python Version](https://img.shields.io/pypi/pyversions/spatial-graph.svg?color=green)](https://python.org)
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/funkelab/spatial_graph/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/spatial_graph)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/funkelab/spatial_graph)
+
+`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",
+)
+```
+
+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)). We modified the original code
+  to also include a fast kNN search.
+
+## Cross-Platform Support
+
+`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
+compiler. If you already have one, great! You can use the PyPI package.
+
+If you (or your users) don't have a compiler installed, you either need to
+
+1. Install a compiler. This might be weird for non-technical users.
+2. Install `spatial_graph` from `conda-forge`, where we include a compiler
+   (`clang`) in its dependencies.
+
+### Why is this so complicated?
+
+There is no cross-platform C/C++ compiler that we can install using `pip`.
+[`numba`](https://github.com/numba/numba) is maybe the closest to having solved
+that problem: `numba` does compile during runtime even if you don't have a
+compiler locally installed. This works because `numba` is generating LLVM IR,
+an intermediate representation language that LLVM can compile into machine
+code. `numba` depends on [`llvmlite`](https://github.com/numba/llvmlite), which
+provides a subset of the LLVM API, statically linked into the binaries in that
+package. This is just enough to compile the `numba` generated LLVM IR into
+machine code. We can't use this strategy, because we compile general C/C++
+code. Converting that into LLVM IR is exactly what we need a compiler for.
+
+## For Developers
+
+To create a new release, tag the current commit with a
+version number and push it to the `upstream` remote:
+
+```bash
+git tag -a "vX.Y.Z" -m "vX.Y.Z"
+git push upstream --follow-tags
+```
+
+This will trigger the CI workflow, which will build the package and upload it to PyPI.
+
+### Testing in a conda environment
+
+To simulate a naive user environment, with *no* assumptions made about the
+availability of a C/C++ compiler, you can run the included Dockerfile
+(where the key part of the conda env is the `compilers` package):
+
+```bash
+docker build -t spatial_graph .
+docker run --rm spatial_graph
+```

spatial_graph-0.0.3/README.md

@@ -0,0 +1,162 @@
+# spatial-graph
+
+[![License](https://img.shields.io/pypi/l/spatial-graph.svg?color=green)](https://github.com/funkelab/spatial_graph/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/spatial-graph.svg?color=green)](https://pypi.org/project/spatial-graph)
+[![Python Version](https://img.shields.io/pypi/pyversions/spatial-graph.svg?color=green)](https://python.org)
+[![CI](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml/badge.svg)](https://github.com/funkelab/spatial_graph/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/funkelab/spatial_graph/branch/main/graph/badge.svg)](https://codecov.io/gh/funkelab/spatial_graph)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/funkelab/spatial_graph)
+
+`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",
+)
+```
+
+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)). We modified the original code
+  to also include a fast kNN search.
+
+## Cross-Platform Support
+
+`spatial_graph` compiles C/C++ code at runtime, and as such needs access to a
+compiler. If you already have one, great! You can use the PyPI package.
+
+If you (or your users) don't have a compiler installed, you either need to
+
+1. Install a compiler. This might be weird for non-technical users.
+2. Install `spatial_graph` from `conda-forge`, where we include a compiler
+   (`clang`) in its dependencies.
+
+### Why is this so complicated?
+
+There is no cross-platform C/C++ compiler that we can install using `pip`.
+[`numba`](https://github.com/numba/numba) is maybe the closest to having solved
+that problem: `numba` does compile during runtime even if you don't have a
+compiler locally installed. This works because `numba` is generating LLVM IR,
+an intermediate representation language that LLVM can compile into machine
+code. `numba` depends on [`llvmlite`](https://github.com/numba/llvmlite), which
+provides a subset of the LLVM API, statically linked into the binaries in that
+package. This is just enough to compile the `numba` generated LLVM IR into
+machine code. We can't use this strategy, because we compile general C/C++
+code. Converting that into LLVM IR is exactly what we need a compiler for.
+
+## For Developers
+
+To create a new release, tag the current commit with a
+version number and push it to the `upstream` remote:
+
+```bash
+git tag -a "vX.Y.Z" -m "vX.Y.Z"
+git push upstream --follow-tags
+```
+
+This will trigger the CI workflow, which will build the package and upload it to PyPI.
+
+### Testing in a conda environment
+
+To simulate a naive user environment, with *no* assumptions made about the
+availability of a C/C++ compiler, you can run the included Dockerfile
+(where the key part of the conda env is the `compilers` package):
+
+```bash
+docker build -t spatial_graph .
+docker run --rm spatial_graph
+```

spatial_graph-0.0.1/README.md → spatial_graph-0.0.3/docs/index.md

@@ -1,44 +1,28 @@
-# spatial_graph
+# 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,
+`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
-==========
+It leverages well-in-time compiled C++ code for efficient graph operations,
+coupled with an rtree implementation for fast spatial queries.
+
+## 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
+- PYX API for graph algorithms in C/C++
+
+## Basic Usage
 
 Graph creation:
 
@@ -49,7 +33,6 @@ graph = sg.SpatialGraph(
     node_attr_dtypes={"position": "double[3]"},
     edge_attr_dtypes={"score": "float32"},
     position_attr="position",
-    directed=False,
 )
 ```
 
@@ -104,9 +87,4 @@ Delete nodes/edges:
 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)).
+See the [API documentation](./reference) for more details.