Multi Survey Access

The ALeRCE Multi Survey API Wrapper gives an easy access to our database through the ALeRCE Multi Survey API service with Python. This API allows you to search between ZTF and LSST surveys by specifying the survey parameter.

Usage

from alerce.core import Alerce
alerce = Alerce()

# Query objects from ZTF survey
dataframe = alerce.query_objects(survey="ztf")

# Query objects from LSST survey
dataframe = alerce.query_objects(survey="lsst")

The dataframe will have several columns, the output specification can be found in Object Response

Supported Surveys

The Multi Survey API currently supports the following surveys:

ztf: Zwicky Transient Facility
lsst: Legacy Survey of Space and Time

You must specify one of these surveys in your queries using the survey parameter.

Query objects

We will use the query_objects() method, this method will query the ALeRCE Multi Survey API and get a page of results, each result has some statistics of the object and a classification.

The filters are passed as arguments to the method, including the required survey parameter. A list of valid arguments can be found in the query_objects() API reference page.

For example, getting all the objects classified as LPV from ZTF could be done like this:

dataframe = alerce.query_objects(
    survey="ztf",
    classifier="lc_classifier",
    class_name="LPV",
    format="pandas"
)

For LSST objects:

dataframe = alerce.query_objects(
    survey="lsst",
    classifier="lc_classifier",
    class_name="LPV",
    format="pandas"
)

You can specify one of the following return formats: pandas | votable | json with json being the default.

Note

If you like to have parameters inside a dict for example that you can reuse later you can do the following:

params = {
   "classifier": "stamp_classifier",
   "class_name": "SN",
   "probability": 0.7
}
objects = alerce.query_objects(survey="ztf", **params)

Getting Single Object

To get information about a single object, use the query_object() method:

# Get single object from ZTF
object_info = alerce.query_object(
    oid="ZTF18abbuksn",
    survey="ztf",
    format="json"
)

# Get single object from LSST
object_info = alerce.query_object(
    oid="45121627560013194",
    survey="lsst",
    format="json"
)

Getting Classifier List

In ALeRCE we will have multiple classifiers and each classifier will have a list of classes, also called Taxonomy. Note that classifier availability may vary between surveys.

For some filters we want to check a specific classifier, to list the current classifiers available we can use the query_classifiers() method.

# Getting list of classifiers
classifiers = alerce.query_classifiers()

The classifier_name field should be used as a filter in query_objects() method, also if the classifier_name and version is already known we can request the list of possible classes with query_classes()

# Getting classes for a classifier and version
classes = alerce.query_classes("lc_classifier",
                               "hierarchical_random_forest_1.0.0")

Querying a known list of objects

You can pass query_objects() a list of object ids to retrieve information of only those objects. You can even apply filters over that list if you wanted to. Remember to specify the survey parameter.

# ZTF
oids = [
    "ZTF18accqogs",
    "ZTF19aakyhxi",
    "ZTF19abyylzv",
    "ZTF19acyfpno",
]
objects = alerce.query_objects(
    oid=oids,
    survey="ztf",
    format="pandas"
)

# LSST
oids = [
    "45121627560013194",
    "45121627560603538",
    "45121627559904665",
    "45121627560013211",
]
objects = alerce.query_objects(
    oid=oids,
    survey="lsst",
    format="pandas"
)

Query Lightcurve

To get the lightcurve for an object the method query_lightcurve() can be used, this will return a dictionary with Detections and Non-detections for that object, also we can get them separately with query_detections() and query_non_detections(). Also, there is a method to access the forced photometries of an object query_forced_photometry().

# Getting detections for an object from LSST
detections = alerce.query_detections(
    oid="45121627560013211",
    survey="lsst",
    format="json"
)

# Getting non detections for an object from LSST
non_detections = alerce.query_non_detections(
    oid="45121627560013211",
    survey="lsst",
    format="json"
)

# Getting forced photometry for an object from LSST
forced_photometry = alerce.query_forced_photometry(
    oid="45121627560013211",
    survey="lsst",
    format="json"
)

# Getting lightcurve for an object from LSST
lsst_lightcurve = alerce.query_lightcurve(
    oid="45121627560013211",
    survey="lsst",
    format="json"
)

# Example with ZTF object
lightcurve = alerce.query_lightcurve(
    oid="ZTF18abbuksn",
    survey="ztf",
    format="json"
)

Query Magstats

To get the magstats for an object using the different classifiers implemented by ALeRCE we will use query_magstats()

# Getting magstats for a ztf object
ztf_magstats = alerce.query_magstats(
  survey="ztf",
  oid="ZTF18abbuksn",
  )

# Getting magstats for a lsst object
lsst_magstats = alerce.query_magstats(
  survey="lsst",
  oid="45121627560013211"
  )

Query Probability

To get the probabilities for an object using the different classifiers implemented by ALeRCE we will use query_probabilities()

# Getting probabilities for a ztf object
ztf_probabilities = alerce.query_probabilities(
  survey="ztf",
  classifier="LC_classifier_BHRF_forced_phot",
  oid="ZTF18abbuksn"
  )

# Getting probabilities for a lsst object
lsst_probabilities = alerce.query_probabilities(
  survey="lsst",
  classifier="lc_classifier_lsst",
  oid="45121627560013211"
  )

Query Features

In development

Migration from ZTF API

If you are migrating from the ZTF-only API, the main change is that you now need to explicitly specify the survey parameter in your method calls.

Method Names

The method names remain the same:

query_objects() - Now requires survey parameter
query_object() - Now requires survey parameter
query_lightcurve() - Now requires survey parameter
query_detections() - Now requires survey parameter
query_non_detections() - Now requires survey parameter
query_forced_photometry() - Now requires survey parameter
query_magstats() - Now requires survey parameter
query_probabilities() - Now requires survey parameter

Required Survey Parameter

All methods now require a survey parameter to specify which survey you’re querying:

# Old ZTF API (deprecated - will show warning)
objects = alerce.query_objects(class_name="SN")

# New Multi Survey API (recommended)
objects = alerce.query_objects(survey="ztf", class_name="SN")

Parameter Changes

New required parameter: Add survey="ztf" or survey="lsst" to all method calls
Object ID formats vary by survey: - ZTF: "ZTF18abbuksn" (string format) - LSST: 45121627560013211 (numeric format)

Error Handling

The ALeRCE Multi Survey Client has useful error messages that you can manage when something goes wrong. If you specify a wrong search criteria, invalid survey, or no objects were found with your query, then you will get one of the following errors:

ValueError: Raised when survey is not in valid surveys (ztf, lsst)
ParseError (code 400): Raised when there’s an error with search parameters
ObjectNotFoundError (code 404): Raised when no objects were returned in your query
FormatValidationError (code 500): Raised when you set a not allowed return format

These errors usually give useful data on what you need to fix with your query. In case you want to do something when an error happens you can capture the error as a regular python exception handling.

try:
    data = alerce.query_objects(survey="ztf", **my_filters)
except ValueError as e:
    if "survey must be one of" in str(e):
        print("Invalid survey specified. Use 'ztf' or 'lsst'")
    else:
        print(f"Error: {e}")
    # do something else

Valid Survey Check

The Multi Survey API validates that you specify a valid survey. The valid surveys are:

VALID_SURVEYS = ["lsst", "ztf"]

If you specify an invalid survey, you’ll get a ValueError:

# This will raise a ValueError
try:
    objects = alerce.query_objects(survey="invalid_survey")
except ValueError as e:
    print(e)  # survey must be one of ['ztf', 'lsst']

Complete Example

Here’s a complete example showing how to use the Multi Survey API:

from alerce.core import Alerce

# Initialize the client
alerce = Alerce()

# Query objects from ZTF
ztf_objects = alerce.query_objects(
    survey="ztf",
    classifier="lc_classifier",
    class_name="SN",
    probability=0.8,
    format="pandas"
)

# Query objects from LSST
lsst_objects = alerce.query_objects(
    survey="lsst",
    classifier="lc_classifier",
    class_name="SN",
    probability=0.8,
    format="pandas"
)

# Get lightcurve for a specific ZTF object
if len(ztf_objects) > 0:
    oid = ztf_objects.iloc[0]['oid']
    lightcurve = alerce.query_lightcurve(
        oid=oid,
        survey="ztf",
        format="json"
    )

    # Get detections separately
    detections = alerce.query_detections(
        oid=oid,
        survey="ztf",
        format="pandas"
    )