Photometry Classification Webservice

The service classifies objects based on their photometric observations in different passbands into gravitational microlensing candidates or other objects. Number of classes depends on the number of measurements found in different catalogs.

Methodology

For the methods of classifications please refer to and/or cite the paper:

Early recognition of Microlensing Events from Archival Photometry with Machine Learning Methods https://arxiv.org/abs/2201.12209

API requests

You can post requests with objects to be classified using the webservice url.

POST /classify/

Request body example:

{
  "coordinates": [
    [1.0, 1.0],
    [2.0, 2.0]
  ]
} 

Response body:

If all is correct, you will receive the status 200 and the following body (example data):

{
    "message": "Success",
    "payload": {
        "results": [
            {
                "best_class": "Red Giant",
                "best_class_confidence": 0.968,
                "classifier": 3,
                "dec": "1.0",
                "predictions": [
                    [
                        "Be Star",
                        0.0
                    ],
                    [
                        "Evolved",
                        0.024
                    ],
                    [
                        "Red Giant",
                        0.968
                    ],
                    [
                        "Main Sequence Star",
                        0.006
                    ],
                    [
                        "YSO",
                        0.002
                    ]
                ],
                "ra": "1.0"
            }
        ]
    }
}

In case of problems, the payload is going to be an empty dictionary and the proper message and status code other than 200 is returned. Example status codes are 400 for a badly formatted request and 503 for unavailable service.

Example: for badly formatted request:

{
    "coordinates": [[1.0, -90.0], ["m", 1.0]]
}

you will receive a status code 400 and a response:

{
    "message": "Invalid coordinates format for ['m', 1.0] (line #1): required is [[ra1, dec1], [ra2, dec2], ...] in ra as angles in [0, 360] and dec as angles in [-90, 90]).",
    "payload": {}
}

An example of accessing the payload results using the Python function:

response = ...

# Check if everything is fine with the response -- 200 will be returned in case of no errors.
if response.status_code == 200:
    # This way, even in case of no payload, an empty dictionary will be returned and no exception raised,
    # so the code won't break.
    # Mind you though, you might want to validate whether any results were returned (e.g. by checking if the key "results"
    # is present in the payload dict)
    results = response.json().get('payload', {}).get('results', {})

Example request and response

Request:

{
    "coordinates": [
        [
            205.88283,
            -58.45681
        ]
    ]
}

Response:

{   "message": "Success",
    "payload": {
        "results": [
            {
                "best_class": "Not Ulens",
                "best_class_confidence": 0.51,
                "classifier": 1,
                "dec": "-58.45681",
                "predictions": [
                    [
                        "Ulens Candidate",
                        0.49
                    ],
                    [
                        "Not Ulens",
                        0.51
                    ]
                ],
                "ra": "205.88283"
            }
        ]
    }
}

Code examples

Python

Query for a list of coordinates (remember about the correct format!)

import requests
from requests.structures import CaseInsensitiveDict
from typing import Any, Dict, List

WEBSERVICE_URL: str = "https://photometry-classification.herokuapp.com/classify"
coordinates: List[List[float]] = [[1.0, 1.0], [2.0, 2.0]] # some example random coordinates...

# We need to add the header about the payload format
headers: CaseInsensitiveDict = CaseInsensitiveDict()
headers["Content-Type"] = "application/json"

response: requests.Response = requests.post(WEBSERVICE_URL,
                                            headers=headers,
                                            json={"coordinates": coordinates})

# If all goes well, the response can be extracted! Find out more in the Response section.
if response.status_code == 200:
    results: List[Dict[str, Any]] = response.json().get('payload', {}).get('results', {})
    
    # Here, you can iterate through the results and process them however your heart desires

cURL

curl -X POST https://photometry-classification.herokuapp.com/classify -H 'Content-Type: application/json' -d '{"coordinates":[[1.0, 1.0], [2.0, 2.0]]}'

Webservice

https://photometry-classification.herokuapp.com/