The Locus Object

ANTARES filters are Python classes which must have a function run(self, locus). The single parameter locus, is an instance of a class Locus. It provides access to all data associated with the Locus:

  • Locus Properties

  • Locus Tags

  • Alerts received by ANTARES, and their Properties

  • Catalog Objects

  • WatchObjects and WatchLists which the Locus matches

The Properties page on the Portal documents the datatype and meaning of individual LocusProperties and AlertProperties.

The Locus class is almost identical to the Locus objects returned by the ANTARES Client library, but has some additional methods and properties.

You can also interactively explore the Locus directly using the devkit:

import antares.devkit as dk

ld = dk.get_locus()  # Get some arbitrary Locus
# ld = dk.get_locus(locus_id)  # or get a specific Locus by ID

print(ld)
print(ld.properties)  # Locus Properties
print(ld.alert)  # The most recent Alert on the Locus

help(ld.timeseries)

# etc.

The Locus object spec is as follows.

property Locus.locus_id
property Locus.ra
property Locus.dec
property Locus.properties

Locus properties dict.

Supports setting new Locus properties and overwriting existing ones.

eg:

# Get a Locus Property
band = locus.properties['ant_passband']

# Set a Locus Property
locus.properties['saha_periodicity'] = periodicity

The schema of the Locus Properties is dynamic, in the sense that new properties can be created at any time by the addition of new Filters.

The list of all Locus properties extant in the system is visible at http://antares.noirlab.edu/properties

Returns

dict-like object PropertiesDict

property Locus.tags

List of Tags which Locus currently has.

Returns

list of str

property Locus.alerts

List of all Alerts (including current Alert) on the Locus.

Alerts returned by this function are read-only.

Alerts have attributes:

  • alert_id

  • mjd

  • properties

eg:

alert_ids = [a.alert_id for a in locus.alerts]

brightest_mag = min(a.properties['ant_mag'] for a in locus.alerts]

The schema of the Alert Properties is dynamic, in the sense that new properties can be created at any time by the addition of new Filters.

The list of all Alert properties extant in the system is visible at http://antares.noirlab.edu/properties

Returns

list of Alert

property Locus.alert

Current (ie. most recent) Alert on the Locus.

Supports setting new properties on the Alert, but not overwriting.

alert = locus.alert

is equivalent to:

alert = locus.alerts[-1]

EXCEPT that only the Alert returned by Locus.alert is mutable. For example, you can:

if something:
    locus.alert.properties['narayan_classification'] = 'sn1a'
Returns

Alert

property Locus.lightcurve

An astropy.TimeSeries of select Alert properties on this Locus.

Value contains the same data as the lightcurve CSV object contained in ANTARES’ Kafka output Alerts.

This is a subset of the data returned by timeseries.

property Locus.timeseries

An astropy.TimeSeries of all Alert Properties on this Locus.

In addition to the Alert Properties, two additional columns are included:

  • ant_mag_corrected

  • ant_magerr_corrected

These two columns contain mag/magerr corrected for variable stars.

This TimeSeries object can be easily converted to Pandas or Numpy:

import antares.devkit as dk
dk.init()

# Get a random Locus to play with
locus = dk.get_locus()

# Get an `astropy.TimeSeries` of all properties
ts = locus.timeseries
print(ts)

# The `astropy.TimeSeries` object can be converted
# into many other formats if desired.

# For example, get a `pandas.core.frame.DataFrame`:
df = locus.timeseries.to_pandas()
print(df)

# You can get each column as a separate `pandas.core.series.Series` object:
alert_id = df['alert_id']
passband = df['ant_passband']
print(passband)
# etc.

# If you prefer numpy, you can get the timeseries as a `numpy.ndarray`:
nd = locus.timeseries.to_pandas().to_numpy()
print(nd)

# You can also get individual columns as separate `numpy.ndarray` objects:
ts = locus.timeseries[['alert_id', 'ant_passband']]
alert_id, passband = ts.to_pandas().to_numpy().T
print(alert_id)
print(passband)
property Locus.catalog_objects

Astro catalog objects which match the current Locus.

Returned data structure is of form:

{
    catalog_name_x: [obj_x1, obj_x2, ...],
    catalog_name_y: [obj_y1, ...]
    ...
}

Where obj_* objects are dicts representing rows from the catalog tables.

The schema of each catalog is different. You can use the Devkit to get a sample containing objects from all ANTARES catalogs:

import antares.devkit as dk
data = dk.get_sample_catalog_data()
Returns

dict of lists of dicts

property Locus.watch_list_ids

All WatchList IDs which the Alert matches.

Returns

list of ints

property Locus.watch_object_ids

All WatchObject IDs which the Alert matches.

Returns

list of ints

Locus.tag(name)

Tag the Locus.

Parameters

name – Tag name

Locus.to_dict()

Return a JSON-ready dict representation of the Locus.

Returns

JSON-ready dict

Locus.to_file(filename)

Write a JSON representation of the Locus to file.