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:
Download all the data:
SELECT * FROM exo.EXO
Download only the first 10 elements:
SELECT TOP 10 * FROM exo.EXO
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)
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
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
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:
- http://www.g-vo.org/tutorials/gaia-mock-tap.pdf
- http://www.ivoa.net/documents/REC/ADQL/ADQL-20081030.pdf
- http://www.ivoa.net/documents/
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