Welcome to AstronomicAL’s documentation!

An interactive dashboard for visualisation, integration and classification of data using Active Learning.

https://travis-ci.com/grant-m-s/astronomicAL.svg?token=upRGxrMseZqj7kT3bSGx&branch=master https://codecov.io/gh/grant-m-s/astronomicAL/branch/master/graph/badge.svg?token=TCO9J2AD1Z https://readthedocs.org/projects/astronomical/badge/?version=latest https://joss.theoj.org/papers/10.21105/joss.03635/status.svg https://img.shields.io/badge/Python-3.8-blue?style=flat&logo=python&logoColor=white

AstronomicAL is a human-in-the-loop interactive labelling and training dashboard that allows users to create reliable datasets and robust classifiers using active learning. The system enables users to visualise and integrate data from different sources and deal with incorrect or missing labels and imbalanced class sizes by using active learning to help the user focus on correcting the labels of a few key examples. Combining the use of the Panel, Bokeh, modAL and SciKit Learn packages, AstronomicAL enables researchers to take full advantage of the benefits of active learning: high accuracy models using just a fraction of the total data, without the requirement of being well versed in underlying libraries.


Statement of Need

With ever-growing datasets, it is becoming impossible to manually inspect and verify ground truth used to train machine learning systems. The reliability of the training data limits the performance of any supervised learning model, so consistent classifications become more problematic as data sizes increase. The problem is exacerbated when a dataset does not contain any labelled data, preventing supervised learning techniques entirely. Active learning (Settles, 2012) addresses these issues by removing the requirement for large amounts of labelled training data whilst still producing high accuracy models.

Although initially designed for astronomers, by providing the functionality for data fusion of catalogued data and online cutout services, AstronomicAL has been developed to be sufficiently general for any tabular data. Large datasets, unreliable labels and vastly imbalanced classes make astronomy data the ideal vehicle to develop this software. Each of these issues is an examplar of more generalised problems that active learning could solve in any dataset.

Using its modular and extensible design, researchers can quickly adapt AstronomicAL for their research to allow for domain-specific plots, novel query strategies, and improved models. Further, there is no requirement to be well-versed in the underlying libraries that the software uses as large parts of the complexity are abstracted whilst still allowing more experienced users to access full customisability.

As the software runs entirely locally on the user’s system, AstronomicAL provides a private space to experiment whilst providing a public mechanism to share results. By sharing only the configuration file, users remain in charge of distributing their potentially sensitive data, enabling collaboration whilst respecting privacy.


To install AstronomicAL and its dependencies, the user can clone the repository and from within the repo folder run pip install -r requirements.txt. It is recommended that the user creates a virtual environment using tools such as Virtualenv or Conda, to prevent any conflicting package versions.

git clone https://github.com/grant-m-s/AstronomicAL.git
cd AstronomicAL
conda config --add channels conda-forge
conda create --name astronomical --file requirements.txt python=3.8
conda activate astronomical

Quickstart Instructions

To begin using the software, run bokeh serve astronomicAL --show, and your browser should automatically open to localhost:5006/astronomicAL.

AstronomicAL provides an example dataset and an example configuration file to allow you to jump right into the software and give it a test run.


AstronomicAL makes it easy to start training your classifier or reload a previous checkpoint.

To begin training, you simply have to select Load Custom Configuration checkbox and select your config file. Here we have chosen to use the example_config.json file.

The Load Config Select option allows users to choose the extent to which to reload the configuration.

Contributing to AstronomicAL

Reporting Bugs

If you encounter a bug, you can directly report it in the issues section.

Please describe how to reproduce the bug and include as much information as possible that can be helpful for fixing it.

Are you able to fix a bug?

You can open a new pull request or include your suggested fix in the issue.

Submission of extensions

Have you created an extension that you want to share with the community?

Create a pull request describing your extension and how it can improve research for others.

Support and Feedback

We would love to hear your thoughts on AstronomicAL.

Are there any features that would improve the effectiveness and usability of AstronomicAL? Let us know!

Any feedback can be submitted as an issue.

Referencing the Package

Please remember to cite our software and user guide whenever relevant.

See the citing page for instructions about referencing and citing the AstronomicAL software.

Indices and tables

_images/CDT-UOB-logo.png _images/EPSRC%2Blogo.png