Quickstart Tutorial¶
First install the etta package (see installation instructions). Then import the package.
[2]:
import etta
All PHP wrappers in etta follow a similar pattern of usage:
Call the wrapper with the arguments taken in by the PHP function.
By default, a
pandas.DataFrameobject will be returned. If you would like anastropy.table.Tableobject instead, you can specifyoutput='astropy'. Otherwise, you can also save the result to a file by specifying the output format (csv, pipe-delimited or text) using theoutputkeyword argument and the filepath using thepathkeyword argument in your function call.
As an example, we will fetch data about TOI 127 from the TOI table using download_toi. By default, the data will be returned as a pandas object.
[3]:
etta.download_toi(toi=127)
Fetching data from https://exofop.ipac.caltech.edu/tess/download_toi.php?output=pipe&toi=127
[3]:
| TIC ID | Previous CTOI | Master | SG1A | SG1B | SG2 | SG3 | SG4 | SG5 | ACWG ESM | ... | Stellar log(g) (cm/s^2) err | Stellar Radius (R_Sun) | Stellar Radius (R_Sun) err | Stellar Metallicity | Stellar Metallicity err | Sectors | Date TOI Alerted (UTC) | Date TOI Updated (UTC) | Date Modified | Comments | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TOI | |||||||||||||||||||||
| 127.01 | 234523599 | NaN | 5 | 5 | 5 | 5 | 4 | 5 | 5 | 39.1 | ... | NaN | 0.445372 | 0.01356 | NaN | NaN | 1,2,28,29 | 2018-09-05 | 2020-11-06 | 2021-06-01 12:02:45 | HATS-71 b |
1 rows × 57 columns
You can return the result in an astropy table instead:
[4]:
etta.download_toi(toi=127, output='astropy')
Fetching data from https://exofop.ipac.caltech.edu/tess/download_toi.php?output=pipe&toi=127
[4]:
Table length=1
| TIC ID | Previous CTOI | Master | SG1A | SG1B | SG2 | SG3 | SG4 | SG5 | ACWG ESM | ACWG TSM | Time Series Observations | Spectroscopy Observations | Imaging Observations | TESS Disposition | TFOPWG Disposition | TESS Mag | TESS Mag err | Planet Name | Pipeline Signal ID | Source | RA | Dec | PM RA (mas/yr) | PM RA err (mas/yr) | PM Dec (mas/yr) | PM Dec err (mas/yr) | Epoch (BJD) | Epoch (BJD) err | Period (days) | Period (days) err | Duration (hours) | Duration (hours) err | Depth (mmag) | Depth (mmag) err | Depth (ppm) | Depth (ppm) err | Planet Radius (R_Earth) | Planet Radius (R_Earth) err | Planet Insolation (Earth Flux) | Planet Equil Temp (K) | Planet SNR | Stellar Distance (pc) | Stellar Distance (pc) err | Stellar Eff Temp (K) | Stellar Eff Temp (K) err | Stellar log(g) (cm/s^2) | Stellar log(g) (cm/s^2) err | Stellar Radius (R_Sun) | Stellar Radius (R_Sun) err | Stellar Metallicity | Stellar Metallicity err | Sectors | Date TOI Alerted (UTC) | Date TOI Updated (UTC) | Date Modified | Comments |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| int64 | float64 | int64 | int64 | int64 | int64 | int64 | int64 | int64 | float64 | float64 | int64 | int64 | int64 | str2 | str2 | float64 | float64 | float64 | int64 | str4 | str11 | str12 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | int64 | float64 | float64 | float64 | float64 | float64 | float64 | float64 | str9 | str10 | str10 | str19 | str9 |
| 234523599 | -- | 5 | 5 | 5 | 5 | 4 | 5 | 5 | 39.1 | 141.1 | 3 | 0 | 0 | KP | CP | 14.1266 | 0.006999999999999999 | -- | 1 | spoc | 01:02:12.45 | -61:45:22.08 | 78.858 | 0.087 | -27.095 | 0.064 | 2458325.6501970002 | 0.0005650000000000001 | 3.795511 | 0.00020899999999999998 | 1.959927 | 0.067449 | 56.113595 | 1.305376 | 50369.702483999994 | 1201.5728 | 10.057625999999999 | 0.386554 | 18.083279 | 525.943445 | 32.727764 | 140.225 | 0.86 | 3424 | -- | 4.438 | -- | 0.44537200000000005 | 0.01356 | -- | -- | 1,2,28,29 | 2018-09-05 | 2020-11-06 | 2021-06-01 12:02:45 | HATS-71 b |
We can also download the data onto a file, specifying the output format to be pipe-delimited (output='pipe').
[5]:
etta.download_toi(toi=127, output='pipe', path='.')
Fetching data from https://exofop.ipac.caltech.edu/tess/download_toi.php?output=pipe&toi=127
Result written to /home/jenny/TSP/.env/test-package/exofop-tess-api/docs/source/getting-started/download_toi.php?output=pipe&toi=127
It’s as easy as that!
Additional examples¶
Download all imaging observation summaries as a pandas.DataFrame object. Find and display the rows in the dataframe where the TIC ID is 468472950.
[6]:
df = etta.download_imaging()
df.loc[df['TIC ID'] == 468472950]
Fetching data from https://exofop.ipac.caltech.edu/tess/download_imaging.php?output=pipe
[6]:
| TIC ID | TIC | TOI | Telescope | Instrument | Filter | Image Type | Pixel Scale | PSF | Contrast | Obs Date | User | Group | Tag | Notes | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 16306 | 468472950 | NaN | TOI 1395 | Gemini (8 m) | NIRI | Brgamma | AO | 0.0219 | NaN | NaN | 2019-11-13 | matthews | tfopwg | 7652 | 2 visual companions: sep=0.250arcsec, pa=194.9... |
| 16307 | 468472950 | NaN | TOI 1395 | Gemini (8 m) | NIRI | K | AO | 0.0200 | NaN | NaN | 2019-11-14 | crossfield | NaN | 7518 | Quicklook: close double, 0.25arcsec SSW |
Download all spectroscopic observation summaries for tag 1494 and save to a named file. Read the resulting file. Create pandas.DataFrame object from file.
[7]:
etta.download_tag_spect(tag=1494, output='pipe', path='tag-spect-example')
with open('tag-spect-example', 'r') as file:
# Read and print the file contents (removing trailing newlines)
print('\nFILE CONTENTS:')
print(file.read().rstrip())
# Create pandas.DataFrame object from file
import pandas as pd
pd.read_csv('tag-spect-example', sep='|')
Fetching data from https://exofop.ipac.caltech.edu/tess/download_tag_spect.php?tag=1494&output=pipe
Result written to /home/jenny/TSP/.env/test-package/exofop-tess-api/docs/source/getting-started/tag-spect-example
FILE CONTENTS:
TIC ID|TIC|TOI|Telescope|Instrument|Spectral resolution|Wavelength coverage|SNR/resolution|SNR wavelength|Appropriate to PRV|Obs Date|User|Group|Tag|Notes
231702397|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
259377017|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
259962054|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
262530407|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 nm|||N|2018-12-22|feinstein||1494|
272086159|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
305048087|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|Observed at high air mass
307210830|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|Observations continued into twilight
415969908|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
439456714|||Magellan (Baade) (6.5 m)|FIRE|6000|0.82 to 2.51 microns|||N|2018-12-22|feinstein||1494|
[7]:
| TIC ID | TIC | TOI | Telescope | Instrument | Spectral resolution | Wavelength coverage | SNR/resolution | SNR wavelength | Appropriate to PRV | Obs Date | User | Group | Tag | Notes | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 231702397 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 1 | 259377017 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 2 | 259962054 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 3 | 262530407 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 nm | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 4 | 272086159 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 5 | 305048087 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | Observed at high air mass |
| 6 | 307210830 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | Observations continued into twilight |
| 7 | 415969908 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
| 8 | 439456714 | NaN | NaN | Magellan (Baade) (6.5 m) | FIRE | 6000 | 0.82 to 2.51 microns | NaN | NaN | N | 2018-12-22 | feinstein | NaN | 1494 | NaN |
Download all observing notes with tag ID 3059, and display rows modified since May 1st 2021.
[8]:
df = etta.download_obsnotes(tag=3059)
df.loc[df['Lastmod'] > '2021-05-01']
Fetching data from https://exofop.ipac.caltech.edu/tess/download_obsnotes.php?output=pipe&tag=3059
[8]:
| ID | TIC ID | Username | Groupname | TAG ID | Lastmod | notes | |
|---|---|---|---|---|---|---|---|
| 0 | 22840 | 311703724 | mlund | tfopwg | 3059 | 2021-07-29 12:01:54 | TOI3680.01:V-shaped; found in faint-star QLP s... |
| 1 | 22839 | 267373896 | mlund | tfopwg | 3059 | 2021-07-29 12:01:52 | TOI3587.01:found in faint-star QLP search; The... |
| 2 | 22838 | 180145006 | mlund | tfopwg | 3059 | 2021-07-29 12:01:51 | TOI312.01:[P=3.54112] Phil Evans observed an i... |
| 3 | 22832 | 233535738 | mlund | tfopwg | 3059 | 2021-07-28 12:02:00 | TOI4106.01:found in faint-star QLP search; The... |
| 4 | 2747 | 138968089 | mlund | tfopwg | 3059 | 2021-07-22 12:01:34 | TOI1429.01:[P=0.641256] KOI-272; [T0 updated f... |
| ... | ... | ... | ... | ... | ... | ... | ... |
| 396 | 22035 | 117789567 | mlund | tfopwg | 3059 | 2021-05-15 12:01:24 | TOI1149.01:[P=2.32063] FIES observation reveal... |
| 397 | 22033 | 424435940 | mlund | tfopwg | 3059 | 2021-05-15 12:01:24 | TOI1627.01:WASP-58b; Master Disp: KP, Phot Dis... |
| 398 | 22026 | 180991313 | mlund | tfopwg | 3059 | 2021-05-15 12:01:23 | TOI2330.01:WASP 128b - 37 Mjup; Master Disp: ... |
| 399 | 22027 | 155001079 | mlund | tfopwg | 3059 | 2021-05-15 12:01:23 | TOI2434.01:DaveL: The first TRES Observation r... |
| 400 | 22025 | 8400842 | mlund | tfopwg | 3059 | 2021-05-15 12:01:23 | TOI1676.01:XO-3b; Master Disp: KP, Phot Disp:... |
401 rows × 7 columns
Download targets near TIC 278683839, sorted by separation.
[9]:
etta.download_nearbytarget(278683839, sort='separation')
Fetching data from https://exofop.ipac.caltech.edu/tess/download_nearbytarget.php?output=pipe&sort=separation&id=278683839
[9]:
| TOI | RA | Dec | TESS Mag | GAIA DR2 | GAIA Mag | Distance(pc) | Distance Err (pc) | PM RA (mas/yr) | PM RA Err (mas/yr) | PM Dec (mas/yr) | PM Dec Err (mas/yr) | Separation (arcsec) | Position Angle (deg E. of N.) | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| TIC ID | ||||||||||||||
| 278683839 | NaN | 06:36:52.66 | -58:01:36.78 | 17.7210 | 5.484358e+18 | 18.372500 | 1857.6300 | 549.5850 | -1.261630 | 0.291142 | 6.94524 | 0.385658 | 0.00 | 0.00 |
| 737400069 | NaN | 06:36:54.39 | -58:01:37.07 | 19.8590 | 5.484346e+18 | 20.561400 | 1109.1800 | 735.3020 | 1.230050 | 1.389270 | 5.76244 | 2.026930 | 13.62 | 91.24 |
| 737400524 | NaN | 06:36:51.54 | -58:01:24.13 | 18.8582 | 5.484358e+18 | 19.908300 | 1299.8900 | 716.4240 | -0.253550 | 0.811719 | -4.00525 | 1.221810 | 15.70 | 324.88 |
| 278683836 | NaN | 06:36:51.71 | -58:01:57.62 | 16.4952 | 5.484346e+18 | 17.171800 | 1787.8900 | 244.3150 | 1.148980 | 0.137737 | 5.87397 | 0.174472 | 22.05 | 199.82 |
| 278683837 | NaN | 06:36:49.09 | -58:01:55.35 | 16.3578 | 5.484358e+18 | 17.011800 | 1328.4900 | 135.2700 | 1.630270 | 0.127436 | 17.44110 | 0.170934 | 33.95 | 236.80 |
| 278683840 | NaN | 06:36:57.57 | -58:01:29.64 | 16.2782 | 5.484346e+18 | 17.494600 | 335.0200 | 10.8830 | 4.711510 | 0.185457 | -23.28290 | 0.212447 | 39.51 | 79.63 |
| 278683835 | NaN | 06:36:57.46 | -58:02:03.66 | 16.7609 | 5.484346e+18 | 17.304900 | 2609.0000 | 529.3100 | -1.273080 | 0.149156 | 5.12392 | 0.192750 | 46.41 | 125.19 |
| 278683844 | 119.0 | 06:36:57.22 | -58:00:58.15 | 9.2789 | 5.484358e+18 | 9.820911 | 66.6187 | 0.1003 | 51.496900 | 0.041663 | -205.60000 | 0.049415 | 52.99 | 43.18 |
| 737400067 | NaN | 06:36:56.28 | -58:02:23.79 | 17.4752 | 5.484346e+18 | 17.965500 | 3566.4900 | 964.7700 | 1.390850 | 0.220959 | 6.87784 | 0.307795 | 54.85 | 148.57 |
| 278683834 | NaN | 06:36:49.29 | -58:02:25.18 | 15.6266 | 5.484346e+18 | 16.664200 | 416.1930 | 8.9760 | 5.831520 | 0.101817 | 6.28829 | 0.135095 | 55.23 | 208.92 |
| 278683838 | NaN | 06:36:59.79 | -58:01:43.29 | 18.2350 | NaN | NaN | NaN | NaN | NaN | NaN | NaN | NaN | 56.86 | 96.55 |
| 737400070 | NaN | 06:36:59.79 | -58:01:43.28 | 18.5228 | 5.484346e+18 | 19.598900 | 795.8020 | 340.1850 | -8.540880 | 0.679449 | 6.04446 | 1.012590 | 56.86 | 96.55 |
| 278683846 | NaN | 06:36:51.39 | -58:00:39.96 | 15.9036 | 5.484358e+18 | 16.419300 | 1866.5800 | 168.6950 | -0.712302 | 0.091340 | 7.04877 | 0.114378 | 57.91 | 349.94 |
| 278683842 | NaN | 06:36:46.01 | -58:01:09.26 | 13.1419 | 5.484358e+18 | 13.611800 | 770.4610 | 9.3605 | 6.401700 | 0.031504 | 9.66757 | 0.036210 | 59.80 | 297.51 |