MARS Help

Welcome to MARS, which aims to Make Alerts Really Simple. MARS provides a browser and API based interface to the public ZTF alert stream and an archive of all previously released public alerts.

MARS allows users to inspect alerts over any period of time and to apply filters on alerts that restrict the alerts shown to a subset that is of interest for any science case. Selected alerts can then be downloaded in their entireties.

Using the MARS web interface

The main page of the MARS interface consists of a list of selection criteria and a table of alerts. By default the table lists the 100 most recent public alerts from ZTF with no filters applied. Earlier results can be viewed by using the prev/next links. To narrow down the results shown, for example by date, use the filters on the left.

To apply filters simply enter the desired value into each corresponding field on the filter list and click "select". Some fields are range selections, some upper or lower bounds, and some are simple matches. For example, to show alerts with a Real/Bogus score greater or equal to 0.8, you would place "0.8" in the field marked "rb >=" and click "select".

Viewing details of a single alert

Clicking on the id of an alert in the main table will bring you to that alert’s detail page. Here you can download the original .avro file, view the detection triplet, lightcurve, and the data provided by the avro.

The three cutouts are taken from the .avro file and display the 1x1 arcmin area surrounding the alert. They are displayed using JS9, which is a web based version of DS9. You can access the menu of JS9 functions (such as scaling and analysis) by clicking "toggle JS9 menus".

Using the JSON API

JSON (Javascript Object Notation) is a widely used data serialization format. Most programming languages provide functions for reading and writing it, which makes it ideal for use in web services. Both the table and detail view can be viewed in JSON form by adding the URL parameter ?format=json. For example, to view the JSON list of alerts with a Real/Bogus score >= 0.8, you would use the following url:

https://mars.lco.global/?rb__gte=0.8&format=json

Alerts will be located within the results key. The other parameters, has_next, has_prev, pages and total are informative keys that should help you paginate through results should your query return greater than 100 alerts.

Similarly, a single alert can also be viewed in JSON form:

https://mars.lco.global/4157148/?format=json

The id part of the URL comes from the "lco_id" key contained in the alert JSON.

Querying the JSON API in bulk

With a POST query, you can submit multiple queries simultaneously, rather than leveraging the GET endpoint multiple times. To do so, simple use the base MARS url:

https://mars.lco.global/

And include a list of queries in the JSON in the POST body:

      
        {
          "queries": [
            {
              "id": 1,
              "cone": "242.3456,-5.3456,0.0007"
            },
            {
              "id": 2,
              "ra_gt": 242.34,
              "ra_lt": 242.35
            }
          ]
        }
      
      

The API will return the original query information in the response to differentiate queries. It will also ignore any unsupported parameters, so you can use this to your advantage by including fields such as unique IDs (as shown above) or names of queries, which you can parse later in the response.

The POST endpoint supports the same filters as are available on the basic GET endpoint.

Working with avro files

ZTF uses the Apache avro data serialization format to distribute alerts. You can access the raw .avro files from MARS by using the web interface or following the avro link in the json views.

ZTF provides a repo containing example scripts and ipython notebooks for working with these files.

Column Descriptions

  • id: Unique ID for this alert, assigned by LCO. lco_id in json view.
  • objectId: Unique identifier for this object.
  • time: Observation time at start of exposure [UTC]
  • filter: (derived) Filter name (g, r, i) derived from fid (1, 2, 3).
  • ra: Right Ascension of candidate; J2000 [deg]
  • dec: Declination of candidate; J2000 [deg]
  • magpsf: Magnitude from PSF-fit photometry measured from difference image [mag]
  • magap: Aperture mag using 8 pixel diameter aperture measured from difference image [mag]
  • distnr: Distance to nearest source in reference image PSF-catalog within 30 arcsec (1 pixel = 1.0 arcsecond) [pixels]
  • deltamaglatest: (Derived) magpsf[this alert] - magpsf[last alert at this location from image of same filter] if a previous alert is available, otherwise Null.
  • deltamagref: (Derived) If distnr < 2" (~2 ZTF pixels), deltamagref = (magnr - magpsf), otherwise Null.
  • rb: RealBogus quality score; range is 0 to 1 where closer to 1 is more reliable.
  • classtar: Star/Galaxy classification score from SExtractor measured from the difference image.

Filter descriptions

Most filters correspond to columns displayed in the main table, with the exception of the following:

  • time since Filter alerts that have occured within the given number of seconds.
  • jd: Filter alerts by JD instead of gregorian date.
  • candid: The value of the candid field of the alert. Exact match.
  • Cone Search: Returns results contained within the radius of a given point, in degrees. For example: 43.2,-30.2,0.2. The format is ra,dec,radius in degrees.
  • Cone Search (Object): Returns results contained within the radius of a given point, obtained via looking up an object name with Simbad2k. For example: m51,5
  • Nearby Objects: Each alert contains the names of the 3 closest objects from the Panstarrs-1 catalog. Filtering on a PS1 object id will return alerts for which this object is listed as close by.
  • Classtar: Return alerts where the The Star/Galaxy classification score from SExtractor is within the provided bounds. Measured from the difference image, not the reference.
  • Fwhm: Return alerts where the FWHM is less than or equal to the given value. Measured from the difference image, not the reference. [pixels]

Acknowledgement of Use

Any scientific publication which results from the use of this resource should include an acknowledgment of MARS as well as the LCOGT organization. Note that we advocate the use of LCOGT as our acronym in scientific publications to avoid confusion with Las Campanas Observatory. If appropriate you may also consider citing our paper which defines the goals, capabilities and research interests of LCO.