From f25b252913861a8157b9591d9e3043d334c444e2 Mon Sep 17 00:00:00 2001 From: "michele.maris" Date: Wed, 24 May 2023 19:49:31 +0200 Subject: [PATCH] u added docs for sphinx --- docs/Makefile | 20 ++++++++++ docs/build/content | 1 + docs/make.bat | 35 +++++++++++++++++ docs/search.js | 46 ++++++++++++++++++++++ docs/source/adql.rst | 65 +++++++++++++++++++++++++++++++ docs/source/api.rst | 9 +++++ docs/source/conf.py | 74 ++++++++++++++++++++++++++++++++++++ docs/source/howtoquote.rst | 13 +++++++ docs/source/index.rst | 41 ++++++++++++++++++++ docs/source/installation.rst | 32 ++++++++++++++++ docs/source/miscellanea.rst | 19 +++++++++ docs/source/py_artecs.rst | 25 ++++++++++++ docs/source/usage.rst | 66 ++++++++++++++++++++++++++++++++ docs/source/usage.rst.old | 22 +++++++++++ 14 files changed, 468 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/build/content create mode 100644 docs/make.bat create mode 100644 docs/search.js create mode 100644 docs/source/adql.rst create mode 100644 docs/source/api.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/howtoquote.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/installation.rst create mode 100644 docs/source/miscellanea.rst create mode 100644 docs/source/py_artecs.rst create mode 100644 docs/source/usage.rst create mode 100644 docs/source/usage.rst.old diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/build/content b/docs/build/content new file mode 100644 index 0000000..b42a9a7 --- /dev/null +++ b/docs/build/content @@ -0,0 +1 @@ +docs contains documentation produced by sphinx diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6fcf05b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/search.js b/docs/search.js new file mode 100644 index 0000000..9acf963 --- /dev/null +++ b/docs/search.js @@ -0,0 +1,46 @@ +window.pdocSearch = (function(){ +/** elasticlunr - http://weixsong.github.io * Copyright (C) 2017 Oliver Nightingale * Copyright (C) 2017 Wei Song * MIT Licensed */!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u0&&t.push(e);for(var i in n)"docs"!==i&&"df"!==i&&this.expandToken(e+i,t,n[i]);return t},t.InvertedIndex.prototype.toJSON=function(){return{root:this.root}},t.Configuration=function(e,n){var e=e||"";if(void 0==n||null==n)throw new Error("fields should not be null");this.config={};var i;try{i=JSON.parse(e),this.buildUserConfig(i,n)}catch(o){t.utils.warn("user configuration parse failed, will use default configuration"),this.buildDefaultConfig(n)}},t.Configuration.prototype.buildDefaultConfig=function(e){this.reset(),e.forEach(function(e){this.config[e]={boost:1,bool:"OR",expand:!1}},this)},t.Configuration.prototype.buildUserConfig=function(e,n){var i="OR",o=!1;if(this.reset(),"bool"in e&&(i=e.bool||i),"expand"in e&&(o=e.expand||o),"fields"in e)for(var r in e.fields)if(n.indexOf(r)>-1){var s=e.fields[r],u=o;void 0!=s.expand&&(u=s.expand),this.config[r]={boost:s.boost||0===s.boost?s.boost:1,bool:s.bool||i,expand:u}}else t.utils.warn("field name in user configuration not found in index instance fields");else this.addAllFields2UserConfig(i,o,n)},t.Configuration.prototype.addAllFields2UserConfig=function(e,t,n){n.forEach(function(n){this.config[n]={boost:1,bool:e,expand:t}},this)},t.Configuration.prototype.get=function(){return this.config},t.Configuration.prototype.reset=function(){this.config={}},lunr.SortedSet=function(){this.length=0,this.elements=[]},lunr.SortedSet.load=function(e){var t=new this;return t.elements=e,t.length=e.length,t},lunr.SortedSet.prototype.add=function(){var e,t;for(e=0;e1;){if(r===e)return o;e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o]}return r===e?o:-1},lunr.SortedSet.prototype.locationFor=function(e){for(var t=0,n=this.elements.length,i=n-t,o=t+Math.floor(i/2),r=this.elements[o];i>1;)e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o];return r>e?o:e>r?o+1:void 0},lunr.SortedSet.prototype.intersect=function(e){for(var t=new lunr.SortedSet,n=0,i=0,o=this.length,r=e.length,s=this.elements,u=e.elements;;){if(n>o-1||i>r-1)break;s[n]!==u[i]?s[n]u[i]&&i++:(t.add(s[n]),n++,i++)}return t},lunr.SortedSet.prototype.clone=function(){var e=new lunr.SortedSet;return e.elements=this.toArray(),e.length=e.elements.length,e},lunr.SortedSet.prototype.union=function(e){var t,n,i;this.length>=e.length?(t=this,n=e):(t=e,n=this),i=t.clone();for(var o=0,r=n.toArray();oA Python3 library to handle contents of ARTECS: Archive of terrestrial-type climate simulations

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

through TAP and the PYVO services.

\n\n

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

\n\n
(1) INAF/Trieste Astronomical Observatory\n
\n\n

First Issue: 2019 Nov 20

\n\n

Dependencies:

\n\n

This package needs: \n numpy, scipy, pandas, pyvo

\n\n

Installation

\n\n

For the latest release:

\n\n
\n
>>> pip3 install py_artecs\n
\n
\n\n

for the dev version clone this GitLab repository.

\n\n

Files in py_artecs

\n\n

__init__.py : the init file

\n\n

tap.py : the file with the TAP library

\n\n

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

\n\n

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

\n\n

Example of session:

\n\n

The archive is accessed from the exop_pubblic_tap in py_artecs:

\n\n
\n
>>> from artecs import exop_pubblic_tap\n
\n
\n\n

Then instantiate a database object

\n\n
\n
>>> atap=exop_pubblic_tap()\n
\n
\n\n

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

\n\n

Queries follows the Astronomical Data Query Language (ADQL) format

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

see the appendix for further references on the ADQL.

\n\n

To know wether the search is successfull:

\n\n
\n
>>> atap.success()\nTrue\n
\n
\n\n

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

\n\n

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

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

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

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

the command creates a fits file to rercover the fits filename

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

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

\n\n

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

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

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.

\n\n

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

\n\n

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

\n\n
\n
>>> atap.clear()\n
\n
\n\n

Appendix A: ADQL Queries

\n\n

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

\n\n

Examples of query strings:

\n\n
    \n

  1. Download all the data:

    \n\n
    \n

    SELECT * FROM exo.EXO

    \n
    2. \n

  2. Download only the first 10 elements:

    \n\n
    \n

    SELECT TOP 10 * FROM exo.EXO

    \n
    3. \n

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

    \n\n
    \n

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

    \n
    \n\n

    alternativelly

    \n\n
    \n

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

    \n
    4. \n

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

    \n\n
    \n

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

    \n
    5. \n

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

    \n\n
    \n

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

    \n
    6. \n

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

    \n\n
    \n

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

    \n
    7. \n
\n\n

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

\n\n

For tutorials see:

\n\n\n\n

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

\n\n
\n
>>> atap.EXPLAIN()\n
\n
\n\n

Appendix B: REFERENCES

\n\n

Please quote

\n\n

Climate bistability of Earth-like exoplanets

\n\n

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

\n\n

MNRAS 492, 2638\u20132650 (2020)

\n\n

doi: 10.1093/mnras/stz3529

\n\n

Appendix C: Example of session with TAP

\n\n

It is possible to access the archive directly with TAP

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

Appendix D: to install pyvo

\n\n
\n
>>> sudo pip3 install pyvo\n
\n
\n"}, {"fullname": "py_artecs.artecs_map", "modulename": "py_artecs.artecs_map", "kind": "module", "doc": "

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map", "kind": "class", "doc": "

A class to handle a temperature map from ARTECS.

\n\n

It reads the artecs_map from a fits file.

\n\n
\n
>>> AMAP=artecs_map("artecs_map.fits")\n
\n
\n\n

Keywords in the map are returned as members of the class or using the method \"parameter\".

\n\n

Example:

\n\n
\n
>>> AMAP.temp \n
\n
\n\n

returns the temperature map,

\n\n
\n
>>> AMAP.parameter('temp')\n
\n
\n\n

returns the temperature map.

\n\n
\n
>>> AMAP.shape\n
\n
\n\n

returns the shape of the map (rows, columns)

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.__init__", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.__init__", "kind": "function", "doc": "

To instantiate the class pass the filename from which to load the Temperature map

\n\n
\n

Keywords:

\n
\n\n
\n
\n

verbose: if True verbose output

\n
\n
\n\n
\n
\n

closeFits: if True the fits file is closed after reading

\n
\n
\n", "signature": "(filename, closeFits=True, verbose=False)"}, {"fullname": "py_artecs.artecs_map.artecs_map.filename", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.filename", "kind": "variable", "doc": "

parameter: the filename

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.p", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.p", "kind": "variable", "doc": "

the fits file pointer, normally closed.

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.lst_lat", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.lst_lat", "kind": "variable", "doc": "

list of latitude bands

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.lst_year", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.lst_year", "kind": "variable", "doc": "

list of time intervals

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.shape", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.shape", "kind": "variable", "doc": "

the shape of the 2D maps

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.TMGLOB", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.TMGLOB", "kind": "variable", "doc": "

the mean surface temperature

\n"}, {"fullname": "py_artecs.artecs_map.artecs_map.keys", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.keys", "kind": "function", "doc": "

returns the list of quantities in the map

\n\n

Keywords:

\n\n
\n

maps (default False), if True returns just the list of of elements which are 2D maps

\n
\n", "signature": "(self, maps=False):", "funcdef": "def"}, {"fullname": "py_artecs.artecs_map.artecs_map.has_key", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.has_key", "kind": "function", "doc": "

True if required key is in the map

\n", "signature": "(self, key):", "funcdef": "def"}, {"fullname": "py_artecs.artecs_map.artecs_map.parameter", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.parameter", "kind": "function", "doc": "

returns a parameter from the fits file from its `key'

\n", "signature": "(self, key):", "funcdef": "def"}, {"fullname": "py_artecs.artecs_map.artecs_map.description", "modulename": "py_artecs.artecs_map", "qualname": "artecs_map.description", "kind": "function", "doc": "

returns the description of a parameter in the fits file from its `key'

\n", "signature": "(self, key):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb", "modulename": "py_artecs.modelDb", "kind": "module", "doc": "

DEPRECATED

\n"}, {"fullname": "py_artecs.modelDb.modelDb", "modulename": "py_artecs.modelDb", "qualname": "modelDb", "kind": "class", "doc": "

DEPRECATED

\n\n

Class to handle a local version of the ARTECS DB.

\n\n

It takes in input a csv file generated from a query of ARTECS and saved in csv format.

\n\n

See the example in the introductory page.

\n\n

This module is kept for compatibility with early releases of py_artecs, but it is not maintained so its use is DEPRECATED.

\n"}, {"fullname": "py_artecs.modelDb.modelDb.__init__", "modulename": "py_artecs.modelDb", "qualname": "modelDb.__init__", "kind": "function", "doc": "

\n", "signature": "(\tproject_name,\tproject_path,\tcsv_name,\tVerbose=True,\tcsv_sep='!',\tcsv_comment='#',\tcsv_index_col='index',\tfigures_path='png',\tfilterBad=True,\tnew=False,\tquery=None)"}, {"fullname": "py_artecs.modelDb.modelDb.to_csv", "modulename": "py_artecs.modelDb", "qualname": "modelDb.to_csv", "kind": "function", "doc": "

\n", "signature": "(self, outFile, COMMENT=''):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.reset", "modulename": "py_artecs.modelDb", "qualname": "modelDb.reset", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.copy", "modulename": "py_artecs.modelDb", "qualname": "modelDb.copy", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.unique_values", "modulename": "py_artecs.modelDb", "qualname": "modelDb.unique_values", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.list_unique_values", "modulename": "py_artecs.modelDb", "qualname": "modelDb.list_unique_values", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.classification_indexes", "modulename": "py_artecs.modelDb", "qualname": "modelDb.classification_indexes", "kind": "function", "doc": "

\n", "signature": "(self, *arg, **karg):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.show_classTable", "modulename": "py_artecs.modelDb", "qualname": "modelDb.show_classTable", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.unique", "modulename": "py_artecs.modelDb", "qualname": "modelDb.unique", "kind": "function", "doc": "

\n", "signature": "(self, key):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.sort", "modulename": "py_artecs.modelDb", "qualname": "modelDb.sort", "kind": "function", "doc": "

\n", "signature": "(self, sort_by):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.sorted_query", "modulename": "py_artecs.modelDb", "qualname": "modelDb.sorted_query", "kind": "function", "doc": "

\n", "signature": "(self, sort_by, qstr):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.query", "modulename": "py_artecs.modelDb", "qualname": "modelDb.query", "kind": "function", "doc": "

\n", "signature": "(self, qstr):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.select_by_loc", "modulename": "py_artecs.modelDb", "qualname": "modelDb.select_by_loc", "kind": "function", "doc": "

\n", "signature": "(self, loc_argument):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.select_by_iloc", "modulename": "py_artecs.modelDb", "qualname": "modelDb.select_by_iloc", "kind": "function", "doc": "

\n", "signature": "(self, iloc_argument):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.classification_string2numeric", "modulename": "py_artecs.modelDb", "qualname": "modelDb.classification_string2numeric", "kind": "function", "doc": "

\n", "signature": "(self, strg):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.calc_iclass", "modulename": "py_artecs.modelDb", "qualname": "modelDb.calc_iclass", "kind": "function", "doc": "

\n", "signature": "(self, string_classification_array):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.keys", "modulename": "py_artecs.modelDb", "qualname": "modelDb.keys", "kind": "function", "doc": "

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.has_key", "modulename": "py_artecs.modelDb", "qualname": "modelDb.has_key", "kind": "function", "doc": "

\n", "signature": "(self, this):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.reset_plot_status", "modulename": "py_artecs.modelDb", "qualname": "modelDb.reset_plot_status", "kind": "function", "doc": "

resets the self._last_plot dictionary where handles from the last plot generated are stored

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.plot2", "modulename": "py_artecs.modelDb", "qualname": "modelDb.plot2", "kind": "function", "doc": "

creates a 2 axis plot, the handles for the plot objects are stored in self._last_plot

\n", "signature": "(\tself,\tx,\ty='MolecularDepth',\tylog=True,\txlog=False,\tnewfig=True,\tlegend_loc=3,\txylim=None,\tsavefig=None,\tone2one_line=False):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.set_iceTOT_threshold", "modulename": "py_artecs.modelDb", "qualname": "modelDb.set_iceTOT_threshold", "kind": "function", "doc": "

set iceTOT_threshold : the ice coverage over which the planet is considered a snowball\nsuggested values 0.95 or 0.99

\n", "signature": "(self, iceTOT_threshold):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.flag_class_warm", "modulename": "py_artecs.modelDb", "qualname": "modelDb.flag_class_warm", "kind": "function", "doc": "

returns Murante's classifications for warm calculated from scratch\niceTOT_threshold is the ice coverage over which the planet is considered a snowball\nsuggested values 0.95 or 0.99

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.flag_class_warm_hot", "modulename": "py_artecs.modelDb", "qualname": "modelDb.flag_class_warm_hot", "kind": "function", "doc": "

returns Murante's classifications for warm_hot calculated from scratch\niceTOT_threshold is the ice coverage over which the planet is considered a snowball\nsuggested values 0.95 or 0.99

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.flag_class_snowball", "modulename": "py_artecs.modelDb", "qualname": "modelDb.flag_class_snowball", "kind": "function", "doc": "

returns Murante's classifications for warm_hot calculated from scratch\niceTOT_threshold is the ice coverage over which the planet is considered a snowball\nsuggested values 0.95 or 0.99

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.modelDb.modelDb.flag_class_waterbelt", "modulename": "py_artecs.modelDb", "qualname": "modelDb.flag_class_waterbelt", "kind": "function", "doc": "

returns Murante's classifications for warm_hot calculated from scratch\niceTOT_threshold is the ice coverage over which the planet is considered a snowball\nsuggested values 0.95 or 0.99

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.tap", "modulename": "py_artecs.tap", "kind": "module", "doc": "

\n"}, {"fullname": "py_artecs.tap.EXOP_TAP", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP", "kind": "class", "doc": "

\n"}, {"fullname": "py_artecs.tap.EXOP_TAP.__init__", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.__init__", "kind": "function", "doc": "

\n", "signature": "(\ttap_url='http://archives.ia2.inaf.it/vo/tap/exo',\ttable_name='exo.EXO',\ttemporary_files_path='/tmp')"}, {"fullname": "py_artecs.tap.EXOP_TAP.keys", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.keys", "kind": "function", "doc": "

list of fields in the database

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.has_key", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.has_key", "kind": "function", "doc": "

has_key

\n", "signature": "(self, this):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.success", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.success", "kind": "function", "doc": "

returns True if last search was successfull

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.clean", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.clean", "kind": "function", "doc": "

cleans information from last search

\n", "signature": "(self):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.adql_search", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.adql_search", "kind": "function", "doc": "

search on database using ADQL string

\n", "signature": "(self, adql_string):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.search_string", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.search_string", "kind": "function", "doc": "

creates a properly formatted adql query_string

\n", "signature": "(self, SELECTION, TOP, FIELDS, WHERE, SORT):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.search", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.search", "kind": "function", "doc": "

download a table from the database\nsearch('') or search(WHERE='') returns all the data in the database

\n\n

the table can be returned as :\n pandas dataframe (default)\n astropy table (as_astropy = True)\n votable (as_votable=True)

\n", "signature": "(\tself,\tWHERE,\tSELECTION=None,\tFIELDS=None,\tTOP=None,\tSORT=None,\tas_astropy=False,\tas_votable=False):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.get_map", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.get_map", "kind": "function", "doc": "

gets a map

\n", "signature": "(self, _URL, outfile=None):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.download_map", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.download_map", "kind": "function", "doc": "

download the fits file corresponding at a given URL\nif outfile is not specified the fits file name from the URL is used\nif path is not specified the current file is stored in the current path

\n", "signature": "(self, URL, outfile=None, path=None):", "funcdef": "def"}, {"fullname": "py_artecs.tap.EXOP_TAP.EXPLAIN", "modulename": "py_artecs.tap", "qualname": "EXOP_TAP.EXPLAIN", "kind": "function", "doc": "

print a short introduction on the query language

\n", "signature": "(self):", "funcdef": "def"}]; + + // mirrored in build-search-index.js (part 1) + // Also split on html tags. this is a cheap heuristic, but good enough. + elasticlunr.tokenizer.setSeperator(/[\s\-.;&_'"=,()]+|<[^>]*>/); + + let searchIndex; + if (docs._isPrebuiltIndex) { + console.info("using precompiled search index"); + searchIndex = elasticlunr.Index.load(docs); + } else { + console.time("building search index"); + // mirrored in build-search-index.js (part 2) + searchIndex = elasticlunr(function () { + this.pipeline.remove(elasticlunr.stemmer); + this.pipeline.remove(elasticlunr.stopWordFilter); + this.addField("qualname"); + this.addField("fullname"); + this.addField("annotation"); + this.addField("default_value"); + this.addField("signature"); + this.addField("bases"); + this.addField("doc"); + this.setRef("fullname"); + }); + for (let doc of docs) { + searchIndex.addDoc(doc); + } + console.timeEnd("building search index"); + } + + return (term) => searchIndex.search(term, { + fields: { + qualname: {boost: 4}, + fullname: {boost: 2}, + annotation: {boost: 2}, + default_value: {boost: 2}, + signature: {boost: 2}, + bases: {boost: 2}, + doc: {boost: 1}, + }, + expand: true + }); +})(); \ No newline at end of file diff --git a/docs/source/adql.rst b/docs/source/adql.rst new file mode 100644 index 0000000..e523579 --- /dev/null +++ b/docs/source/adql.rst @@ -0,0 +1,65 @@ +ADQL Queries +============ + +A query is a string with format + + [expression [ ....]] + +Valid directives are + +SELECTION + set of data to be selected + +HOW_MANY + elements to select + +WHICH_FIELDS + fields to select + +FROM + which table to be queried + +WHERE + condition for elements selection + +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` + +4. The same but with a different expression +:: + `SELECT TOP 10 * FROM exo.EXO WHERE (0.9 <= SMA) AND (SMA <= 1.1)` + +5. 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` + +6. 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` + +7. 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 a query string is not sensitive to uppercase or lowercase. + +For other details 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/ + +An inline reminder of how to form query strings can be recalled by: + + >>> atap.EXPLAIN() diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 0000000..185a500 --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,9 @@ +API +=== + +.. autosummary:: py_artecs + :toctree: + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..1f2f8b8 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,74 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +#sys.path.insert(0, os.path.abspath(os.getcwd()+'/src')) +sys.path.insert(0, '../src') +#print(sys.path) + + + +# -- Project information ----------------------------------------------------- + +project = 'py_artecs' +copyright = '2023, M.Maris, M.Molinaro' +author = 'M.Maris, M.Molinaro' + +# The full version, including alpha/beta/rc tags +release = '1.0.1' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'autoapi.extension', + 'sphinx.ext.inheritance_diagram', +] + +autoapi_type='python' + +autoapi_dirs = ['../../src/py_artecs'] + +autoapi_options: [ 'members', 'show-inheritance', 'show-inheritance-diagram', 'special-members', 'imported-members'] + +#autoapi_options: [ 'members', 'private-members', 'show-inheritance', 'show-module-summary', 'special-members', 'imported-members', 'undoc-members'] +#autoapi_options= ['members'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + diff --git a/docs/source/howtoquote.rst b/docs/source/howtoquote.rst new file mode 100644 index 0000000..299050f --- /dev/null +++ b/docs/source/howtoquote.rst @@ -0,0 +1,13 @@ +How to Quote +============ +If you use this library of parts of it for your work, 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) + + https://doi.org/10.1093/mnras/stz3529 + + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..b8daa4a --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,41 @@ +.. py_artecs documentation master file, created by + sphinx-quickstart on Wed May 24 10:11:21 2023. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to py_artecs's documentation! +===================================== + + +The library py_artecs is designed to provide an user friendly interface to the `ARTECS http://wwwuser.oats.inaf.it/exobio/climates/' database of exoplanets climates through TAP and PyVO services. + +It was originally authored in 2019 by Michele Maris and Marco Molinaro. + +The library allows to query the database for a list of models, download the list and for each model download the corresponding fits file containing the exoplanet temperature map. + +The library also provides a class to simplify the handling of a temperature map file. + +Check out section :ref:`Install ` to install the project and section :doc:`Usage ` for an example of usage. + +------- + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + installation + usage + adql + + miscellanea + + howtoquote + +------------------- + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..657358f --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,32 @@ +.. _installation: + +Installation +============ + +To install by pip +----------------- + +To install with pip3: + +.. code-block:: console + + $ pip3 install py_artecs + +To clone the dev version +------------------------ + +To clone the development version from the GitLab of National Institute of Astrophysics + +.. code-block:: console + + $ git clone https://www.ict.inaf.it/gitlab/michele.maris/py_artecs + +Note that in this case the library will be in ./py_artecs/src/py_artecs. + +To install pyvo +--------------- +The package pyvo should be part of astropy. To install separately + +.. code-block:: console + + $ sudo pip3 install pyvo diff --git a/docs/source/miscellanea.rst b/docs/source/miscellanea.rst new file mode 100644 index 0000000..5bbabe3 --- /dev/null +++ b/docs/source/miscellanea.rst @@ -0,0 +1,19 @@ +Miscellanea +=========== + +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) +>>>... + + diff --git a/docs/source/py_artecs.rst b/docs/source/py_artecs.rst new file mode 100644 index 0000000..a3e5c01 --- /dev/null +++ b/docs/source/py_artecs.rst @@ -0,0 +1,25 @@ +py\_artecs +========== + +.. automodule:: py_artecs + :members: + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/usage.rst b/docs/source/usage.rst new file mode 100644 index 0000000..ffbb7cc --- /dev/null +++ b/docs/source/usage.rst @@ -0,0 +1,66 @@ +Usage +===== + +Basic query +----------- + +The archive is accessed from exop_pubblic_tap in py_artecs: + + >>> from artecs import exop_pubblic_tap + +Then instantiate a database session named "atap" + + >>> 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 + +Before a new query the atap has to be resetted width: + + >>> atap.clear() + +Results in pandas table +----------------------- + +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=' ') + +Getting temperature maps +------------------------ + +In order to get a map corresponding to the first entry in the ptab use: + + >>> TMAP=atap.get_map(ptab[0].URL) + +the command creates a fits file to download the fits file specified in ptab[0].URL + + >>> 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[0].URL,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. + + + diff --git a/docs/source/usage.rst.old b/docs/source/usage.rst.old new file mode 100644 index 0000000..e9c1339 --- /dev/null +++ b/docs/source/usage.rst.old @@ -0,0 +1,22 @@ +Usage +===== + +.. _installation: + +Installation +------------ + +To use py_artecs, firt install it by using pip3: + +.. code-block:: console + + $ pip3 install py_artecs + +If you want to download the development version download it from inaf GitLab with + +.. code-block:: console + + $ git clone https://www.ict.inaf.it/gitlab/michele.maris/py_artecs + +in this case the library will be in py_artecs/src/py_artecs. + -- GitLab