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.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(id)

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

Parameters

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

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_alert(id)

The response for a single alert is as follows:

{

‘oid’:’ZTF20acnsdjd’, … ‘firstmjd’:59149.1119328998, …

}

ANTARES

Lasair

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.roe.ac.uk/objlist/.

MARS

class tom_alerts.brokers.mars.MARSBroker

The MARSBroker is the interface to the MARS alert broker. For information regarding MARS and its available filters for querying, please see https://mars.lco.global/help/.

SCIMMA

class tom_scimma.scimma.SCIMMABroker

This is a prototype interface to the skip db built by SCIMMA

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

Submits target and observation record as Hopskotch alerts.

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

  • **kwargs – See below

Keyword Arguments

  • topic (str): Hopskotch topic to submit the alert to.

Returns

True or False depending on success of message submission

Return type

bool

Raises
AlertSubmissionException: If topic is not provided to the function and a default is not provided in

settings

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/