Set-up

Set-up#

First you need to install the package, you can either use pip

pip install --user atlasapiclient

or clone the repository from github:

git clone git@github.com:HeloiseS/atlasapiclient.git

Config file#

The client requires a config ile that contains the base url of the ATLAS transient web servers and your token for the ATLAS API. In the directory atlasapiclient/config_files you will find the api_config_template.yaml file.

    1. Copy it in the same directory to a file named api_config_MINE.yaml.

cd atlasapiclient/config_files
cp api_config_template.yaml api_config_MINE.yaml

Warning

The name of that file matters immensly. Unless you know what you’re doing DON’T CHANGE IT

How do I get a token?#

Once you have access to the web server you can get a token for API access by using the APIClient.refresh_token() method. This will generate a token for you and save it in the config file defined within the API_CONFIG_FILE variable in the atlasapiclient/utils.py file. For example:

from atlasapiclient import client as atlaspaiclient

client = atlaspaiclient.APIClient()
client.refresh_token()

This will work for any of the clients included in atlasapiclient.client. If your token is expired you can use the same method to refresh it.

Quick Recipes#

Data for a Single Object#

Get the data#

from atlasapiclient import client as atlaspaiclient

atlas_id = '1161600211221604900'
client = atlaspaiclient.RequestSingleSourceData(atlas_id=atlas_id, get_response=True)

Note: Here we don’t parse the config file because we assume you have named yours api_config_MINE.yaml. The path to that file is encoded in the API_CONFIG_FILE variable in the atlasapiclient/utils.py file and parsed by default to the classes.

If you feel fancy and want to name your config file differently you have to keep track of its location and parse it with the argument api_config_file.

Extract the Lightcurve from the JSON#

Your data can be found in the client.response_data attribute. Note that it is a list so if you only have one object you want to do client.response_data[0] to get the JSON data.

detections = pd.DataFrame(client.response_data[0]['lc'])
non_dets = pd.DataFrame(client.response_data[0]['lcnondets'])

Make a Neat Plot#

mjd_min, mjd_max= 58277, 58327

filter_colors = {'c': 'blue', 'o': 'orange'}

fig, ax = plt.subplots()

# Plot detections, colored by filter
for f in ['c', 'o']:
    df = detections[detections['filter'] == f]
    ax.scatter(df.mjd, df.mag, color=filter_colors[f], label=f'filter {f}')

# Plot non-detections with down arrows and lower alpha
for f in ['c', 'o']:
    df = non_dets[non_dets['filter'] == f]
    ax.scatter(
        df.mjd, df.mag5sig,
        color=filter_colors[f],
        alpha=0.3,
        marker='v',  # down arrow
        label=f'non-det {f}'
    )

ax.set_xlim(mjd_min, mjd_max)
ax.set_ylim(20, 13)
ax.set_xlabel('MJD')
ax.set_ylabel('Magnitude')
ax.legend()
AT2018cow lightcurve

AT 2018 cow lightcurve#

Get Data for Multiple objects#

If you want to query the ATLAS API for multiple objects you’re going to encounter the rate limit, which is 100 per query. To handle this, there is a class to chunk stuff for you:

from atlasapiclient import client as atlaspaiclient

client = RequestMultipleSourceData(atlas_ids=YOUR_LIST_OF_IDS, mjdthreshold = LOWER_MJD_THRESHOLD)
client.chunk_get_response() # Chunks the list of IDs into a bunch of payloads and colates the responses.

You can then get the data just as you would for a single object.

Data Structure and other bits of data#

The ATLAS API gives you back everything (or nearly). You can check out the json `schema`_ if you want to navigate the key structure and what they mean. If anything is not clear please add an issue to the GH. Here is a couple of handy recipes…

Getting the Sherlock crossmatches#

The first crossmatch (if any) is a merged entry which cherry picks the best information from all catalogues (so if a galaxy has info in 3 catalogues it will be cross matched 3 times and the info from these catalogues will appear as separate entries in our list of dictionaries - the first entry in the list will be the combination of all the best info in those 3 entries) The following entries are the individual crossmatches.

summary_crossmatch = client.response_data[0]['sherlock_crossmatches'][0]

Is that ATLAS_ID object in TNS?#

You can check the crossmatches using:

client.response_data[0]['tns_crossmatches']
Contents