webKnossos Python library

In this post, I would like to showcase our new Python library for working and interacting with datasets and annotations from webKnossos. The library is a great tool for expanding your webKnossos annotations with advanced analysis algorithms in Python or for automating workflows.

The webKnossos Python package offers three main features:

1. An easy-to-use, high-level API for working with 2D and 3D webKnossos datasets in the webKnossos wrap (*.wkw) files. Create new datasets from raw microscopy data, read annotations as Numpy arrays for image processing, or manipulate existing datasets by adding/removing layers or up/downsampling operations, and more.
2. Versatile Python objects for reading and writing line-segment (“skeleton”) annotations from *.nml files. Manipulate your annotations in an object-oriented API instead of going through text files. Easily convert skeleton into graph structures for deep analysis.
3. Interaction with your webKnossos instance. Directly download raw data and annotations into analysis workflows or upload results from advanced processing such as machine learning classification to your webKnossos online account.

Getting Started

The webKnossos Python package is available through Python’s standard PyPi repository. Install it like you would any other Python package:

pip install webknossos

In your Python project, you can then import the webKnossos package and integrate it with your existing code, e.g. for loading and manipulating a webKnossos dataset:

The library requires at least Python 3.7+. The code is available as open-source on GitHub and we are happy to accept pull requests from the community. There, we also maintain a Changelog and release notes in case you are interested.

Moreover, we provide a wide range of examples and detailed API documentation on the webKnossos docs website: https://docs.webknossos.org/webknossos-py/

Example 1: Uploading Image Data

In this example, we will open a 3D image stack in the webKnossos wrap (WKW) file format and upload it to your webKnossos organization. Here, we assume you have an account webKnossos.org (free), but it should also work with an up-to-date on-premise installation.

3D Cell Image Data uploaded to webKnossos

Example 2: Download a volume annotation and train a machine learning model

In this example, we will showcase a complete segmentation and simple machine learning workflow with webKnossos.

(left) Annotated Data in Skin Tissue (right) Classification Result

For this example, we have already uploaded a small 2D microscopy dataset of skin tissue to webKnossos and roughly annotated the 3 different skin layers as a volume annotation. We will use this small annotated, bounding box to train a random forest classifier for segmenting the whole image. We can use the Python library to download both the raw microscopy data and accompanying annotation directly from our webKnossos instance. Model training and prediction are then executed locally on your workstation. The resulting segmentation is then uploaded to webKnossos as a new dataset and can be shared with colleagues or further refined with more volume annotation.

Example 3: Working with skeleton annotations

Skeleton annotations and nodes in webKnossos are a very versatile feature. We use them to highlight and mark all sorts of interesting image details in our data.

In this last example, we want to find node pairs within a minimum distance from each other. Let’s assume that each tree in our skeleton annotation follows along a dendrite’s or axon’s path in a neuron with nodes regularly placed along their entire path length. Whenever a node of one neuron skeleton and a second skeleton get close to one another within a specified 3D distance (spherical threshold), we can mark the node pair as a possible location of a synaptic connection (“synapse candidate”) because of their close vicinity.

All resulting candidates will be added to skeleton annotation and written as a new *.nml file. Upload the resulting *.nml file to webKnossos like you normally would, e.g. with drag and drop in wK, and inspect our candidate locations.

— -

Please, read the docs for an always up-to-date version of these examples. We hope these examples can be a great starting point for incorporating webKnossos in your Python workflows.

We would love to hear your feedback on the new webKnossos Python package. Let us know what you think and what features you would like to see in the future. Open a pull request or issue on GitHub or email us at hello@webknossos.org.