NeuronConnector class for connectivity of TreeNeurons

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Description**
+A clear and concise description of what the bug is. 
+
+**To Reproduce**
+A minimal code example to reproduce the bug. If any extra data (e.g. skeletons) are required, please attach the file(s) to the issue.
+
+```Python
+import navis 
+...
+```
+
+If the code generates an error please make sure to share the _entire_ traceback.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Your system**
+- NAVis version: [e.g. 1.5.0]
+- Python version: [e.g. Python 3.10]
+- Operating System: [e.g. OSX, Windows or Linux]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. 
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/test-package.yml

@@ -36,6 +36,7 @@ jobs:
         pip install flybrains --no-deps
         pip install git+https://github.com/siavashk/pycpd@master
         pip install k3d
+        pip install pyarrow
     - name: Install navis
       run: pip install -e .[dev,vispy-pyqt5,pathos,cloudvolume]
     - run: pip install python-igraph

.readthedocs.yaml

@@ -1,18 +1,34 @@
-# https://docs.readthedocs.io/en/stable/config-file/v2.html#supported-settings
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
 version: 2
 
-sphinx:
-  builder: html
-
+# Add some extra build dependencies (graphviz for plotting)
+# Set the version of Python and other tools you might need
 build:
-  os: "ubuntu-20.04"
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
-    rust: "1.55"
+    python: "3.10"
+  apt_packages:
+    - graphviz
+    - graphviz-dev
 
+# Make sure that dependencies are installed with pip instead of setup.py
 python:
   install:
+    - requirements: docs/preinstall_requirements.txt
     - requirements: docs/requirements.txt
+    #- requirements: requirements.txt
     - method: pip
       path: .
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+#formats:
+#  - pdf

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

README.md

@@ -1,8 +1,8 @@
-[![Documentation Status](https://readthedocs.org/projects/navis/badge/?version=latest)](http://navis.readthedocs.io/en/latest/?badge=latest) [![Tests](https://github.com/navis-org/navis/actions/workflows/test-package.yml/badge.svg)](https://github.com/navis-org/navis/actions/workflows/test-package.yml) [![Run notebooks](https://github.com/navis-org/navis/actions/workflows/notebooktest-package.yml/badge.svg)](https://github.com/navis-org/navis/actions/workflows/notebooktest-package.yml) [![Coverage Status](https://coveralls.io/repos/github/navis-org/navis/badge.svg?branch=master)](https://coveralls.io/github/navis-org/navis?branch=master) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/navis-org/navis/blob/master/examples/colab.ipynb) [![DOI](https://zenodo.org/badge/168142416.svg)](https://zenodo.org/badge/latestdoi/168142416) [![Downloads](https://pepy.tech/badge/navis)](https://pepy.tech/project/navis)
+[![Documentation Status](https://readthedocs.org/projects/navis/badge/?version=latest)](http://navis.readthedocs.io/en/latest/?badge=latest) [![Tests](https://github.com/navis-org/navis/actions/workflows/test-package.yml/badge.svg)](https://github.com/navis-org/navis/actions/workflows/test-package.yml) [![Run notebooks](https://github.com/navis-org/navis/actions/workflows/notebooktest-package.yml/badge.svg)](https://github.com/navis-org/navis/actions/workflows/notebooktest-package.yml) [![Coverage Status](https://coveralls.io/repos/github/navis-org/navis/badge.svg?branch=master)](https://coveralls.io/github/navis-org/navis?branch=master) [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/navis-org/navis/blob/master/examples/colab.ipynb) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8191725.svg)](https://zenodo.org/doi/10.5281/zenodo.4699382) [![Downloads](https://pepy.tech/badge/navis)](https://pepy.tech/project/navis)
 
 <img src="https://github.com/navis-org/navis/raw/master/docs/_static/favicon.png" height="60">
 
-NAVis is a Python 3 (3.8 or later) library for **N**euron **A**nalysis and **Vis**ualization.
+NAVis is a Python 3 library for **N**euron **A**nalysis and **Vis**ualization.
 
 ## Documentation
 NAVis is on [ReadTheDocs](http://navis.readthedocs.io/ "NAVis ReadTheDocs").
@@ -62,10 +62,30 @@ NAVis comes with batteries included but is also highly extensible. Some
 libraries built on top of NAVis:
 * [flybrains](https://github.com/navis-org/navis-flybrains) provides templates and transforms for *Drosophila* brains to use with navis
 * [pymaid](https://pymaid.readthedocs.io/en/latest/) pulls and pushes data from/to CATMAID servers
-* [fafbseg](https://fafbseg-py.readthedocs.io/en/latest/index.html) contains tools to work with auto-segmented data for the FAFB EM dataset
+* [fafbseg](https://fafbseg-py.readthedocs.io/en/latest/index.html) contains tools to work with auto-segmented data for the FAFB EM dataset including FlyWire
+
+## Who uses NAVis?
+NAVis has been used in a range of neurobiological publications. Here's a semi-random sample
+of recent papers:
+
+```
+BIFROST: a method for registering diverse imaging datasets, Brezovec et al., bioRxiv (2023); doi: https://doi.org/10.1101/2023.06.09.544408
+
+Vimo: Visual Analysis of Neuronal Connectivity Motifs, Troidl et al., bioRxiv (2022); doi: https://doi.org/10.1101/2022.12.09.519772
+
+Information flow, cell types and stereotypy in a full olfactory connectome, Schlegel, Bates et al., eLife (2021); doi: https://doi.org/10.7554/eLife.66018
+
+Synaptic wiring motifs in posterior parietal cortex support decision-making, Kuan et al., bioRxiv (2022); doi: https://doi.org/10.1101/2022.04.13.488176
+```
+
+Want to see your work listed here? Open an [Issue](https://github.com/navis-org/navis/issues) and tell us about it!
+
+## Citing NAVis
+We'd love to know if you found NAVis useful for your research! You can help us
+spread the word by citing the DOI provided by Zenodo [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8191725.svg)](https://zenodo.org/doi/10.5281/zenodo.4699382)
 
 ## License
-This code is under GNU GPL V3
+This code is under [GNU GPL V3](LICENSE).
 
 ## Acknowledgments
 NAVis is inspired by and inherits much of its design from the excellent

docs/index.rst

@@ -81,4 +81,5 @@
                 :link: other_libs
                 :link-type: ref
 
-                Write your own library built on top of navis functions.
+                Write your own library built on top of navis functions. See
+                our :ref:`ecosystem <other_libs>` for examples.

docs/preinstall_requirements.txt

@@ -2,4 +2,4 @@
 # For some odd reason, readthedocs uses a really old version of setuptools
 # Note: as of v58.0.0 the `2to3` option for setup() is gone which breaks
 # ALL installs of sphinx-bootstrap-theme
-setuptools==57.5.0
+setuptools>=65.5.1

docs/requirements.txt

@@ -2,7 +2,7 @@
 # For some odd reason, readthedocs uses a really old version of setuptools
 # Note: as of v58.0.0 the `2to3` option for setup() is gone which breaks
 # ALL installs of sphinx-bootstrap-theme
-setuptools==57.5.0
+setuptools>=65.5.1
 ipykernel
 nbsphinx
 mock

docs/source/api.rst

@@ -7,7 +7,9 @@ API Reference
 at top level (e.g. ``navis.plot3d``) and easily another 100 secondary functions
 available via submodules (e.g. ``navis.morpho.find_soma``). This can be a bit
 daunting at first - especially if you don't exactly know what you are looking
-for. I recommend you either just have a browse, use the search field
+for.
+
+I recommend you either just have a browse, use the search field
 (upper right) or simply search in page (CONTROL/CMD-F). Failing that, please
 feel free to open an `issue <https://github.com/navis-org/navis/issues>`_ on
 the Github repo with your question.
@@ -499,6 +501,11 @@ Connectivity
 ++++++++++++
 Collection of functions to work with graphs and adjacency matrices.
 
+.. autosummary::
+    :toctree: generated/
+
+    navis.NeuronConnector
+
 Graphs
 ------
 Functions to convert neurons and networkx to iGraph or networkX graphs.
@@ -549,6 +556,9 @@ Functions to import/export neurons.
     navis.write_json
     navis.write_precomputed
     navis.read_precomputed
+    navis.read_parquet
+    navis.write_parquet
+    navis.scan_parquet
 
 
 .. _api_utility:

docs/source/other_libraries.rst

@@ -32,7 +32,7 @@ fafbseg
 `fafbseg <https://fafbseg-py.readthedocs.io/en/latest/index.html>`_ contains
 tools to work with autosegmented data for the
 `FAFB <https://www.temca2data.org>`_ (full adult fly brain)
-EM dataset. It brings together data from `flywire <https://flywire.ai/>`_,
+EM dataset. It brings together data from `FlyWire <https://flywire.ai/>`_,
 `Google's <http://fafb-ffn1.storage.googleapis.com/landing.html>`_ segmentation
 of FAFB and `synapse predictions <https://github.com/funkelab/synful>`_ by
 Buhmann et al. (2019).

docs/source/whats_new.rst

@@ -15,6 +15,10 @@ repository.
    * - Version
      - Date
      -
+   * - dev
+     - ongoing
+     - - :class:`navis.NeuronConnector` class for creating connectivity graphs
+         from groups neurons with consistent connector IDs.
    * - 1.5.0
      - 27/07/23
      - - BREAKING: dropped support for Python 3.7

navis/connectivity/__init__.py

@@ -13,8 +13,10 @@
 
 from .predict import cable_overlap
 from .matrix_utils import group_matrix
+from .adjacency import NeuronConnector
 from .cnmetrics import connectivity_sparseness
 from .similarity import connectivity_similarity, synapse_similarity
 
 __all__ = ['connectivity_sparseness', 'cable_overlap',
-           'connectivity_similarity', 'synapse_similarity']
+           'connectivity_similarity', 'synapse_similarity',
+           'NeuronConnector']