py_artecs

A Python3 library to handle contents of ARTECS: Archive of terrestrial-type climate simulations

http://wwwuser.oats.inaf.it/exobio/climates/

through TAP and the PYVO services.

Authors: Michele Maris (1), Marco Molinaro (1)

(1) INAF/Trieste Astronomical Observatory

First Issue: 2019 Nov 20

Dependencies:

This package needs: numpy, scipy, pandas, pyvo

Installation

For the latest release:

>>> pip3 install py_artecs

for the dev version clone this GitLab repository.

Files in py_artecs

__init__.py : the init file

tap.py : the file with the TAP library

artecs_map.py : a utility class to handle a local fits file with a Temperature MAP downloaded from the archive

modelDB.py : a utility class to handle a local csv file with the result of a query, this module is kept for backward compatibility, but its use is deprecated

Example of session:

The archive is accessed from the exop_pubblic_tap in py_artecs:

>>> from artecs import exop_pubblic_tap

Then instantiate a database object

>>> atap=exop_pubblic_tap()

all the queries to ARTECS are made through the methods in atap.

Queries follows the Astronomical Data Query Language (ADQL) format

>>> ptab=atap.search('power(SMA,1.5)>0.87');

see the appendix for further references on the ADQL.

To know wether the search is successfull:

>>> atap.success()
True

The result of a query is stored in ptab as a PANDAS data_frame.

In order to save the table as a csv file use the "to_csv" method of pandas data frame:

>>> ptab.to_csv('result.csv',sep=' ')

In order to get a map corresponding to the first entry in the ptab use:

>>> TMAP=atap.get_map(ptab.URL[0])

the command creates a fits file to rercover the fits filename

>>> print(MAP.filename)
/tmp/artecs_download_file_669d40064f5bddc8.fits

note that the get_map method saved the fits inside the /tmp directory and gives it a dummy name.

To specify a different name and directory use the outfile keyword in get_map

>>> TMAP=atap.get_map(ptab.URL[0],outfile='./test.fits')
>>> print(TMAP.filename)
./test.fits

TMAP is an object of class artecs_map, so it contains the temperature MAP in the ARTECS fits file, as well as the other keywords in the original fits file.

Note that the artecs_map class can be used also local copies of the ARTECS temperature maps.

At last, to perform a new query reset the old one with:

>>> atap.clear()

Appendix A: ADQL Queries

A query is a string . SELECTION set of data to be selected . HOW_MANY elements to select . WHICH_FIELDS fields to select . FROM which table . WHERE condition for selection is true

Examples of query strings:

  1. Download all the data:

    SELECT * FROM exo.EXO

  2. Download only the first 10 elements:

    SELECT TOP 10 * FROM exo.EXO

  3. Download only the first 10 elements with SMA in the range 0.9 to 1.1:

    SELECT TOP 10 * FROM exo.EXO WHERE SMA BETWEEN 0.9 AND 1.1

    alternativelly

    SELECT TOP 10 * FROM exo.EXO WHERE (0.9 <= SMA) AND (SMA <= 1.1)

  4. Download only the first 10 elements with SMA in the range 0.9 to 1.1 and CONTHAB>=0.5

    SELECT TOP 10 * FROM exo.EXO WHERE SMA BETWEEN 0.9 AND 1.1 AND CONTHAB>=0.5

  5. Arithmetic calculations are allowed if needed for selection so to download the first 10 elements with SMA^1.5 > 0.87

    SELECT TOP 10 * FROM exo.EXO WHERE power(SMA,1.5)> 0.87

  6. returns just columns SMA and CONTHAB from previous example:

    SELECT TOP 10 SMA,CONTHAB FROM exo.EXO WHERE power(SMA,1.5)> 0.87

Note that the query string is not sensitive to uppercase or lowercase.

For tutorials see:

A reminder of how to form query strings can be recalled by calling:

>>> atap.EXPLAIN()

Appendix B: REFERENCES

Please quote

Climate bistability of Earth-like exoplanets

Murante G., Provenzale A., Vladilo G.,Taffoni G., Silva L., Palazzi E.,von Hardenberg J.,Maris M., Londero E., Knapic C., Zorba C.

MNRAS 492, 2638–2650 (2020)

doi: 10.1093/mnras/stz3529

Appendix C: Example of session with TAP

It is possible to access the archive directly with TAP

>>> import pyvo as vo
>>> tap_service = vo.dal.TAPService("http://archives.ia2.inaf.it/vo/tap/exo")
>>> tap_results = tap_service.search("SELECT top 1 exp_id, url FROM exo.EXO")
>>> print(tap_results)
>>>...
>>> len(tap_results)
>>>...
>>> tap_results.getrecord(0)
>>>...

Appendix D: to install pyvo

>>> sudo pip3 install pyvo
1"""
2   .. include:: ../../README.md
3"""
4
5from .modelDb import *
6from .artecs_map import *
7from .tap import EXOP_TAP as exop_pubblic_tap