# TESS-ExoClass (TEC)
TESS exoplanet detection filter, crossmatch, classifier, and ranker.

### Problem:
Your transiting planet detection pipeline results in a huge pile of detections.  Now What?  Do I really have to look at all these manually!?

### Answer:
No!  Algorithmic filtering and classifying is available with TESS-ExoClass (TEC).

### Authors:
Christopher J Burke (MIT), Jeffrey Coughlin (SETI/NASA Ames), Susan Mullally (STScI), Aylin Garcia Soto (MIT), Fergal Mullally (SETI), Jessie Christiansen (NExSci)

### Results:
Sector Number | Detection Source | Result Tables | Summary PDFs
------------- | ---------------- | ------------- | ------------
3 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/lakbewewji4ieap/AABT-7AquQRV4u1RwBwhvz_Ea?dl=0) | [PDFs](https://www.dropbox.com/sh/pd0lsf5u5uk7qil/AABc2UrZcdI75VExtkDmkLqpa?dl=0)
4 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/crkk010kl0rjp9z/AACfSft-gQckJZFTd-4F9_Yta?dl=0) | [PDFs](https://www.dropbox.com/sh/gq7shwdw2pi1xjv/AADQCc1H9yIrd99mwPdADynoa?dl=0)
1-3 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/im6pg6uepelt0dw/AADm7VH_PYKriETXda080yIRa?dl=0) | [PDFs](https://www.dropbox.com/sh/sf2qiw708z6fgvb/AAALmpgUqP6DrTf2VtlYgF7Fa?dl=0)
5 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/0ejf3rc0fneizq7/AAAzti3PoskfWLlAcTrMbHzza?dl=0) | [PDFs](https://www.dropbox.com/sh/7fvfusjsa00gua1/AAC--PPZHcPfrSrp3HaJYq5ja?dl=0)
6 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/hqvx611hfwvqvlx/AAAs60DnbHbw7Q-mWabj2nRRa?dl=0) | [PDFs](https://www.dropbox.com/sh/wuvqhal09wgeqo4/AACGgNO9_LFdTLlc68mM1f4Aa?dl=0)
7 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/oklvc0252wmujop/AABVPo7tIG3QLyBiLCJ2GpR7a?dl=0) | [PDFs](https://www.dropbox.com/sh/f9uik54x6fkigc6/AADARhv-hCp0Wy_il8iM3pSFa?dl=0)
8 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/cbgr3s5gv4a0z77/AAANc4bG-ccGkKJrtr9RZcBca?dl=0) | [PDFs](https://www.dropbox.com/sh/mui5ed55357wxb0/AADzDByf4fQlniLDkt68PU6ka?dl=0)
1-6 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/v2d9u38ihqju6mt/AAA-0CgEkZbn5AG_3HY2S9laa?dl=0) | [PDFs](https://www.dropbox.com/sh/pxrblejzwvr5ipx/AACrJ3J0eKhXthICwnbuDJkWa?dl=0)
9 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/3zpriterx9e221v/AABLWqybtBBXLnKPY9p7EF_Wa?dl=0) | [PDFs](https://www.dropbox.com/sh/n23lt6j6hddf9fz/AABYEt63n4sypgdnRt7I-lWma?dl=0)
1-9 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/h3zcqv1oinhfu6d/AADDVnIHD8yGtCGh1dnhv7zua?dl=0) | [PDFs](https://www.dropbox.com/sh/dt85mcpxay877tr/AABcBfFlTw_jjeRd6Wd4JypFa?dl=0)
10 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/9qirgbb3jamj9q3/AAAXBXOUcZaS--ar4url2YjJa?dl=0) | [PDFs](https://www.dropbox.com/sh/oeunwrojn47p50l/AABovyizVu0rbfws-1a3li17a?dl=0)
11 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/nyjxz2g5ejqunwx/AABDcKP8uKp1f9EwFNaHxbcDa?dl=0) | [PDFs](https://www.dropbox.com/sh/1hddeqppdcn2kcw/AAA5s1iSX5jf_ofV8OH5hGxZa?dl=0)
12 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/fls1y2bk9mfuzw9/AADjVSDETidK72ES4e26p0pia?dl=0) | [PDFs](https://www.dropbox.com/sh/55ljots0pwfxon0/AACFtrboiKwHhWCtiCO2JxaDa?dl=0)
13 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/kbokgvu4o515jev/AAAEmRJF8fhLyUS5NKfRR3rna?dl=0) | [PDFs](https://www.dropbox.com/sh/ljnwvqyyfpguhzm/AACDzFGg7QXgg4D2bCv6WeEJa?dl=0)
1-13 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/uqgvjfz4374wpuu/AADPYdH9VBbyzmBNlPDq4u5ja?dl=0) | [PDFs](https://www.dropbox.com/sh/kxhwuzf6rm43dn8/AABEIOuJKucogdTquH57Mezya?dl=0)
14 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/t4n08vjfo5zivcj/AADtaxrlEe0xU5o5H_0oKwUQa?dl=0) | [PDFs](https://www.dropbox.com/sh/kcjvizdcuuniojg/AAATQ8jaLzQ7tbEN91bZ6ZsWa?dl=0)
15 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/gn060e1casbf8n3/AAAB27PhBuw0I-I_GqRSrSmRa?dl=0) | [PDFs](https://www.dropbox.com/sh/idqdbc5vrhaycv6/AAD5mUXP1NGcsSoDJBs8u-yFa?dl=0)
16 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/2lxkzaus3ckjgjk/AADX_g2l12ZYbOEAXYz3GCYAa?dl=0) | [PDFs](https://www.dropbox.com/sh/393xkxa630bxk8x/AAA9FKthhic6FXJuZPJxgf_ca?dl=0)
14-16 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/fqw34bu7i0vglwc/AADdDW4BMro2-D4EPnRQUZPXa?dl=0) | [PDFs](https://www.dropbox.com/sh/hxhrp4jhj5j3izp/AABpt98Iawot0_PbpQ7UqeVda?dl=0)
17 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/jdq9aivncccu422/AAAjuWd1cw4pIG1aBFOGF4iDa?dl=0) | [PDFs](https://www.dropbox.com/sh/j3qoe1xqlli3m5i/AADUFzUsMFz8OYkRr0Uwho0ka?dl=0)
18 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/v8078hvjultba40/AAB5u1wdN-Ic19Zm1brZDSaBa?dl=0) | [PDFs](https://www.dropbox.com/sh/370p2yrdpj1own3/AACDXx_xoPaOP7qgBkTGpz_Ca?dl=0)
19 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/9wxe4udds78i87z/AAAUnurk-6dz3wpO8gT-Mmdqa?dl=0) | [PDFs](https://www.dropbox.com/sh/5q42m43enqhphb3/AAColzHkdtPEw01t3sPj1nzta?dl=0)
14-19 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/bhkof532xwq10jb/AAALhx1qSycK6oZQUKx6f83ja?dl=0) | [PDFs](https://www.dropbox.com/sh/fcpth31emw24yb7/AADJ6FIGjRYjyTLqkx9a16ZJa?dl=0)
20 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/dwkpepofu6cipb3/AAAG2XBJwIf3mihsXfgOyMsSa?dl=0) | [PDFs](https://www.dropbox.com/sh/rdxzgkq73c2gy94/AADPGUpy7X6EOzQIdMpvHlk5a?dl=0)
21 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/f1cwcmu7j9ri6t8/AAAx_DzQ2U8Ay3zSkHCbx6sQa?dl=0) | [PDFs](https://www.dropbox.com/sh/l82fhsl6fw0s8fp/AACNK-U2y0Vsmz-dfngn1uIha?dl=0)
22 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/dieplixalgmk1k7/AACore6bHx9tJVKp8nM1j12ya?dl=0) | [PDFs](https://www.dropbox.com/sh/a4xhxf28ypt769z/AABtfu8ZW1ubljxs8KY2-idpa?dl=0)
23 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/swu31qwze59xdnp/AACSx4AlcRMw6VhztjkxIQ3Za?dl=0) | [PDFs](https://www.dropbox.com/sh/nuavy12gvzgrczs/AADvlenvYOqH7X76FHkSMdVta?dl=0)
14-23 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/2xec8wq4tdrsz86/AADUAqYRj3hxU5-MKh9NYJwAa?dl=0) | [PDFs](https://www.dropbox.com/sh/sppyl0x2g1jup3p/AABVfp8cm6p_JCWTX_KBNC4oa?dl=0)
24 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/i5iwksucelxatm2/AAC3YnvxLR6pugxvG7oErKn8a?dl=0) | [PDFs](https://www.dropbox.com/sh/0uso08z82n87tvc/AAAQkm8PB9strJ2ofgX5-DnJa?dl=0)
25 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/kkjwpn0mvkizwcc/AACd-Nct-NTrKSfyIdwkJD7xa?dl=0) | [PDFs](https://www.dropbox.com/sh/prj7z7kwjfqkfbz/AAD-KIqWgl2ab7XNpl5mpiI3a?dl=0)
26 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/d7j668pdujqtnu9/AAC_jo9ZZruwysnxo03R3mwta?dl=0) | [PDFs](https://www.dropbox.com/sh/orh3q4qsti2wegm/AAARHK8wyg9YK5RxJRg_Gtxta?dl=0)
14-26 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/q4rzbjjr5b0ncxp/AAApZfGp-L5a_oAm4gOXpoY1a?dl=0) | [PDFs](https://www.dropbox.com/sh/ct3y5d1rkn6ks4l/AAA0MUbZQmzscpDK2xoWyOzJa?dl=0)
27 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/m4tje3lxwbxz714/AACwoRbD17gHlvnOTpAgXD72a?dl=0) | [PDFs](https://www.dropbox.com/sh/era6ekgdsuwzhwb/AADBSU2gyKDia1n2MQXd1ds_a?dl=0)
28 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/kppd54fafchoyn9/AABCpnhSOL6P9MW_8WXaUKW-a?dl=0) | [PDFs](https://www.dropbox.com/sh/md3og74k5ps8v3r/AAAOWug77W6QOPEG-8oJtRSma?dl=0)
29 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/t12k0no7colfasy/AABw6B7LtRVvVY11olQaJuxia?dl=0) |[PDFs](https://www.dropbox.com/sh/xb80u54k5jq44r2/AADyFte0Y7JlrvEs6OIbfruUa?dl=0)
30 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/lr8vf8hglduhvii/AADEnBlhifWvtnsEmzhRWAxxa?dl=0) | [PDFs](https://www.dropbox.com/sh/yxtzj74rl9bnqae/AADktyhPfrralCjlTpyC0Ayda?dl=0)
31 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/avw6mnpqgi1d1qn/AABcNy0bQLNP-IdSF7tJzlrua?dl=0) | [PDFs](https://www.dropbox.com/sh/btuiyj0skvi0wgo/AAC8Zj1VCPBsC--Cwr_YZ6-0a?dl=0)
32 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/2a8adbmnkrba8ij/AADfx4ROru831GwzhycuFijqa?dl=0) | [PDFs](https://www.dropbox.com/sh/gk40f0cc5jslrro/AADFCdvPyVNOSBfw0_kjRv6Qa?dl=0)
33 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/lnuz18p1e9ew0nk/AAD1QCxo0s04a-sBzrP7Lnoza?dl=0) | [PDFs](https://www.dropbox.com/sh/j41zsvftkrc7a61/AABKtZKycFuHbXuDpeSqmoN-a?dl=0)
34 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/siigp607qufnqb6/AABjFy2cIaus3l1OcOGlNUXda?dl=0) | [PDFs](https://www.dropbox.com/sh/1of470r7f0xz0l3/AAADebCkqJG9_uh6LzmuFA8Da?dl=0)
35 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/1xwtd04qt608r6k/AABOpu4UkfiJ5uMjRWm3lUiqa?dl=0) | [PDFs](https://www.dropbox.com/sh/8t7xdmi7tlt15pg/AADWAcYGLjFBFmOpXayGJq9ga?dl=0)
36 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/3rkaleqwju3u8mb/AAA9aGXp6aCsI0MZxJcMncrva?dl=0) | [PDFs](https://www.dropbox.com/sh/yrsuu26vmecu46h/AAAeqcxOzAW5rF2sGEE-TMcFa?dl=0)
37 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/juwm0vf1hpaipac/AAAYe1HfAisetqqnq5J9J_5_a?dl=0) | [PDFs](https://www.dropbox.com/sh/ag2qrd9g2yu626y/AACR803poj210xP5kqEQ1J2Ha?dl=0)
1-36 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/21khkjgqk8uf1jt/AABh36KZVmuE1jWOgzyz3Wp2a?dl=0) | [PDFs](https://www.dropbox.com/sh/yxokp6co3azcpr6/AABfGBS6jLvk4SiEXEa3aq7pa?dl=0)
38 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/pyl6tau2vkub9gz/AACaNLqH-_kPXiO0nqLZd_dTa?dl=0) | [PDFs](https://www.dropbox.com/sh/312k736s7ynckil/AACUujwJRU_spJmjlD0LejTPa?dl=0)
39 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/3umpaoyuloeanwz/AACa0Uw-EnKRlkv8kLtkozu0a?dl=0) | [PDFs](https://www.dropbox.com/sh/gwtl10poh08m8i1/AABp7Ia8lE3mxj5xIuIrSKxRa?dl=0)
40 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/pj5s55v41i8u1ht/AACAuic8apBkxdvYS8WKm6q8a?dl=0) | [PDFs](https://www.dropbox.com/sh/gn49msjz93nunay/AABGmsJ6Uhzp44WGMojKACBRa?dl=0)
1-39 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/ifgu9uubckhofdd/AABCqMHDWKrmXXCWpZ8uclCla?dl=0) | [PDFs](https://www.dropbox.com/sh/mjoaa9rug0y5cfm/AAB-PYKruqeRzKYGddfFAK_xa?dl=0)
41 | NASA Ames SPOC TCE | [Tables](https://www.dropbox.com/sh/phfna5575qg86lz/AAC1tgoBMWErgoCrnItnKO-Za?dl=0) | [PDFs](https://www.dropbox.com/sh/av0ngkkkdxfygbq/AACqDlPfTl6l6TeVdI6bUzoMa?dl=0)


### Description:
TEC gets you from your pile of signal detections to your best transiting planet candidate science faster.  TEC builds off the highly successful Kepler Robovetter classification process ([Coughlin et al. 2016](http://adsabs.harvard.edu/abs/2016ApJS..224...12C), [Thompson et al. 2018](http://adsabs.harvard.edu/abs/2018ApJS..235...38T)) as well as the [DAVE](http://keplertcert.seti.org/DAVE/) K2 vetting tools ([Kostov et al. 2019](http://adsabs.harvard.edu/abs/2019arXiv190107459K)).  TEC is actually neither of those more mature efforts (yet).  TEC is actually the foundation underlying those classifiers.  In other words TEC is the database of attributes/metrics that generically feed any kind of machine learning or classification process.  For instance, the Kepler Robovetter examined a database of ~50 metrics in order for it to carry out its decision tree based classifications.  TEC is currently focused on developing the database of attributes/metrics that can provide more sophisticated classifications using machine learning techniques.  TEC currently uses a crude decision tree like classifier that is tuned manually in order to match the efficacy of the current manual vetting effort to build the MIT TOI alerts.

### What does TEC enable:
- Observing the best candidates: TEC provides a filtered and ranked list of the most viable detections to get you to the 'gem' planet candidates quickly.  In practice, TEC has demonstrated that the number of viable detections can be reduced by a factor of six from the original detections.
- Machine learning attributes and training sets: All machine learning algorithms begin with a database of attributes/metrics.  You can use TEC to enhance the current set of attributes that you have developed or you can use the currently crude classifications from TEC to enhance your training set.
- Statistical Validation: Do you want to statistically validate your lowest signal to noise ratio (SNR) detections?  Then you need to quantify the reliability of your detections and classification.  [Mullally et al. (2018)](http://adsabs.harvard.edu/abs/2018AJ....155..210M) and [Burke et al. (2019)](http://adsabs.harvard.edu/abs/2019arXiv190100506B) recently have shown that important Kepler statistical validations (such as Kepler-452b and Kepler-186f) are not as statistically significant as previously thought without taking into account the possibility that they could be false alarm/systematic detections.  TEC enables automating the classification thus one can provide TEC examples of systematics in order to demonstrate whether reliability is an issue for the lowest SNR detections.
- Planet Occurrence Rates: Are you one of the brave souls that wants to calculate unbiased planet occurrence rates based on TESS data?  You need automated classifications in order to quantify how this step influences the recovered planets.
- Your Pipeline Here: I have my own planet search pipeline, and my own large pile of detections.  Help!  Without too much work providing a flux-time series and detection ephemeris you can run TEC for your own pipeline.

### STATUS:
TEC is a very, very much work in progress from a coding and workflow standpoint.  However, TEC is producing filtered and ranked list of candidates from the TESS produced NASA Ames SPOC Threshold Crossing Events (TCEs) along with summary documents for each detection that TEC deems worthy of attention.  So, even if you ignore the codes, TEC currently can provide a high fidelity list of the most promising planet candidates for observing follow-up, machine learning training sets, or benchmark to your own efforts.  The TOI alerts (focused on providing the most reliable candidates for the TESS prime mission) are a heavily filtered set of candidates.  TEC provides a more thorough search to lower SNR levels and classifications for all TCEs from the NASA Ames pipeline.

From an attribute/metric standpoint most of the flux-level metrics from the Kepler Robovetter are available with TEC.  The notable exceptions are LPP ([Thompson et al. 2015](http://adsabs.harvard.edu/abs/2015ApJ...812...46T)) and Marshall ([Mullally et al. 2016](http://adsabs.harvard.edu/abs/2016PASP..128g4502M)).  Those missing metrics do have publicly available algorithms under the [DAVE](https://github.com/barentsen/dave) project and will potentially be implemented in future TEC updates.  Pixel-level centroid analysis does not exist in TEC yet, and won't for sometime.  There is an effort to independently calculate in-transit difference images, but that is under developement.  TEC relies on the centroid analysis from the NASA Ames pipeline to warn about possible centroid shifts during transit.  The DAVE project is potentially gearing up for more detailed pixel level analysis that I encourage those interested to follow the DAVE project.

### TEC Outputs:
TEC currently consists of 5 primary outputs that are of most interest to the community.  The columns and format of the files are described in doc/TESS-ExoClass_File_Guide.txt
1. Triage list - Based upon a limited set of metrics that are simple, efficient, and robustly deal with 'junky' candidates, TEC does a triage filter on the NASA Ames TCEs.  This is a hard filter in that TCEs that do not pass the TEC triage filter do not get a TEC summary report and do not have the more detailed metrics calculated.  From a classification standpoint, the TCEs that do not pass this filter should be considered instrumental and/or stellar variability in nature.  The TCEs that pass the triage are considered viable transiting planet candidates and/or detached stellar eclipsing binaries.  Contact binaries that are not detached (detached EBs have a flat stable normalized flux time series in between the eclipses) tend to not pass the triage filter stage.
2. Tier 1 list - List of most promising planet candidates that pass the triage filter and all the additional metrics indicate that the signals are consistent with a planet candidate on the target.  In addition, the Tier 1 list is ranked by a heuristic value that gives higher rank to planet candidates that have brighter hosts, smaller radii, lower insolation flux, and etc...(quantities most suitable for follow up).  In addition, the Tier 1 list provides a flag as to whether the planet candidate is previously known from the confirmed planet list hosted by the NASA Exoplanet Archive or a previously known TOI.  End users (especially observers making plans for a telescope) are still encouraged to perform due diligence and manually examine the summary report pdf in order to confirm that the planet candidate is viable.
3. Tier 2 list - List of planet candidates that pass the triage filter, but one or more metrics indicate an issue with the signal that raises concern the signal is not a planet candidate or the signal is not on the primary target of interest (evidence for a centroid offset).  The Tier 2 list is a similarly ranked list as Tier 1, but contains a flag string to indicate which metric has raised concern.  End users are encouraged to examine the summary report pdf in order to provide a judgement as to whether the metric of concern is significant and calculated in a valid manner.  Some of the metrics can have false negatives and be good clean planet candidates.
4. Tier 3 list - List of probable stellar eclipsing binaries.  In particular, this list contains signals with eclipses and a significant secondary that is not due to a planet.
5. Summary report - Users of the [Kepler TCERT Vetting Reports](https://exoplanetarchive.ipac.caltech.edu/docs/KSCI-19105-001.pdf) from the Kepler Science Office will feel right at home with the TEC summary reports.  The TEC summary report repeats the SPOC DV summary and includes the additional information calculated in TEC such as the very helpful [model shift test](https://github.com/JeffLCoughlin/Model-Shift), SPOC centroid information, and a prototype for an independent difference image calculation.

### Documentation
The doc folder has documentation that describes the columns for the TEC outputs, a semi-thorough step-by-step guide for running TEC on the NASA Ames SPOC TCEs along with hints for implementing TEC codes for your own pipeline results.

### Code
TEC code is in the code folder.  It is primarily python.  See doc/tess-exoclass_opsnotes_s04.txt for the guide for running the code for the NASA Ames SPOC TCEs with data products available at MAST.

 
