atlasapiclient

ATLAS API Client

Who/what is this code for?

This package allows authorised users of the ATLAS Transient web server to query the server without being exposed to regular or code breaking changes to the underlying API. In particular we have in mind bots and other automated services.

It also allows users the make routine queries in a friendlier way, such as:

• doing a Cone Search
• check out the data in your custom list

How to get access?

The ATLAS Transient web server is our production server for the survey, and we cannot give unlimited access to manage the load on our machines.

Anyone with legitimate scientific interests can apply for access by submitting a 1-page max science case to the Data Request Form, justifying your access needs (length of time and whether you need Write access - you probably do not).

The ATLAS team will review requests at least once a month on the first Friday. If you require urgent access email [e-mail] with the subject line after submitting the form: "Urgent ATLAS access request - [Proposal Title]". The [Proposal Title] should be the same as the one submitted in the form.

Once you have been granted access you will receive an email with your username and a one-time use password which you will have to change on your first login.

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()

Help I forgot my password!

The server doesn't store your email address so it can't send you an email to reset the password. If you forget it for good, you will need to email [e-mail] of [e-mail]. We will then use our admin super powers to reset your password to a one-time use password which you will then be able to reset.

Docs

There is a full docs page where you can see some more verbose tutorials with pictures. Here is a little cheat sheet with just some code.

Install and config

Pypi

pip install --user atlasapiclient

Clone Github

git clone [e-mail]:HeloiseS/atlasapiclient.git

Configuration

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.

• Copy it in the same directory to a file named api_config_MINE.yaml. YES - THE NAME MATTERS

cd atlasapiclient/config_files
cp api_config_template.yaml api_config_MINE.yaml

• Update your token (if you don't have a token see below)
• Update the url to "https://psweb.mp.qub.ac.uk/sne/atlas4/api/"

Cheat sheet

Cone Search

from atlasapiclient import client as atlaspaiclient

client = atlaspaiclient.ConeSearch(payload={'ra': 150,
                                            'dec': 60,
                                            'radius': 60,
                                            'requestType': 'nearest'},
                                            get_response=True)

Data for a Single Object

To get the data:

from atlasapiclient import client as atlaspaiclient

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

To extract the light curve data from the JSON:

import pandas as pd 

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

To make a neat plot:

import matplotlib.pyplot as plt

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()

Data for Multiple Objects

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.

Housekeeping

Privacy Policy

As ATLAS users your first name and last name will be stored on our server. Your email address will be stored on a Google Drive spreadsheet alongside the information provided with your Data Access Request Form. We store this data because it is required to provide you access to this service and we will only store it as long as needed to provide this service. The ATLAS user list will be reviewed twice a year: In November and in May. If your Data Access Request is out of date, or if you have not logged into the server since the last review, we will email you with a two-week deletion warning. If we receive no response, your profile will be deleted and your access revoked. If you would like us to delete your data sooner, send an email to [e-mail] and we will remove your account and associated data.

Who can see my data?: All users of the server can see your name.surname when you comment. Your email is stored in a private Google Drive spreadsheet that only a couple of project administrators can access.

We will never share your data with third parties

Community Guidelines

Reporting issues

Feel free to report any API bugs or missing features by opening an Issue on this repo.

Seeking support

If you have questions that do not fit in an issue (or we are taking too long to reply) you can email [e-mail]

Contributing

If you would like to contribute to this project you are welcome to fork and open a pull request however we strongly recommend asking the dev team (via [e-mail]) before you start putting in some work. It's possible that changes you want to make would require other changes in our telescope pipelines and if we do not have the resources to refactor those codes, or if your changes are incompatible with our other pipelines, we may have to deny what could look like a very sensible PR.

If there are good first issues we will flag them clearly.

Citing this code

Software in science needs recognition so we can keep funding and human resources allocated. Please cite this DOI in your TNS reports and papers if you used our code, and thank you!

.. image:: https://zenodo.org/badge/804295497.svg :target: https://doi.org/10.5281/zenodo.14331062