antares-devkit

Provides tools and utility methods to write and debug ANTARES filters with Python.

ANTARES is an Alert Broker developed by the NSF NOIRLab for ZTF and LSST.

If you want to write and submit a filter to ANTARES please follow the steps to submit a filter in our documentation. If you wrote a filter for antares and is not in the devkit repository, contact us and we'll send you your code from our backup.

Installation

The ANTARES DevKit supports Python version 3.9 and up and can be installed with pip:

pip install antares-devkit

Basic Usage

The DevKit can be used in a local environment and also on NSF NOIRLab’s Astro Data Lab Jupyter environment.

A basic example of creating and executing a filter is provided below.

Create a HelloWorld filter:

from antares_devkit.models import BaseFilter


class HelloWorld(BaseFilter):
    OUTPUT_LOCUS_TAGS = [
        {"name": "hello_world", "description": "hello!"},
    ]

    def _run(self, locus):
        print("Hello Locus ", locus.locus_id)

Run the filter on a random ANTARES locus:

from antares_client import search
from antares_devkit.models import DevKitLocus
from antares_devkit.utils import filter_report

# fetch a random locus from the antares database using the antares-client
client_locus = search.get_random_locus()
devkit_locus = DevKitLocus.model_validate(client_locus.to_devkit())

# execute the filter
HelloWorld().run(devkit_locus)

For more information and additional examples visit our DevKit guide.

Development

How does this work?

This repository can be shipped as a python package on pip and also can be used in installations using the repository with tags. Then the filter_runner docker image in the antares main repository is going to install all the filters and required packages, then we use a gcp bucket to know which filters are enabled or disabled.

How to test filters using Docker (Recommended)

docker build -t antares_devkit:3.9 -f test/Dockerfile .
docker run -v $(pwd)/antares_devkit:/usr/src/app/antares_devkit -v $(pwd)/test:/usr/src/app/test -it antares_devkit:3.9
uv run pytest test

How to setup local environment (with conda)

conda create -n devkit python=3.9 -y
conda activate devkit
pip install uv
uv sync --all-groups --all-extras

How to add a filter dependency

uv add "{package_name}" --optional filter-dependencies

or for jupyter lab libraries use:

uv add "{package_name}" --optional jupyter

How to add a dev dependency

uv add "{package_name}" --group dev

or for docs libraries use:

uv add "{package_name}" --group docs

How to run a jupyter notebook

uv run --with jupyter jupyter lab

How to write documentation

Add md files and update mkdocs.yml to add them in the nav.

How to update filters src

1. Execute uv run python scripts/update_filters_src.py
2. Paste the output in mkdocs.yml within the nav.Filters replacing the entire section.

How to view the documentation locally

Install necessary dependencies:

uv sync --group docs

Serve the docs:

uv run mkdocs serve