geff 0.0__tar.gz

geff-0.0/.gitattributes

@@ -0,0 +1,2 @@
+# SCM syntax highlighting & preventing 3-way merges
+pixi.lock merge=binary linguist-language=YAML linguist-generated=true

geff-0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Proposed Change
+Briefly describe the contribution. If it resolves an issue or feature request, be sure to link to that issue.
+
+# Types of Changes
+What types of changes does your code introduce? Delete those that do not apply.
+- Bugfix (non-breaking change which fixes an issue)
+- New feature or enhancement
+- Documentation update
+- Tests
+- Maintenance (e.g. dependencies, CI, releases, etc.)
+
+Which topics does your change affect? Delete those that do not apply.
+- Specification
+- `networkx` implementation
+
+# Checklist
+Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your code.
+
+- [ ] I have read the developer/contributing docs.
+- [ ] I have added tests that prove that my feature works in various situations or tests the bugfix (if appropriate).
+- [ ] I have checked that I maintained or improved code coverage.
+- [ ] I have written docstrings and checked that they render correctly.
+- [ ] If I changed the specification, I have checked that any validation functions and tests reflect the changes.
+
+# Further Comments
+If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc...

geff-0.0/.github/workflows/ci.yaml

@@ -0,0 +1,165 @@
+name: Test geff
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+    tags: [v*]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  SETUPTOOLS_SCM_PRETEND_VERSION: "0.0"
+
+jobs:
+  tests:
+    uses: ./.github/workflows/test.yaml
+    with:
+      test-target: "tests"
+      witty-cache: false
+      install-extras: "dev"
+
+  schema:
+    name: Check json schema
+    runs-on: ubuntu-latest
+    env:
+      testjson: check-json.json
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache-dependency-path: "pyproject.toml"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          pip install .
+
+      - name: Generate json 
+        run: python scripts/export_json_schema.py --filename $testjson
+
+      - run: cat $testjson
+
+      - name: Compare hashes
+        if: ${{ hashFiles( env.testjson ) != hashFiles('geff-schema.json') }}
+        uses: actions/github-script@v3
+        with:
+          script: |
+              core.setFailed('geff-schema.json needs to be updated by locally running `pixi run update-json`. ${{ hashFiles( env.testjson ) }} vs ${{ hashFiles('geff-schema.json') }}')
+
+  benchmark:
+    name: Benchmark
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 50 # this is to make sure we obtain the target base commit
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.13
+          cache-dependency-path: "pyproject.toml"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e .[bench,dev]
+
+      - name: Retrieve cached baseline if available
+        uses: actions/cache/restore@v4
+        id: cache_baseline
+        with:
+          path: baseline.json
+          key: ${{ github.event.pull_request.base.sha }}
+
+      - name: Run baseline benchmark if not in cache
+        if: steps.cache_baseline.outputs.cache-hit != 'true'
+        run: |
+          git checkout ${{ github.event.pull_request.base.sha }}
+          pytest tests/bench.py -v --benchmark-json baseline.json
+
+      - name: Cache baseline results
+        uses: actions/cache/save@v4
+        if: steps.cache_baseline.outputs.cache-hit != 'true'
+        with:
+          path: baseline.json
+          key: ${{ github.event.pull_request.base.sha }}
+
+      - name: Run benchmark on PR head commit
+        run: |
+          git checkout ${{ github.event.pull_request.head.sha }}
+          pytest tests/bench.py -v --benchmark-json pr.json
+
+      - name: Generate report
+        run: python scripts/benchmark-pr.py baseline.json pr.json report.md
+
+      - name: Comment on commit with report for non-forks
+        uses: peter-evans/commit-comment@v3
+        if: github.event.pull_request.head.repo.fork == false
+        with:
+          body-path: report.md
+          token: ${{ secrets.COMMIT_MESSAGE_TOKEN }}
+
+  deploy:
+    name: Deploy
+    # TODO: Add back successful test requirement once package is more stable
+    # needs: test
+    # if: success() && startsWith(github.ref, 'refs/tags/') && github.event_name != 'schedule'
+    if: 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: Install geff
+        run: pip install .
+
+      - run: echo ${{ github.ref_name }}
+
+      - name: Check supported_versions.yml
+        shell: python
+        run: |
+          import re; from geff.metadata_schema import SUPPORTED_VERSIONS_REGEX
+
+          if re.search(SUPPORTED_VERSIONS_REGEX, "${{ github.ref_name }}") is None:
+              sys.exit("`supported_versions.yml`  needs to be updated to include new release ${{ github.ref_name }}")
+
+      - 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/*"

geff-0.0/.github/workflows/gh-pages.yaml

@@ -0,0 +1,86 @@
+name: Push gh-pages updates update
+
+# push to the gh-pages branch whenever there is a new push to main or a new tag
+on:
+  push:
+    branches:
+      - main
+    tags: ["*"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  deployments: write
+
+env:
+  TAG: ${{ contains(github.ref, 'tags') && 'latest' || 'dev'}}
+  SETUPTOOLS_SCM_PRETEND_VERSION: "0.0"
+
+jobs:
+  push-docs:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: gh-pages
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          pip install -e ".[docs]"
+
+      - id: get_version
+        uses: battila7/get-version-action@v2
+
+      - name: configure git
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git fetch origin gh-pages --depth=1
+
+      - name: Update schema docs
+        run: |
+          mkdir docs/schema
+          generate-schema-doc geff-schema.json docs/schema/schema.html
+
+      - name: Push changes to gh-pages branch
+        run: mike deploy ${{ steps.get_version.outputs.version }} $TAG -u -p
+
+  benchmark:
+    name: Report benchmarks on gh-pages
+    runs-on: ubuntu-latest
+    concurrency:
+      group: gh-pages
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+          cache-dependency-path: "pyproject.toml"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install -e .[dev,bench]
+
+      - name: Run benchmark
+        run: |
+          pytest tests/bench.py --benchmark-json output.json
+
+      - name: Store benchmark results
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          name: Python Benchmark with pytest-benchmark
+          tool: 'pytest'
+          output-file-path: output.json
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          auto-push: true
+          benchmark-data-dir-path: bench/

geff-0.0/.github/workflows/test.yaml

@@ -0,0 +1,83 @@
+on:
+  workflow_call:
+    inputs:
+      test-target:
+        required: true
+        type: string
+      witty-cache: 
+        required: true
+        type: boolean
+      install-extras:
+        required: true
+        type: string
+
+env:
+  SETUPTOOLS_SCM_PRETEND_VERSION: "0.0"
+
+jobs:
+  test:
+    name: ${{ matrix.platform }} ${{ matrix.python-version }} zarr ${{ matrix.zarr-version }}
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+        zarr-version: ["2.*", "3.*"]
+        exclude:
+          # Zarr 3 doesn't support 3.10
+          - zarr-version: "3.*"
+            python-version: "3.10"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache-dependency-path: "pyproject.toml"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -U pip
+          python -m pip install zarr==${{ matrix.zarr-version }}
+          python -m pip install -e .[${{ inputs.install-extras }}]
+          python -m pip list
+
+      - name: Get witty cache directory
+        if: ${{ inputs.witty-cache }}
+        id: cache-path
+        run: |
+          import Cython.Utils
+          import os
+
+          cache_path = os.path.join(Cython.Utils.get_cython_cache_dir(), "witty")
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as fh:
+              print(f"path={cache_path}", file=fh)
+        shell: python
+
+      - name: Check for witty cache
+        uses: actions/cache/restore@v4
+        id: witty-cache
+        if: ${{ inputs.witty-cache }}
+        with:
+          path: ${{ steps.cache-path.outputs.path }}
+          key: ${{ matrix.platform }} - ${{ matrix.python-version }}
+
+      - name: Test
+        run: pytest --color=yes --cov --cov-report=xml --cov-report=term-missing ${{ inputs.test-target }}
+
+      - name: Coverage
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Save witty cache
+        uses: actions/cache/save@v4
+        if: ${{ inputs.witty-cache }}
+        with:
+          path: ${{ steps.cache-path.outputs.path }}
+          key: ${{ matrix.platform }} - ${{ matrix.python-version }}

geff-0.0/.gitignore

@@ -0,0 +1,27 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Temporary files
+*.sw[pmno]
+*.zarr
+
+# Virtual environments
+.venv
+
+# pixi environments
+.pixi
+*.egg-info
+pixi.lock
+
+.DS_Store
+
+# Autogenerated docs files
+docs/schema/*
+
+# Pytest coverage local files
+.coverage*

geff-0.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+ci:
+  autoupdate_schedule: monthly
+  autofix_commit_msg: "style(pre-commit.ci): auto fixes [...]"
+  autoupdate_commit_msg: "ci(pre-commit.ci): autoupdate"
+  autofix_prs: false
+
+repos:
+  - repo: https://github.com/crate-ci/typos
+    rev: v1
+    hooks:
+      - id: typos
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        files: "^src/"
+        # # you have to add the things you want to type check against here
+        additional_dependencies:
+          - types-pyyaml

geff-0.0/CONTRIBUTING

@@ -0,0 +1,41 @@
+# CONTRIBUTING
+
+We recommend using `pixi` for environment management while developing `geff`. See the [pixi docs](https://pixi.sh/dev/) for installation instructions. The following instructions will be focused on pixi-based development, but all of the same tasks can be completed with pip and another environment manager.
+
+For local development, clone the repo and install in editable mode.
+```
+git clone https://github.com/funkelab/geff.git
+pixi install
+```
+
+## Testing
+To run tests
+```
+pixi run test
+```
+
+## Style
+We utilize `pre-commit` with ruff for linting and formatting. If you would like to run `pre-commit` locally:
+```
+pixi run -e dev pre-commit install
+```
+Alternatively [pre-commit.ci](https://pre-commit.ci/), will run and commit changes on any open PRs.
+
+## Releases
+In order to deploy a new version, tag the commit with a version number and push it to github. This will trigger a github action that will build and deploy to PyPI. (see the "deploy" step in workflows/ci.yml). The version number is determined automatically based on the tag.
+
+Prior to making a release that bumps the major or minor number, the `supported_versions.yml` needs to be updated and the json schema updated by running `pixi run update-json`. 
+
+```
+git tag -a v0.1.0 -m v0.1.0
+git push --follow-tags
+```
+
+## Docs
+
+Docs are written with MkDocs
+
+Relevant commends can be run using `pixi run -e docs <mkdocs command>`
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.

geff-0.0/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.

geff-0.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: geff
+Version: 0.0
+Summary: Reference implementation of the Graph Exchange File Format
+License: MIT License
+Project-URL: repository, https://github.com/live-image-tracking-tools/geff
+Project-URL: homepage, https://github.com/live-image-tracking-tools/geff
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: zarr<4,>2
+Requires-Dist: pydantic
+Requires-Dist: pyyaml
+Requires-Dist: numcodecs<0.16
+Requires-Dist: networkx
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.4; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocstrings[python]; extra == "docs"
+Requires-Dist: mkdocs-api-autonav; extra == "docs"
+Requires-Dist: mkdocs-include-markdown-plugin; extra == "docs"
+Requires-Dist: mike; extra == "docs"
+Requires-Dist: json-schema-for-humans; extra == "docs"
+Requires-Dist: typing-extensions; extra == "docs"
+Provides-Extra: bench
+Requires-Dist: pytest-benchmark; extra == "bench"
+Requires-Dist: tabulate; extra == "bench"
+Requires-Dist: pandas; extra == "bench"
+Requires-Dist: typer; extra == "bench"
+Dynamic: license-file
+
+# Graph Exchange File Format (geff)
+
+<!--intro-start-->
+
+[![License](https://img.shields.io/pypi/l/geff.svg?color=green)](https://github.com/funkelab/geff/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/geff.svg?color=green)](https://pypi.org/project/geff)
+[![Python Version](https://img.shields.io/pypi/pyversions/geff.svg?color=green)](https://python.org)
+[![Test geff](https://github.com/funkelab/geff/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/geff/actions/workflows/ci.yaml)
+
+geff is a specification for a file format for **exchanging** spatial graph data. It is not intended to be mutable, editable, chunked, or optimized for use in an application setting.
+
+geff is the specification of the file format, but the library also includes implementations for writing from and reading to a networkx graph, a common Python in-memory graph data structure. The library uses semantic versioning, where changes to the specification bump the major or minor versions, and bugfixes for the example implementation bumps the patch version.
+
+## Installation
+
+```
+pip install geff
+```
+<!--intro-end-->

geff-0.0/README.md

@@ -0,0 +1,19 @@
+# Graph Exchange File Format (geff)
+
+<!--intro-start-->
+
+[![License](https://img.shields.io/pypi/l/geff.svg?color=green)](https://github.com/funkelab/geff/raw/main/LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/geff.svg?color=green)](https://pypi.org/project/geff)
+[![Python Version](https://img.shields.io/pypi/pyversions/geff.svg?color=green)](https://python.org)
+[![Test geff](https://github.com/funkelab/geff/actions/workflows/ci.yaml/badge.svg)](https://github.com/funkelab/geff/actions/workflows/ci.yaml)
+
+geff is a specification for a file format for **exchanging** spatial graph data. It is not intended to be mutable, editable, chunked, or optimized for use in an application setting.
+
+geff is the specification of the file format, but the library also includes implementations for writing from and reading to a networkx graph, a common Python in-memory graph data structure. The library uses semantic versioning, where changes to the specification bump the major or minor versions, and bugfixes for the example implementation bumps the patch version.
+
+## Installation
+
+```
+pip install geff
+```
+<!--intro-end-->

geff-0.0/docs/index.md

@@ -0,0 +1,7 @@
+# Welcome to geff!
+
+{%
+    include-markdown "../README.md"
+    start="<!--intro-start-->"
+    end="<!--intro-end-->"
+%}

geff-0.0/docs/specification.md

@@ -0,0 +1,74 @@
+# Geff specification
+
+The graph exchange file format is `zarr` based. A graph is stored in a zarr group, which can have any name. This allows storing multiple `geff` graphs inside the same zarr root directory. A `geff` group is identified by the presence of a `geff_version` attribute in the `.zattrs`. Other `geff` metadata is also stored in the `.zattrs` file of the `geff` group. The `geff` group must contain a `nodes` group and an `edges` group.
+
+## Geff metadata
+
+{%
+    include "schema/schema.html"
+%}
+
+## The `nodes` group
+The nodes group will contain an `ids` array and an `attrs` group.
+
+### The `ids` array
+The `nodes\ids` array is a 1D array of node IDs of length `N` > 0, where `N` is the number of nodes in the graph. Node ids must be unique. Node IDs can have any type supported by zarr, but we recommend integer dtypes. For large graphs, `uint64` might be necessary to provide enough range for every node to have a unique ID. 
+
+### The `attrs` group and `node attribute` groups
+The `nodes\attrs` group will contain one or more `node attribute` groups, each with a `values` array and an optional `missing` array. 
+
+- `values` arrays can be any zarr supported dtype, and can be N-dimensional. The first dimension of the `values` array must have the same length as the node `ids` array, such that each row of the attribute `values` array stores the attribute for the node at that index in the ids array. 
+- The `missing` array is an optional, a one dimensional boolean array to support attributes that are not present on all nodes. A 1 at an index in the `missing` array indicates that the `value` of that attribute for the node at that index is None, and the value in the `values` array at that index should be ignored. If the `missing` array is not present, that means that all nodes have values for the attribute. 
+
+!!! note
+    When writing a graph with missing attributes to the geff format, you must fill in a dummy value in the `values` array for the nodes that are missing the attribute, in order to keep the indices aligned with the node ids.
+
+- The `position` group is a special node attribute group that must be present and does not allow missing attributes.
+- The `seg_id` group is an optional, special node attribute group that stores the segmenatation label for each node. The `seg_id` values do not need to be unique, in case labels are repeated between time points. If the `seg_id` group is not present, it is assumed that the graph is not associated with a segmentation. 
+<!-- Perhaps we just let the user specify the seg id attribute in the metadata instead? Then you can point it to the node ids if you wanted to -->
+
+## The `edges` group
+Similar to the `nodes` group, the `edges` group will contain an `ids` array and an `attrs` group. If there are no edges in the graph, the edge group is not created.
+
+### The `ids` array
+The `edges\ids` array is a 2D array with the same dtype as the `nodes\ids` array. It has shape `(2, E)`, where `E` is the number of edges in the graph. All elements in the `edges\ids` array must also be present in the `nodes\ids` array.
+Each row represents an edge between two nodes. For directed graphs, the first column is the source nodes and the second column holds the target nodes. For undirected graphs, the order is arbitrary.
+Edges should be unique (no multiple edges between the same two nodes) and edges from a node to itself are not supported.
+
+### The `attrs` group and `edge attribute` groups
+The `edges\attrs` group will contain zero or more `edge attribute` groups, each with a `values` array and an optional `missing` array. 
+
+- `values` arrays can be any zarr supported dtype, and can be N-dimensional. The first dimension of the `values` array must have the same length as the `edges\ids` array, such that each row of the attribute `values` array stores the attribute for the edge at that index in the ids array. 
+- The `missing` array is an optional, a one dimensional boolean array to support attributes that are not present on all edges. A 1 at an index in the `missing` array indicates that the `value` of that attribute for the edge at that index is missing, and the value in the `values` array at that index should be ignored. If the `missing` array is not present, that means that all edges have values for the attribute.
+
+If you do not have any edge attributes, the `edges\attrs` group should still be present, but empty.
+
+## Example file structure and metadata
+
+TODO: Example metadata for this file structure
+``` python
+/path/to.zarr
+    /tracking_graph
+	    .zattrs  # graph metadata with `geff_version`
+	    nodes/
+            ids  # shape: (N,)  dtype: uint64
+            attrs/
+                position/
+                    values # shape: (N, 3) dtype: float16
+                color/
+                    values # shape: (N, 4) dtype: float16
+                    missing # shape: (N,) dtype: bool
+	    edges/
+            ids  # shape: (E, 2) dtype: uint64
+            attrs/
+                distance/
+                    values # shape: (E,) dtype: float16
+                score/
+                    values # shape: (E,) dtype: float16
+                    missing # shape: (E,) dtype: bool
+    # optional:
+    /segmentation 
+    
+    # unspecified, but totally okay:
+    /raw 
+```

geff-0.0/docs/what-is-geff.md

@@ -0,0 +1,12 @@
+# What is geff?
+
+`geff` is a graph exchange file format that seeks to fulfill the following needs:
+- Provide a storage/exchange format for graphs and optional segmentation
+- Provide a common API with reference implementations for use in other projects
+
+## Design Decisions and Assumptions
+
+- Raw image data is not included in the `geff` spec. However, to keep nodes linked to segmentation labels, support for specifying the seg_id of each node in a standard way, along with the path to the segmentation, are included in the `spec`.
+- Since `geff` is an exchange format, we do not provide support for searching or filtering.
+- We do not provide support for editing or changing the graph on the fly.
+- In order to support efficient reading/writing, we assume the graph can fit into memory.

geff-0.0/geff-schema.json

@@ -0,0 +1 @@
+{"description": "Geff metadata schema to validate the attributes json file in a geff zarr", "properties": {"geff_version": {"pattern": "(0\\.0)|(0\\.1)", "title": "Geff Version", "type": "string"}, "directed": {"title": "Directed", "type": "boolean"}, "roi_min": {"items": {"type": "number"}, "title": "Roi Min", "type": "array"}, "roi_max": {"items": {"type": "number"}, "title": "Roi Max", "type": "array"}, "position_attr": {"default": "position", "title": "Position Attr", "type": "string"}, "axis_names": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "default": null, "title": "Axis Names"}, "axis_units": {"anyOf": [{"items": {"type": "string"}, "type": "array"}, {"type": "null"}], "default": null, "title": "Axis Units"}}, "required": ["geff_version", "directed", "roi_min", "roi_max"], "title": "geff_metadata", "type": "object"}