Ipyannotator - the infinitely hackable annotation framework

Ipyannotator is a flexible annotation system. Developed to allow users to hack its features by extending and customizing it.

The large variety of annotation tasks, data formats and data visualizations is a challenging when dealing with multiple domains of supervised machine learning (ML). The existent tooling is often not flexible enough which imposes limitations to the user. By providing a framework where users can use, customize and create their own annotation tooling this projects aims to solve this problem.

The library contains some pre-defined annotators that can be used out of the box, but it also can be extend and customized according to the users needs. Check our tutorials for a quickly understanding of it's usage and check our API for quick reference.

This library has been written in the literate programming style popularized for jupyter notebooks by nbdev. In addition to our online documentation the jupyter notebooks located at nbs/ allow an interactive exploration of the inner workings of Ipyannotator.

We hope this repository helps you to explore how annotation UI's can be quickly built using only python code and leveraging many awesome libraries (ipywidgets, voila, ipycanvas, etc.) from the jupyter Eco-system.

At https://palaimon.io we have used the concepts underlying Ipyannotator internally for various projects and this is our attempt to contribute back to the OSS community some of the benefits we have had using OOS software.

Please star, fork and open issues!

Please let us know if you find this repository useful. Your feedback will help us to turn this proof of concept into a comprehensive library.

Citation

If you make use of this software for your work we would appreciate it if you would cite the paper from the Journal of Open Source Software:

@article{Epifânio2022,
   title = {Ipyannotator: the infinitely hackable annotation framework},
   author = {Ítalo Epifânio and Oleksandr Pysarenko and Immanuel Bayer},
   journal = {Journal of Open Source Software},
   publisher = {The Open Journal},
   volume = {7},
   number = {76},
   pages = {4480},
   year = {2022}
} 

Install

Ipyannotator is available on Pypi and can be installed using:

pip install ipyannotator

Running ipyannotator

Ipyannotator provides a simple API that provides the ability to explore, create and improve annotation datasets by using a pair of input/outputs. All pair of input/output are listed on Ipyannotator's docs. Check Ipyannotator tutorials for a quickly demonstration of the library.

Run ipyannotator tests

To run Ipyannotator's tests:

1. Install poetry
2. Create the test environment with poetry install
3. Activate the poetry environment using poetry shell
4. Run tests by executing nbdev_test_nbs

Run ipyannotator as stand-alone web app using voila

Ipyannotator can be executed as a web app using the voila library. The following sections describe how to run using poetry and pip.

Using poetry

On your terminal:

cd {project_root}
poetry install --no-dev

Any jupyter notebook with ipyannotator can be executed as an standalone web application. An example of voila usage it's available in the current repository and can be executed as it follow:

poetry run voila nbs/09_voila_example.ipynb --enable_nbextensions=True

Using pip

The installation and execution process can also be done using pip.

   cd {project_root}
   
   pip install .
   pip install voila
   
   voila nbs/09_voila_example.ipynb --enable_nbextensions=True

Jupyter lab trouble shooting

For clean (re)install make sure to have all the lab extencions active:

jupyter lab clean to remove the staging and static directories from the lab

ipywidgets:

jupyter labextension install @jupyter-widgets/jupyterlab-manager

ipycanvas:

jupyter labextension install @jupyter-widgets/jupyterlab-manager ipycanvas

ipyevents:

jupyter labextension install @jupyter-widgets/jupyterlab-manager ipyevents

nbdime:

nbdime extensions --enable [--sys-prefix/--user/--system]

viola:

jupyter labextension install @jupyter-voila/jupyterlab-preview

How to contribute

Check out CONTRIBUTING.md and since ipyannotator is build using nbdev reading the nbdev tutorial and related docs will be very helpful.

Additional resources

• jupytercon 2020 talk.

• Recording of jupytercon 2020 talk explaining the high level concepts / vision of ipyannotator.

Acknowledgements

The authors acknowledge the financial support by the Federal Ministry for Digital and Transport of Germany under the program mFUND (project number 19F2160A).

Copyright

Copyright 2022 onwards, Palaimon GmbH. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project's files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository.