Source code for astroquery.oac.core

# Licensed under a 3-clause BSD style license - see LICENSE.rst.
"""
OPEN ASTRONOMY CATALOG (OAC) API TOOL
-------------------------------------
This module allows access to the OAC API and
all available functionality. For more information
see: https://api.astrocats.space.
:authors: Philip S. Cowperthwaite (pcowpert@cfa.harvard.edu)
and James Guillochon (jguillochon@cfa.harvard.edu)
"""


import json
import csv

import astropy.units as u
from astropy.table import Column, Table
from astroquery import log

from . import conf
from ..query import BaseQuery
from ..utils import async_to_sync, commons

__all__ = ['OAC', 'OACClass']


[docs]@async_to_sync class OACClass(BaseQuery): """OAC class.""" URL = conf.server TIMEOUT = conf.timeout HEADERS = {'Content-type': 'application/json', 'Accept': 'text/plain'} FORMAT = None
[docs] def query_object_async(self, event, quantity=None, attribute=None, argument=None, data_format='csv', get_query_payload=False, cache=True): """ Retrieve object(s) asynchronously. Query method to retrieve the desired quantities and attributes for an object specified by a transient name. If no quantities or attributes are given then the query returns the top-level metadata about the event(s). The complete list of available quantities and attributes can be found at https://github.com/astrocatalogs/schema. Parameters ---------- event : str or list, required Name of the event to query. Can be a list of event names. quantity : str or list, optional Name of quantity to retrieve. Can be a list of quantities. The default is None. attribute : str or list, optional Name of specific attributes to retrieve. Can be a list of attributes. The default is None. argument : str or list, optional These are special conditional arguments that can be applied to a query to refine. Examples include: 'band=i' returns only i-band photometry, 'first' returns the first result, 'sortby=attribute' returns a table sorted by the given attribute, and 'complete' returns only those table rows with all of the requested attributes. A complete list of commands and their usage can be found at: https://github.com/astrocatalogs/OACAPI. The default is None. data_format: str, optional Specify the format for the returned data. The default is CSV for easy conversion to Astropy Tables. The user can also specify JSON which will return a JSON-compliant dictionary. Note: Not all queries can support CSV output. get_query_payload : bool, optional When set to `True` the method returns the HTTP request parameters as a dict. The actual HTTP request is not made. The default value is False. Returns ------- result : `~astropy.table.Table` The default result is an `~astropy.table.Table` object. The user can also request a JSON dictionary. """ request_payload = self._args_to_payload(event, quantity, attribute, argument, data_format) if get_query_payload: return request_payload response = self._request('GET', self.URL, data=json.dumps(request_payload), timeout=self.TIMEOUT, headers=self.HEADERS, cache=cache) return response
[docs] def query_region_async(self, coordinates, radius=None, height=None, width=None, quantity=None, attribute=None, argument=None, data_format='csv', get_query_payload=False, cache=True): """ Query a region asynchronously. Query method to retrieve the desired quantities and attributes for an object specified by a region on the sky. The search can be either a cone search (using the radius parameter) or a box search (using the width/height parameters). IMPORTANT: The API can only query a single set of coordinates at a time. The complete list of available quantities and attributes can be found at https://github.com/astrocatalogs/schema. Parameters ---------- coordinates : str or `astropy.coordinates`. A single set of ra/dec coorindates to query. Can be either a list with [ra,dec] or an astropy coordinates object. Can be given in sexigesimal or decimal format. The API can not query multiple sets of coordinates. radius : str, float or `astropy.units.Quantity`, optional The radius, in arcseconds, of the cone search centered on coordinates. Should be a single, float-convertable value or an astropy quantity. The default value is None. width : str, float or `astropy.units.Quantity`, optional The width, in arcseconds, of the box search centered on coordinates. Should be a single, float-convertable value or an astropy quantity. The default value is None. height : str, float or `astropy.units.Quantity`, optional The height, in arcseconds, of the box search centered on coordinates. Should be a single, float-convertable value or an astropy quantity. The default value is None. quantity: str or list, optional Name of quantity to retrieve. Can be a a list of quantities. The default is None. attribute: str or list, optional Name of specific attributes to retrieve. Can be a list of attributes. The default is None. argument : str or list, optional These are special conditional arguments that can be applied to a query to refine. Examples include: 'band=i' returns only i-band photometry, 'first' returns the first result, 'sortby=attribute' returns a table sorted by the given attribute, and 'complete' returns only those table rows with all of the requested attributes. A complete list of commands and their usage can be found at: https://github.com/astrocatalogs/OACAPI. The default is None. data_format: str, optional Specify the format for the returned data. The default is CSV for easy conversion to Astropy Tables. The user can also specify JSON which will return a JSON-compliant dictionary. Note: Not all queries can support CSV output. get_query_payload : bool, optional When set to `True` the method returns the HTTP request parameters as a dict. The actual HTTP request is not made. The default value is False. Returns ------- result : `~astropy.table.Table` The default result is an `~astropy.table.Table` object. The user can also request a JSON dictionary. """ # Default object name used for coordinate-based queries event = 'catalog' request_payload = self._args_to_payload(event, quantity, attribute, argument, data_format) # Check that coordinate object is a valid astropy coordinate object # Criteria/Code from ../sdss/core.py if (not isinstance(coordinates, list) and not isinstance(coordinates, Column) and not (isinstance(coordinates, commons.CoordClasses) and not coordinates.isscalar)): request_payload['ra'] = coordinates.ra.deg request_payload['dec'] = coordinates.dec.deg else: try: request_payload['ra'] = coordinates[0] request_payload['dec'] = coordinates[1] except IndexError: raise IndexError("Please check format of input coordinates.") if ((radius is None) and (height is None) and (width is None)): raise ValueError("Please enter a radius or width/height pair.") if (radius is not None and (height is not None or width is not None)): raise ValueError("Please specify ONLY a radius or " "height/width pair.") if ((radius is None) and ((height is None) or (width is None))): raise ValueError("Please enter both a width and height " "for a box search.") # Check that any values are in the proper format. # Criteria/Code from ../sdss/core.py if radius is not None: if isinstance(radius, u.Quantity): radius = radius.to(u.arcsec).value else: try: float(radius) except TypeError: raise TypeError("radius should be either Quantity or " "convertible to float.") request_payload['radius'] = radius if (width is not None and height is not None): if isinstance(width, u.Quantity): width = width.to(u.arcsec).value else: try: float(width) except TypeError: raise TypeError("width should be either Quantity or " "convertible to float.") if isinstance(height, u.Quantity): height = height.to(u.arcmin).value else: try: float(height) except TypeError: raise TypeError("height should be either Quantity or " "convertible to float.") request_payload['width'] = width request_payload['height'] = height if get_query_payload: return request_payload response = self._request('GET', self.URL, data=json.dumps(request_payload), timeout=self.TIMEOUT, headers=self.HEADERS, cache=cache) return response
[docs] def get_photometry_async(self, event, argument=None, cache=True): """ Retrieve all photometry for specified event(s). This is a version of the query_object method that is set up to quickly return the complete set of light curve(s) for the given event(s). The light curves are returned by default as an Astropy Table. Additional arguments can be specified but more complicated queries should make use of the base query_object method instead of get_photometry. Parameters ---------- event : str or list, required Name of the event to query. Can be a list of event names. argument : str or list, optional These are special conditional arguments that can be applied to a query to refine. Examples include: 'band=i' returns only i-band photometry, 'first' returns the first result, 'sortby=attribute' returns a table sorted by the given attribute, and 'complete' returns only those table rows with all of the requested attributes. A complete list of commands and their usage can be found at: https://github.com/astrocatalogs/OACAPI. The default is None. Returns ------- result : `~astropy.table.Table` The default result is an `~astropy.table.Table` object. The user can also request a JSON dictionary. """ response = self.query_object_async(event=event, quantity='photometry', attribute=['time', 'magnitude', 'e_magnitude', 'band', 'instrument'], argument=argument, cache=cache ) return response
[docs] def get_single_spectrum_async(self, event, time, cache=True): """ Retrieve a single spectrum at a specified time for given event. This is a version of the query_object method that is set up to quickly return a single spectrum at a user-specified time. The time does not have to be precise as the method uses the closest option by default. The spectrum is returned as an astropy table. More complicated queries, or queries requesting multiple spectra, should make use of the base query_object or get_spectra methods. Parameters ---------- event : str, required Name of the event to query. Must be a single event. time : float, required A single MJD time to query. This time does not need to be exact. The closest spectrum will be returned. Returns ------- result : `~astropy.table.Table` The default result is an `~astropy.table.Table` object. The user can also request a JSON dictionary. """ query_time = 'time=%s' % time response = self.query_object_async(event=event, quantity='spectra', attribute=['data'], argument=[query_time, 'closest'], cache=cache ) return response
[docs] def get_spectra_async(self, event, cache=True): """ Retrieve all spectra for a specified event. This is a version of the query_object method that is set up to quickly return all available spectra for a single event. The spectra must be returned as a JSON-compliant dictionary. Multiple spectra can not be unwrapped into a csv/Table. More complicated queries should make use of the base query_object methods. Parameters ---------- event : str, required Name of the event to query. Can be a single event or a list of events. Returns ------- result : dict The default result is a JSON dictionary. An `~astropy.table.Table` can not be returned. """ response = self.query_object_async(event=event, quantity='spectra', attribute=['time', 'data'], data_format='json', cache=cache ) return response
def _args_to_payload(self, event, quantity, attribute, argument, data_format): request_payload = dict() if (event) and (not isinstance(event, list)): event = [event] if (quantity) and (not isinstance(quantity, list)): quantity = [quantity] if (attribute) and (not isinstance(attribute, list)): attribute = [attribute] if (argument) and (not isinstance(argument, list)): argument = [argument] request_payload['event'] = event request_payload['quantity'] = quantity request_payload['attribute'] = attribute if argument: if 'format' in argument: raise KeyError("Please specify the output format using the " "data_format function argument") if 'radius' in argument: raise KeyError("A search radius should be specified " "explicitly using the query_region method.") if 'width' in argument: raise KeyError("A search width should be specified " "explicitly using the query_region method.") if 'height' in argument: raise KeyError("A search height should be specified " "explicitly using the query_region method.") for arg in argument: if '=' in arg: split_arg = arg.split('=') request_payload[split_arg[0]] = split_arg[1] else: request_payload[arg] = True if ((data_format.lower() == 'csv') or (data_format.lower() == 'json')): request_payload['format'] = data_format.lower() else: raise ValueError("The format must be either csv or JSON.") self.FORMAT = data_format.lower() return request_payload def _format_output(self, raw_output): if self.FORMAT == 'csv': split_output = raw_output.splitlines() columns = list(csv.reader([split_output[0]], delimiter=',', quotechar='"'))[0] rows = split_output[1:] # Quick test to see if API returned a valid csv file # If not, try to return JSON-compliant dictionary. test_row = list(csv.reader([rows[0]], delimiter=',', quotechar='"'))[0] if (len(columns) != len(test_row)): log.info("The API did not return a valid CSV output! \n" "Outputing JSON-compliant dictionary instead.") output = json.loads(raw_output) return output # Initialize and populate dictionary output_dict = {key: [] for key in columns} for row in rows: split_row = list(csv.reader([row], delimiter=',', quotechar='"'))[0] for ct, key in enumerate(columns): output_dict[key].append(split_row[ct]) # Convert dictionary to Astropy Table. output = Table(output_dict, names=columns) else: # Server response is JSON compliant. Simply # convert from raw text to dictionary. output = json.loads(raw_output) return output def _parse_result(self, response, verbose=False): if not verbose: commons.suppress_vo_warnings() if response.status_code != 200: raise AttributeError("ERROR: The web service returned error code: %s" % response.status_code) if 'message' in response.text: raise KeyError("ERROR: API Server returned the following error:\n{}".format(response.text)) raw_output = response.text output_response = self._format_output(raw_output) return output_response
OAC = OACClass()