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. 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

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. For information regarding the query format for Lasair, please see https://lasair-ztf.lsst.ac.uk/.

Requires a LASAIR_TOKEN in settings.py. See https://lasair-ztf.lsst.ac.uk/api for details about how to acquire an authorization token.

Hermes

Scout

class tom_alerts.brokers.scout.ScoutBroker

The ScoutBroker is the interface to the Scout alert broker. For information regarding the Scout Broker, please see https://cneos.jpl.nasa.gov/scout/intro.html, as well as https://ssd-api.jpl.nasa.gov/doc/scout.html.

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/

Requires the following configuration in settings.py:

BROKERS = {
    'TNS': {
        'api_key': 'YOUR_API_KEY',
        'bot_id': 'YOUR_BOT_ID',
        'bot_name': 'YOUR_BOT_NAME',
        'tns_base_url': 'https://sandbox.wis-tns.org/api',  # Note this is the Sandbox URL
        'group_name': 'YOUR_GROUP_NAME',
    },
}