ZTF Access¶

The ALeRCE ZTF API Wrapper gives an easy access to our database through the ALeRCE ZTF API service with Python.

Usage¶

from alerce.core import Alerce
alerce = Alerce()

dataframe = alerce.query_objects()

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

Query objects¶

We will use the query_objects() method, this method will query the ALeRCE ZTF 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, a list of valid arguments can be found in the query_objects() API reference page.

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

dataframe = alerce.query_objects(
    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(**params)

Getting Classifier List¶

In ALeRCE we will have multiple classifiers and each classifier will have a list of classes, also called Taxonomy.

For some filters we want to check an 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 retreive information of only those objects. You can even apply filters over that list if you wanted to.

oids = [
    "ZTF18accqogs",
    "ZTF19aakyhxi",
    "ZTF19abyylzv",
    "ZTF19acyfpno",
]
objects = alerce.query_objects(oid=oids, 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 separetly with query_detections() and query_non_detections().

# Getting detections for an object
detections = alerce.query_detections("ZTF18abbuksn",
                                     format="json")

# Getting non detections for an object
non_detections = alerce.query_non_detections("ZTF18abbuksn",
                                             format="json")

# Getting lightcurve for an object
lightcurve = alerce.query_lightcurve("ZTF18abbuksn",
                                     format="json")

Query Probabilities¶

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

# Getting detections for an object
probabilities = alerce.query_probabilities("ZTF18abbuksn")

Other Queries¶

There are other more specific queries, to get more information from an object.

To get the features used by the Light Curve Classifier , we can use query_features() or query_feature() for a single one.

(Check P. Sánchez-Sáez, et al. 2020 for more information on each feature)

# Getting all the features for an object as a dataframe
features = alerce.query_features("ZTF18abbuksn", format="pandas")

# Getting multiband period for an object
mb_period = alerce.query_feature("ZTF18abbuksn", "Multiband_period")

For each filter ALeRCE calculate some statistics for an object, we can get them with query_magstats()

# Getting magstats for an object
magstats = alerce.query_magstats("ZTF18abbuksn")

Error Handling¶

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

ZTFAPIError (code -1): this is the default error
ParseError (code 400): this error is raised when there’s an error with search parameters
ObjectNotFoundError (code 404): this error is raised when no objects were returned in your query
FormatValidationError (code 500): this error is raised when you set a not allowed return format

This 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(**my_filters)
except ObjectNotFoundError as e:
    print(e.message)
    # do something else