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',
    },
}