The ESOAsg API reference¶

ESOAsg¶

The archive_catalogues module¶

ESOAsg.archive_catalogues.all_catalogues_info(all_versions=False, verbose=False)[source]¶

Load an astropy.table with information on all catalogues present in the ESO archive

The output table will contain the following columns: collection, title, version, table_name, filter, instrument, telescope, publication_date, description, number_rows, number_columns, rel_descr_url, acknowledgment, cat_id, mjd_obs, mjd_end, skysqdeg, bibliography, document_id, from_column, target_table, target_column, last_version

For further information check the ESO catalogue facility

Note

This is analogue to run:

>>> catalogues_info(collections=None, tables=None)

with the difference that, given that no constraints are set, this returns the master table with all catalogues present in the ESO archive

Parameters

verbose (bool) – if set to True additional info will be displayed
all_versions (bool) – if set to True also obsolete versions of the catalogues are listed

Returns

table containing the information on all catalogues present in the ESO archive

Return type

astropy.table

ESOAsg.archive_catalogues.catalogues_info(all_versions=False, collections=None, tables=None, verbose=False)[source]¶

Load an astropy.table with information on the selected catalogues

Specific catalogues can be selected by selecting a list of collections or a list of table_names. If both collections and tables are set to None information on all ESO catalogues will be returned. For further information check the ESO catalogue facility

The output table will contain the following columns: collection, title, version, table_name, filter, instrument, telescope, publication_date, description, number_rows, number_columns, rel_descr_url, acknowledgment, cat_id, mjd_obs, mjd_end, skysqdeg, bibliography, document_id, from_column, target_table, target_column, last_version

Note

The way the query is created is to set as input or collections or tables. Particular attention should be given if both collections and tables are not None. Given that the connector between the two conditions is an AND this may give rise to an un-expected behaviour

Parameters

all_versions (bool) – if set to True also obsolete versions of the catalogues are listed
collections (any, optional) – list of str containing the names of the collections (or single str) for which the query will be limited
tables (any, optional) – list of str containing the table_name of the tables (or single str) for which the query will be limited
verbose (bool) – if set to True additional info will be displayed

Returns

table containing the information on the selected catalogues

Return type

astropy.table

ESOAsg.archive_catalogues.columns_info(collections=None, tables=None, verbose=False)[source]¶

Load a query that get names (and corresponding ucd) of the columns present in a collection

If collections and tables are None the query for the column of all collections and tables in the ESO archive is returned.

Note

The way the query is created is to set as input or collections or tables. Particular attention should be given if both collections and tables are not None. Given that the connector between the two conditions is an AND this may give rise to an un-expected behaviour

Parameters

collections (any, optional) – list of str containing the names of the collections (or single str) from which the columns will be extracted
tables (any, optional) – list of str containing the names of the tables (or single str) from which the columns will be extracted
verbose (bool) – if set to True additional info will be displayed

Returns

table of all columns present in a table/collection. Information are stored in table_name,: column_name, ucd, datatype, description, and unit

Return type

astropy.table

ESOAsg.archive_catalogues.get_catalogues(collections=None, tables=None, columns=None, type_of_query='sync', all_versions=False, maxrec=None, verbose=False)[source]¶

Query the ESO tap_cat service for specific catalogues

There are two ways to select the catalogues you are interested in. Either you select directly the table_name (or the list of table_names) that you want to query, or you select a collection (or a list of collections). If you select this latter option, what happens in the background is that the code is going to search for the table(s) corresponding to the given collection and query them

If you are asking for more than one table, the result will be listed in a list of astropy.tables one per table

Parameters

collections (any) – list of str containing the names (or a single str) of the collections for which the query will be limited
tables (any) – list of str containing the table_name of the tables for which the query will be limited
columns (any) – list of the column_name that you want to download. The full list of the columns in a table can be found by running columns_info()
all_versions (bool) – if set to True also obsolete versions of the catalogues are searched in case collections is given
type_of_query (str) – type of query to be run
maxrec (int, optional) – define the maximum number of entries that a single query can return. If it is None the value is set by the limit of the service.
verbose (bool) – if set to True additional info will be displayed

Returns

astropy.table or list of astropy.tables containing the queried catalogues

Return type

any

The archive_observations module¶

ESOAsg.archive_observations.download(dp_ids, min_disk_space=6.0)[source]¶

Given a filename in the ADP format, the code download the file from the ESO archive

Parameters

dp_ids (any) – list data product ID (or single product ID) to be downloaded
min_disk_space (float) – the file will be downloaded only if there is this amount of space (in Gb) free on the disk

Returns

None

ESOAsg.archive_observations.query_from_polygons(polygons, instruments=None, data_types=None, verbose=False, maxrec=None)[source]¶

Query the ESO archive for data at a area in the sky defined by a polygon

The polygons value (or list) needs to be given as a string defining the location in the sky of the polygon with RA, Dec, separated by commas and with the first RA, Dec pair that matches the last one (to close the polygon)

The output is in an (list of) astropy.table with columns defined in: core.tap_queries.COLUMNS_FROM_OBSCORE

Parameters

polygons (list) – ist of str (or single str) containing the coordinates of the polygon in the sky you want to query
instruments (list) – list of str (or single str) containing the instruments used to limit the search
data_types (list) – list of str (or single str) containing the data types used to limit the search
verbose (bool) – if set to True additional info will be displayed
maxrec (int, optional) – define the maximum number of entries that a single query can return. If it is None the value is set by the limit of the service.

Returns

results from the queries

Return type

any

ESOAsg.archive_observations.query_from_radec(positions=None, radius=None, instruments=None, data_types=None, verbose=False, maxrec=None)[source]¶

Query the ESO archive for data at a given position in RA and Dec

The positions value (or list) needs to be given as an astropy.coordinates.SkyCoord <https://docs.astropy.org/en/stable/coordinates/>`_ object.

The output is in an (list of) astropy.table with columns defined in: core.tap_queries.COLUMNS_FROM_OBSCORE

Note

In case you are querying radius=`None` is set, the query will performed with: INTERSECT(POINT(‘’,RA,Dec), s_region) instead of: INTERSECT(s_region,CIRCLE(‘’,RA,Dec,radius/3600.)). See here for further examples: tap obs examples

Parameters

positions (astropy.coordinates.SkyCoord) – coordinates (or list of coordinates) of the sky you want to query
radius (float, optional) – search radius in arcseconds
instruments (list) – list of str (or single str) containing the instruments used to limit the search
data_types (list) – list of str (or single str) containing the data types used to limit the search
verbose (bool) – if set to True additional info will be displayed
maxrec (int, optional) – define the maximum number of entries that a single query can return. If it is None the value is set by the limit of the service.

Returns

results from the queries

Return type

any

The archive_science_portal module¶

ESOAsg.archive_science_portal.query_from_polygons(polygons=None, instruments=None, data_types=None, open_link=False, show_link=False)[source]¶

Query the ESO ASP service given a polygon

The polygons value (or list) needs to be given as a string defining the location in the sky of the polygon with RA, Dec, separated by commas and with the first RA, Dec pair that matches the last one (to close the polygon)

Parameters

polygons (list) – list of str (or single str) containing the coordinates of the polygon in the sky you want to query
instruments (list) – list of str (or single str) containing the instruments used to limit the search
data_types (list) – list of str (or single str) containing the data types used to limit the search
open_link (bool) – open a link to the ASP page
show_link (bool) – show the link on the terminal

Returns

None

ESOAsg.archive_science_portal.query_from_radec(positions, radius=None, instruments=None, data_types=None, open_link=False, show_link=False)[source]¶

Query the ESO ASP service given a position

The positions value (or list) needs to be given as an astropy.coordinates.SkyCoord object. For further detail see here: astropy coordinates

Parameters

positions (astropy.coordinates.SkyCoord) – coordinates (or list of coordinates) of the sky you want to query
radius (float) – search radius in arcseconds
instruments (list) – list of str (or single str) containing the instruments used to limit the search
data_types (list) – list of str (or single str) containing the data types used to limit the search
open_link (bool) – open a link to the ASP page
show_link (bool) – show the link on the terminal

Returns

None

ESOAsg.queries¶

The query.Query class¶

class ESOAsg.queries.query.Query(tap_service=None, query=None, type_of_query='sync', result_from_query=None, maxrec=None)[source]¶

Base class that dictate the general behaviour of a query

tap_service¶

TAP service that will be used for the query

Type: pyvo.dal.tap.TAPService

query¶

String containing the query

Type: str

type_of_query¶

type of query to be run

Type: str

maxrec¶

define the maximum number of entries that a single query can return

Type: int, optional

result_from_query¶

result from the query to the TAP service

Type: astropy.table.Table

clean_query()[source]¶: Set the query attribute to None

clean_result_from_query()[source]¶: Set the result_from_query attribute to None

get_result_from_query()[source]¶: Returns a copy of result_from_query

print_query()[source]¶: Print the query on the terminal

run_query(to_string=True)[source]¶

Run the query and store results in the result_from_query attribute

Parameters: to_string (bool, optional) – if set to True, if a column is in bytes format it transform it to str

which_columns()[source]¶

Return a list with all the names of the columns in the attribute result_from_query

Returns: List of all the names of the columns
Return type: list_of_columns (list)

which_service()[source]¶

Return the tap_service that is used together with a description of it

Returns: None

The query_catalogues.ESOCatalogues class¶

Child class to run queries to the ESO catalogue

class ESOAsg.queries.query_catalogues.ESOCatalogues(query=None, result_from_query=None, type_of_query='sync', maxrec='20000')[source]¶

This class is designed to query the scientific catalogues provided by the principal investigators of ESO observing programmes

This is a child of ESOAsg.queries.query.Query with the tap_service defined to be:

>>> tap_service=tap_queries.define_tap_service('eso_tap_cat')

Parameters

query (str) – String containing the query
type_of_query (str) – type of query to be run
maxrec (int, optional) – define the maximum number of entries that a single query can return
result_from_query (astropy.table.Table) – result from the query to the TAP service

set_last_version(update=True)[source]¶

Set the last_version column to the result_from_query attribute

last_version is a column of bool where False means that there is a more update version of a catalogue

This works only if result_from_query contains the columns: version and title. In case the last_version column is already present, a warning is raised.

Parameters: update (bool) – in case the last_version column is already present the code will update the value only if update is set to True
Returns: None

The query_observations.ESOObservations class¶

class ESOAsg.queries.query_observations.ESOObservations(query=None, result_from_query=None, type_of_query='sync', maxrec='20000')[source]¶

This class is designed to query the ESO archive for raw, reduced, and ambient data.

This is a child of ESOAsg.queries.query.Query with the tap_service defined to be:

>>> tap_service=tap_queries.define_tap_service('eso_tap_obs')

Parameters

query (str) – String containing the query
type_of_query (str) – type of query to be run
maxrec (int, optional) – define the maximum number of entries that a single query can return
result_from_query (astropy.table.Table) – result from the query to the TAP service

ESOAsg.core¶

The tap_queries module¶

Module to create and run TAP queries

The Table Access Protocol (TAP) is a web-service protocol that gives access to collections of tabular data referred to collectively as a tableset. TAP services accept queries posed against the tableset available via the service and return the query response as another table, in accord with the relational model. Queries to the ESO TAP services are submitted using the Astronomical Data Query Language ADQL [O08].

Currently, ESOAsg offers two TAP services:

eso_tap_obs: to query both the database tables describing the observed raw and reduced data obtained at the La Silla Paranal Observatory, and the database table containing the ESO ambient conditions and meteorological measurements (seeing, isoplanatic angle, precipitable water, turbulence profiles, etc.)
eso_tap_cat: to query the scientific catalogues provided by the principal investigators of ESO observing programmes

More information on the ESO TAP service are at this web-page and some examples are given in these notebooks

O08: Oritz et al., (2008) IVOA Astronomical Data Query Language

ESOAsg.core.tap_queries.condition_collections_like(collections=None)[source]¶

Create a LIKE - OR condition over a list of collections

If collections is None the query the conditions will be substitute with ‘%’ meaning that will have no effect

Parameters: collections (list, optional) – list of str containing the names of the collections for which columns information will be returned
Returns: set of conditions in the format: collection LIKE — OR
Return type: str

ESOAsg.core.tap_queries.condition_data_types_like(data_types=None)[source]¶

Create condition string to select only specific data product types in ivoa.ObsCore

Parameters: data_types (list) – limit the search to the selected list of dataproduct types (e.g., spectrum)
Returns: string containing the dataproduct_type condition for a query
Return type: str

ESOAsg.core.tap_queries.condition_instruments_like(instruments=None)[source]¶

Create condition string to select only specific instruments in ivoa.ObsCore

Parameters: instruments (list) – limit the search to the selected list of instruments (e.g., XSHOOTER)
Returns: string containing the instrument_name condition for a query
Return type: str

ESOAsg.core.tap_queries.condition_intersects_polygon(polygon)[source]¶

Create the WHERE INTERSECTS polygon condition string for a query

Parameters: polygon (str) – coordinates of the verices of the polygon in the sky
Returns: String containing the WHERE INTERSECT condition for a query
Return type: str

ESOAsg.core.tap_queries.condition_intersects_ra_dec(ra, dec, radius=None)[source]¶

Create the WHERE INTERSECTS condition string for a query

Parameters

ra (float) – RA of the target in degrees and in the ICRS system
dec (float) – Dec of the target in degrees and in the ICRS system
radius (float, optional) – Search radius in arcsec. If set to None no radius will be considered in the INTERSECT condition

Returns

String containing the WHERE INTERSECT condition for a query

Return type

str

ESOAsg.core.tap_queries.condition_tables_like(tables=None)[source]¶

Create a LIKE - OR condition over a list of table_names

If tables is None the query the conditions will be substitute with ‘%’ meaning that will have no effect

Parameters: tables (list) – list of str containing the table_name for which columns information will be returned
Returns: set of conditions in the format: table_name LIKE — OR
Return type: str

ESOAsg.core.tap_queries.create_query_all_catalogues(all_versions=False, collections=None, tables=None)[source]¶

Create TAP query that returns info on all catalogues in the ESO archive

If collections or tables are not None only the query for the selected collections/tables is returned

Parameters

all_versions (bool) – if set to True also obsolete versions of the catalogues are listed
collections (list, optional) – list of str containing the names of the collections that are going to be selected
tables (list, optional) – list of str containing the table_name of the tables that are going to be selected

Returns

string containing the query to obtain all catalogues present in the ESO archive

Return type

str

ESOAsg.core.tap_queries.create_query_all_columns(collections=None, tables=None)[source]¶

Create a query that get names (and corresponding info) of the columns present in a collection (or in a table)

If collections and tables are None the query for the column of all collections in the ESO archive is returned.

Parameters

collections (list, optional) – list of str containing the names of the collections for which columns information will be returned
tables (list, optional) – list of str containing the table_name for which columns information will be returned

Returns

string containing the query to obtain information on all columns present in the ESO archive

Return type

str

ESOAsg.core.tap_queries.create_query_obscore_base()[source]¶

Create the base string for a query to ivoa.ObsCore

Returns: Base for the ivoa.ObsCore queries
Return type: str

ESOAsg.core.tap_queries.create_query_table(table_name, columns=None)[source]¶

Create a query to return selected columns from a table

Parameters

columns (list, optional) – list of str containing the columns that will be queried
table_name (str) – name of the table that will be queried

Returns

query to obtain data from a table

Return type

str

ESOAsg.core.tap_queries.define_tap_service(which_tap_service)[source]¶

Load a Table Access Protocol (TAP) service from defaults

Currently the supported TAP services are: * eso_tap_cat: TAP service for scientific catalogues generated by ESO observing teams * eso_tap_obs: TAP service for raw, reduced, and ambient data

See pyvo docs for further details

Parameters

which_tap_service (str) –

Select the TAP services to be queried

Returns

TAP service used for the queries

Return type

pyvo.dal.tap.TAPService

ESOAsg.core.tap_queries.print_query(query)[source]¶

Print the query on the terminal

In case the query is empty, a warning is raised

Parameters: query (str) – String containing the query
Returns: None

ESOAsg.core.tap_queries.run_query(tap_service, query, type_of_query, maxrec='20000')[source]¶

Run query to TAP service and return result as an astropy.Table

If the job requires to much time to run, the code will move to an asynchronous query.

Parameters

tap_service (pyvo.dal.tap.TAPService) – TAP service that will be used for the query
query (str) – query to be run
type_of_query (str) – type of query to be run
maxrec (int) – define the maximum number of entries that a single query can return. Default is set by default.get_value(‘maxrec’)

Returns

result from the query to the TAP service

Return type

astropy.table

ESOAsg.core.tap_queries.run_query_async(tap_service, query, maxrec='20000')[source]¶

Run an asynchronous query to TAP service and return result as an astropy.Table

Parameters

tap_service (pyvo.dal.tap.TAPService) – TAP service that will be used for the query
query (str) – query to be run
maxrec (int) – define the maximum number of entries that a single query can return. Default is set by default.get_value(‘maxrec’)

Returns

result from the query to the TAP service

Return type

astropy.table

ESOAsg.core.tap_queries.run_query_sync(tap_service, query, maxrec='20000')[source]¶

Run a synchronous query to TAP service and return result as an astropy.Table

If the synchronous query fails, the code automatically tries to run the same query asynchronously

Parameters

tap_service (pyvo.dal.tap.TAPService) – TAP service that will be used for the query
query (str) – query to be run
maxrec (int) – define the maximum number of entries that a single query can return. Default is set by default.get_value(‘maxrec’)

Returns

result from the query to the TAP service

Return type

astropy.table

ESOAsg.core.tap_queries.which_service(tap_service)[source]¶

Print a summary description of the TAP service used

Parameters: tap_service (pyvo.dal.tap.TAPService) – TAP service used for the queries
Returns: None

The asp_queries module¶

Module to create and run ASP queries

The ESO Archive Science Portal (ASP) allows browsing and exploration of archive content using an intuitive interactive user interface that supports iterative queries

ESOAsg.core.asp_queries.base_url()[source]¶

Return the url for ASP

Returns: url
Return type: str

ESOAsg.core.asp_queries.condition_data_types(data_types, connector=None)[source]¶

Return condition for data types

Parameters

data_types (list) – limit the search to the selected list of dataproduct types (e.g., spectrum)
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string containing the dp_type= condition for ASP

Return type

str

ESOAsg.core.asp_queries.condition_instruments(instruments, connector=None)[source]¶

Return condition for instruments

Parameters

instruments (list) – limit the search to the selected list of instruments (e.g., XSHOOTER)
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string containing the ins_id= condition for ASP

Return type

str

ESOAsg.core.asp_queries.condition_polygon(polygon, connector=None)[source]¶

Return condition for polygon

Parameters

polygon (any) – string containing the RA and Dec vertices (in degrees) of the polygon
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string containing the poly= condition for ASP

Return type

str

ESOAsg.core.asp_queries.condition_position(ra, dec, radius=None, connector=None)[source]¶

Return condition for position

Parameters

ra (any) – string containing the RA of the source in degree
dec (any) – string containing the Dec of the source in degree
radius (any) – string containing the search radius in arcseconds
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string containing the pos= condition for ASP

Return type

str

ESOAsg.core.asp_queries.condition_radius(radius, connector=None)[source]¶

Return condition for radius

Parameters

radius (any) – string containing the search radius in arcseconds
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string containing the r= condition for ASP

Return type

str

ESOAsg.core.asp_queries.run_query(query, show_link=True, open_link=True)[source]¶

Run the ASP query

Parameters

query (str) – url of the ASP query
open_link (bool) – open a link to the ASP page
show_link (bool) – show the link on the terminal

Returns

None

ESOAsg.core.asp_queries.sort_by(sort_type='-obs_date', connector=None)[source]¶

Sort the ASP query for a specific keyword

Parameters

sort_type (str) – value for which sort the ASP query
connector (str, optional) – connector to be put in front of the the condition (e.g., ‘&’)

Returns

string that defines the sort type in a ASP query

Return type

str

ESOAsg.datacontainers¶

ligthcurves¶

Class to work on light curves

class ESOAsg.datacontainers.lightcurves.LightCurves(primary_header=None, header=None, time=None, flux=None, error=None, time_bin=None, background=None, quality=None, others=None)[source]¶

A class used to define and make simple operations on time series

This allows to perform some basic tasks on a time series and to save it in a format that is ESO Phase3 compliant.

Attributes:

Methods:

check(autocorrect=False)[source]¶: Checks that a LightCurves objects is in a format compatible with the ESO standard

load_from_table(table, primary_header=None, copy_header=True, where_time='TIME', where_time_bin='TIME_BIN', where_flux='FLUX', where_error='ERROR', where_background='BACKGROUND', where_quality='QUAL')[source]¶

Given a table put it in a LightCurves object

Parameters

where_quality –
where_background –
where_error –
where_time_bin –
where_time –
copy_header –
primary_header –
where_flux –

ESOAsg.datacontainers.lightcurves.save_into_fits(fits_file_name, primary_header, light_curve_headers, light_curve_names, light_curves, overwrite=True)[source]¶

Parameters

light_curves –
light_curve_names –
light_curve_headers –
fits_file_name –
primary_header –
lightcurves –
overwrite (bool) –

Returns: