ExoTETHyS

ExoTETHyS: Tools for Exoplanetary Transits around host stars - Published in JOSS (2020)

https://github.com/ucl-exoplanets/exotethys

Scientific Fields

Repository

README.adoc

= ExoTETHyS:
:author: Giuseppe Morello
:sectnums:
:sectnumlevels: 2
:toc: preamble
:toclevels: 4
:source-language: python
:experimental:
:xrefstyle: short

#*Tools for Exoplanetary Transits around Host Stars*#

image::logo.png[width=40%]
*version: 2.0.10*

ifdef::env-github[]
:tip-caption: :bulb:
:note-caption: :information_source:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]


ExoTETHyS is an open-source package for modeling exoplanetary transits, eclipsing binaries and related phenomena. +
It includes various subpackages with different functions. We remind to the link:user_manuals/[user manuals] and relevant papers (see below) for their rationale and detailed instructions. You can also consult the wiki with the answers to frequently asked questions (link:../../wiki/ExoTETHyS-FAQ[FAQ]).

== Getting started

These instructions will get you to have a version of the package on your computer up and running.

=== Requirements
The code is consistent with python2/3. +
The required python libraries are specified in the file requirements.txt.

=== Download and installation

==== From Pypi

Type on the terminal: `` pip install exotethys `` +
This command installs the latest stable version of the package.

==== From Github

The most updated version of the package is available on GitHub. As this version is constantly under development, stability is not guaranteed.

To download and install with a single command, type on the terminal +
`pip install git+git://github.com/ucl-exoplanets/ExoTETHyS`.

To download, then (optionally) install:

1. Go to , +
then click the green button *Clone or download*, +
then click *Download ZIP* to download the whole repository. +
+
_Alternatively_ type on the terminal +
`git clone https://github.com/ucl-exoplanets/ExoTETHyS`.

2. Access the root folder from terminal (you may need to unzip first).

3. After accessing the root folder from terminal, type `pip install .` to install the package. +
+
_Otherwise_, you could import the package without installation, if you run python from the root folder.

4. To test the installation, you can type:
[source, bash]
```
pytest PATH_TO_ROOT/exotethys/tests/test_sail.py  
pytest PATH_TO_ROOT/exotethys/tests/test_trip.py 
pytest PATH_TO_ROOT/exotethys/tests/boats_trip.py 
```

NOTE: The root folder name depends on the download process. It appears to be *ExoTETHyS-master* if downloaded from the web browser interface, *ExoTETHyS* if git cloned from terminal.

==== Before using

TIP: If this is the first time that you are using ExoTETHyS, you can skip this subsection.

If you had already installed/used an older version of ExoTETHyS (v1.x.y), you should delete the old database folder to avoid incompatibility issues.

NOTE: If a file from the old database is mistakenly used with this new version, *the run will fail* raising an error message. There is *no risk* to obtain wrong results.

The database folder should be located in your home: `/PATH_HOME/.exotethys`.
You could locate and remove this folder. +
This operation can also be performed by using the manage_database subpackage of ExoTETHyS, as follows:

[source, bash]
```
>>> from exotethys import manage_database as mdb 
>>> mdb.rm_database() 
Are you sure that you want to delete the directory /Users/pepe/.exotethys? [y/N]: y 
```

WARNING: *The above operation is irreversible.* It is highly recommended that you read more about the manage_database subpackage before deciding to perform this operation.


=== Quick how to run the subpackages

NOTE: The following example files are written to be launched from root directory level. +
Alternatively, the paths in the examples need to be personalized by the user.

1. *SAIL -- Stellar Atmosphere Intensity Limb* +
This subpackage can compute the stellar limb-darkening coefficients for requested targets.
+
[source, bash]
```
>>> from exotethys import sail  
>>> sail.ldc_calculate('PATH_TO_ROOT/examples/sail_example1.txt')   
```
Consult the link:user_manuals/SAIL_manual.adoc[SAIL manual].

2. *TRIP -- Transit Ring-Integrated Profile* +
This subpackage can compute transit light-curves by using stellar specific intensities rather than (approximate) limb-darkening coefficients.
+
[source, bash]
```
>>> from exotethys import trip  
>>> trip.trip_calculate('PATH_TO_ROOT/examples/trip_example1.txt')  
```
Consult the link:user_manuals/TRIP_manual.adoc[TRIP manual].

3. *BOATS -- Bias in the Occultation Analysis of Transiting Systems* +  
   This subpackage can compute the potential bias in transit/eclipse depth due to neglecting the exoplanetary flux and/or its variation with the orbital phase (common approximations). It also provides the predicted transit/eclipse depth values with the photon noise limited error bars.
+
[source, bash]
```
>>> from exotethys import boats  
>>> boats.boats_calculate_transit('PATH_TO_ROOT/examples/boats_example4.txt')  
>>> boats.boats_calculate_eclipse('PATH_TO_ROOT/examples/boats_example5.txt')  
```
Consult the link:user_manuals/BOATS_manual.adoc[BOATS manual].

4. *manage_database* +
   This subpackage can be used to manage the `.exotethys` folder that is created in your home the first time that a file is downloaded to perform a calculation. It contains 3 functions to list, copy and remove the items in this folder.
Consult the link:user_manuals/manage_database_manual.adoc[manage_database manual].


== License

This package is an open source project under GNU General Public License v3.

== References

If you use this package for your research, please consider citing the following references:

- Morello, G., Claret, A., Martin-Lagarde, M., Cossou, C., Tsiaras, A., & Lagage, P.-O. 2020, _The ExoTETHyS package: Tools for Exoplanetary Transits around Host Stars_, AJ, 159, 75 +
(Pivotal paper for the SAIL and TRIP subpackages)
- Morello, G., Claret, A., Martin-Lagarde, M., Cossou, C., Tsiaras, A., & Lagage, P.-O. 2020, _ExoTETHyS: Tools for Exoplanetary Transits around Host Stars_, JOSS, 5, 1834 +
(First official software release)
- Morello, G., Zingales, T., Martin-Lagarde, M., Gastaud, R., & Lagage, P.-O. 2020, _Phase-curve pollution of exoplanet transmission spectra_, under review +
(Pivotal paper for the BOATS subpackage)
- Martin-Lagarde, M., Morello, G., Lagage, P.-O., Gastaud, R., & Cossou, C. 2020, _Phase-curve pollution of exoplanet transit depths_, AJ, 160, 197 +
(First use of the BOATS subpackage)

If you adopt the built-in stellar model grids, please consider citing the relevant references:

MPS_Atlas_set1_2023 & MPS_Atlas_set2_2023

- Kostogryz, N., et al. 2023, RNAAS, 7, 39

Atlas_2000

- Claret, A. 2000, A&A, 363, 1081

Phoenix_2012_13 & Phoenix_drift_2012

- Claret, A., Hauschildt, P. H., & Witte, S. 2012, A&A, 546, A14
- Claret, A., Hauschildt, P. H., & Witte, S. 2013, A&A, 552, A16

Phoenix_2018

- Claret, A. 2018, A&A, 618, A20

Stagger_2018

- Chiavassa, A., et al. 2018, A&A, 611, A11 *https://pollux.oreme.org/DBPollux/PolluxAccesDB/[[3D Spectra, available publicly on POLLUX database]]*

Stagger_2015

- Magic, Z., et al. 2015, A&A, 573, A90

If you adopt the built-in instrumental passbands, please consider citing the relevant references:

_JWST_

- Pontoppidan, K. M., et al. 2016, SPIE, 9910, 991016  *https://pypi.org/project/pandeia.engine/[[Pandeia]]*
- Maszkiewicz, M. 2017, SPIE, 10564, 105642Q
- Kendrew, S., et al. 2015, PASP, 127, 623

_Spitzer_

- Hora, J. L.,  et al. 2008, PASP, 120, 1233 *https://irsa.ipac.caltech.edu/data/SPITZER/docs/irac/calibrationfiles/spectralresponse/[[NASA/IPAC]]*

_HST_

- Kuntschner, H., et al. 2011, ST-ECF Instrument Science Report WFC3-2011-05

_TESS_

- (Vanderspek, R., unreleased) *https://heasarc.gsfc.nasa.gov/docs/tess/the-tess-space-telescope.html[[NASA/TESS]]*

_Kepler_

- (Bachtell, E., and Peters, D., 2008, unreleased) *https://keplerscience.arc.nasa.gov/data-products.html[[NASA/Kepler & K2]]*


== Contributors

Developer and corresponding author

- *Giuseppe Morello* (Instituto de Astrofísica de Canarias, Spain), gmorello@iac.es, giuseppe.morello.11@ucl.ac.uk

Python support, revision and useful comments

- *Christophe Cossou* (CEA-Saclay, France)
- *Marine Martin-Lagarde* (CEA-Saclay)
- *Rene Gastaud* (CEA-Saclay)
- *Pierre Olivier-Lagage* (CEA-Saclay)
- *Angelos Tsiaras* (University College London, UK)
- *Tiziano Zingales* (Université de Bordeaux)

Database of stellar models

- *Antonio Claret* (Instituto de Astrofisica de Andalucia, Spain)
- *Andrea Chiavassa* (Observatoire de la Côte d'Azur, France)
- *Soeren Witte* (Hamburger Sternwarte, Germany)

Peer-reviewers

- *Arfon Smith* (JOSS editor)
- *Steven Murray* (Arizona State University, USA)
- *William James Handley* (University of Cambridge, UK)

Owner

JOSS Publication

ExoTETHyS: Tools for Exoplanetary Transits around host stars

Published

February 11, 2020

DOI

10.21105/joss.01834

Volume 5, Issue 46, Page 1834

Authors

Giuseppe Morello
AIM, CEA, CNRS, Université Paris-Saclay, Université Paris Diderot, Sorbonne Paris Cité, F-91191 Gif-sur-Yvette, France, INAF, Osservatorio Astronomico di Palermo, Piazza del Parlamento 1, 90134 Palermo, Italy, Dept. of Physics & Astronomy, University College London, Gower Street, WC1E 6BT London, UK

Antonio Claret
Instituto de Astrofísica de Andalucía, CSIC, Apartado 3004, 18080 Granada, Spain, Dept. Física Teórica y del Cosmos, Universidad de Granada, Campus de Fuentenueva s/n, 10871, Granada, Spain

Marine Martin-Lagarde
AIM, CEA, CNRS, Université Paris-Saclay, Université Paris Diderot, Sorbonne Paris Cité, F-91191 Gif-sur-Yvette, France

Christophe Cossou
Institut d'Astrophysique Spatiale, CNRS/Université Paris-Sud, Université Paris-Saclay, bâtiment 121, Université Paris-Sud, 91405, Orsay Cedex, France

Angelos Tsiara
Dept. of Physics & Astronomy, University College London, Gower Street, WC1E 6BT London, UK

Pierre-Olivier Lagage
AIM, CEA, CNRS, Université Paris-Saclay, Université Paris Diderot, Sorbonne Paris Cité, F-91191 Gif-sur-Yvette, France

Editor

Arfon Smith

Tags

astronomy exoplanets exoplanetary transits galactic dynamics stellar limb-darkening

View PDF Review Thread Software Archive

GitHub Events

Committers

Last synced: 7 months ago

Issues and Pull Requests

Last synced: 6 months ago

Packages