Brokers¶

Base Broker Class¶

tom_alerts.alerts.get_service_classes()¶

Gets the broker classes available to this TOM as specified by TOM_ALERT_CLASSES in settings.py. If none are specified, returns the default set.

Returns:: dict of broker classes, with keys being the name of the broker and values being the broker class
Return type:: dict

tom_alerts.alerts.get_service_class(name)¶

Gets the specific broker class for a given broker name.

Returns:: Broker class
Return type:: class

class tom_alerts.alerts.GenericAlert(timestamp: datetime, id: int, name: str, ra: float, dec: float, mag: float, score: float, url: str)¶

dataclass representing an alert in order to display it in the UI.

to_target()¶

Returns a Target instance for an object defined by an alert, as well as any TargetExtra or additional TargetNames.

Returns:: representation of object for an alert
Return type:: Target
Returns:: dict of extras to be added to the new Target
Return type:: dict
Returns:: list of aliases to be added to the new Target
Return type:: list

class tom_alerts.alerts.GenericQueryForm(*args, **kwargs)¶

Form class representing the default form for a broker.

save(query_id=None)¶

Saves the form data in the database as a BrokerQuery.

Returns:: BrokerQuery model representation of the form that was saved to the db
Return type:: BrokerQuery

class tom_alerts.alerts.GenericBroker¶

The GenericBroker provides an interface for implementing a broker module. It contains a number of methods to be implemented, but only the methods decorated with @abstractmethod are required to be implemented. In order to make use of a broker module, add the path to TOM_ALERT_CLASSES in your settings.py.

For an implementation example, please see https://github.com/TOMToolkit/tom_base/blob/main/tom_alerts/brokers/mars.py

abstract fetch_alerts(parameters: dict)¶

This method takes in the query parameters needed to filter alerts for a broker and makes the GET query to the broker endpoint.

Parameters:: parameters (dict) – JSON string of query parameters

fetch_alert(alert_id)¶

This method takes an alert id and retrieves the specific alert data from the given broker.

Parameters:: alert_id (str) – Broker-specific id corresponding with the desired alert

process_reduced_data(target, alert=None)¶

Retrieves and creates records for any reduced data provided by a specific broker. Updates existing data if it has changed.

Parameters:

target (Target) – Target object that was previously created from a BrokerQuery alert
alert (str) – alert data from a particular BrokerQuery

to_target(alert)¶

Creates Target object from the broker-specific alert data.

Parameters:: alert (str) – alert data from a particular BrokerQuery

submit_upstream_alert(target=None, observation_record=None, **kwargs)¶

Submits an alert upstream back to the broker. At least one of a target or an observation record must be provided.

Parameters:

target (Target) – Target object to be converted to an alert and submitted upstream
observation_record (ObservationRecord) – ObservationRecord object to be converted to an alert and submitted upstream

Returns:

True or False depending on success of message submission

Return type:

bool

abstract to_generic_alert(alert)¶

This method creates a GenericAlert object from the broker-specific alert data for use outside the implementation of the GenericBroker.

Parameters:: alert (str) – alert data from a particular BrokerQuery

fetch_and_save_all(parameters)¶

Gets all alerts using a particular BrokerQuery and creates a Target from each one.

Parameters:: parameters (str) – JSON string of query parameters
Returns:: list of Target objects
Return type:: list

get_broker_context_data(*args, **kwargs)¶: Override this method in the subclass to allow the Broker to add additional context data to the View. This method will be called by views.RunQueryView.get_context_data() and the returned dictionary will be added to the View’s context.

ALeRCE¶

class tom_alerts.brokers.alerce.ALeRCEBroker¶

The ALeRCEBroker is the interface to the ALeRCE alert broker.

To include the ALeRCEBroker in your TOM, add the broker module location to your TOM_ALERT_CLASSES list in your settings.py:

TOM_ALERT_CLASSES = [
    'tom_alerts.brokers.alerce.ALeRCEBroker',
    ...
]

For information regarding the ALeRCE objects and classification, please see http://alerce.science.

fetch_alerts(parameters)¶: Loop through pages of ALeRCE alerts until we reach the maximum pages requested. This simply concatenates all alerts from n pages into a single iterable to be returned.

fetch_alert(alert_id)¶

The response for a single alert is as follows:

{
    'oid':'ZTF20acnsdjd',
    ...
    'firstmjd':59149.1119328998,
    ...
}

ANTARES¶

class tom_alerts.brokers.antares.ANTARESBroker¶

In order to install the Antares Broker plugin, please see these instructions at https://github.com/TOMToolkit/tom_antares.

There is a known compatibility issue with antares-client required for the TOM_Antares Broker. The antares-client requires the librdkafka library to be installed in order to be compatible with Python 3.10. You can learn more about this on the antares-client website (https://nsf-noirlab.gitlab.io/csdc/antares/client/installation.html) .

Fink¶

class tom_alerts.brokers.fink.FinkBroker¶: In order to install the full plugin, please see the instructions at https://github.com/TOMToolkit/tom_fink.

GAIA¶

class tom_alerts.brokers.gaia.GaiaBroker¶

The GaiaBroker is the interface to the Gaia alert broker.

To include the GaiaBroker in your TOM, add the broker module location to your TOM_ALERT_CLASSES list in your settings.py:

TOM_ALERT_CLASSES = [
    'tom_alerts.brokers.gaia.GaiaBroker',
    ...
]

For information regarding the Gaia Science Alerts Project, please see http://gsaweb.ast.cam.ac.uk/alerts/about.

fetch_alerts(parameters)¶: Must return an iterator

Lasair¶

tom_alerts.brokers.lasair.get_lasair_object(obj)¶: Parse lasair object table

class tom_alerts.brokers.lasair.LasairBroker¶

The LasairBroker is the interface to the Lasair alert broker.

To include the LasairBroker in your TOM, add the broker module location to your TOM_ALERT_CLASSES list in your settings.py:

TOM_ALERT_CLASSES = [
    'tom_alerts.brokers.lasair.LasairBroker',
    ...
]

Requires a LASAIR[‘api_key’] value in the BROKERS dictionary in your settings.py.

Create an account at https://lasair-ztf.lsst.ac.uk/, log in, and check your profile page for your API token. Add the api key to your settings.py file as follows, storing the token in an environment variable for security:

BROKERS = {
    'LASAIR': {
        'api_key': os.getenv('LASAIR_API_KEY', ''),
    },
    ...
}

For information regarding the query format for Lasair, please see https://lasair.readthedocs.io/en/main/core_functions/rest-api.html#.

Hermes¶

class tom_alerts.brokers.hermes.HermesBroker¶: In order to install the full plugin, please see the instructions at https://github.com/TOMToolkit/tom_hermes.

Transient Name Server¶

class tom_alerts.brokers.tns.TNSBroker¶

The TNSBroker is the interface to the Transient Name Server. For information regarding the TNS, please see https://www.wis-tns.org/

To include the TNSBroker in your TOM, add the broker module location to your TOM_ALERT_CLASSES list in your settings.py:

TOM_ALERT_CLASSES = [
    'tom_alerts.brokers.tns.TNSBroker',
    ...
]

Requires the following configuration in settings.py:

BROKERS = {
    'TNS': {
        'api_key': os.getenv('TNS_API_KEY', 'DO NOT COMMIT API TOKENS TO GIT!'),
        'bot_id': os.getenv('TNS_BOT_ID ', 'My TNS Bot ID'),
        'bot_name': os.getenv('TNS_BOT_NAME', 'BestTOMBot'),
        'tns_base_url': 'https://sandbox.wis-tns.org/api',  # Note this is the Sandbox URL
        'group_name': os.getenv('TNS_GROUP_NAME', 'BestTOMGroup'),
    },
}

classmethod fetch_tns_transients(parameters)¶

Args:

parameters: dictionary containing days_ago (str), min_date (str) and either:

Right Ascention, declination (can be deg, deg or h:m:s, d:m:s) of the target,

and search radius and search radius unit (“arcmin”, “arcsec”, or “deg”), or - TNS name without the prefix (eg. 2024aa instead of AT2024aa)