SHERLOCK (Searching for Hints of Exoplanets fRom Lightcurves Of spaCe-based seeKers; Pozuelos et al. 2020) is a friendly-user open-source package that has five different modules that allow to: (1) search for planetary candidates; (2) perform vetting of the most promising signals; (3) compute a statistical validation; (4) model the signals to refine the ephemerids; and (5) compute the observational windows from ground-based observatories. SHERLOCK has direct access to short- and long-cadence data observed by Kepler/K2 and TESS. Hence, SHERLOCK is a fully operational powerful tool that allows the user to perform planet searches in space-based data robustly. In most of cases the user only needs to provide with a KIC-ID, EPIC-ID, TIC-ID or coordinates of the host star where wants to search for exoplanets.
We are currently working in a specific article for SHERLOCK. In addition, the best curent way to cite SHERLOCK is by referencing the first paper where it was firstly used (Pozuelos et al. 2020):
@ARTICLE{2020A&A...641A..23P,
author = {{Pozuelos}, Francisco J. and {Su{\'a}rez}, Juan C. and {de El{\'\i}a}, Gonzalo C. and {Berdi{\~n}as}, Zaira M. and {Bonfanti}, Andrea and {Dugaro}, Agust{\'\i}n and {Gillon}, Micha{\"e}l and {Jehin}, Emmanu{\"e}l and {G{\"u}nther}, Maximilian N. and {Van Grootel}, Val{\'e}rie and {Garcia}, Lionel J. and {Thuillier}, Antoine and {Delrez}, Laetitia and {Rod{\'o}n}, Jose R.},
title = "{GJ 273: on the formation, dynamical evolution, and habitability of a planetary system hosted by an M dwarf at 3.75 parsec}",
journal = {\aap},
keywords = {planets and satellites: dynamical evolution and stability, planets and satellites: formation, Astrophysics - Earth and Planetary Astrophysics, Astrophysics - Solar and Stellar Astrophysics},
year = 2020,
month = sep,
volume = {641},
eid = {A23},
pages = {A23},
doi = {10.1051/0004-6361/202038047},
archivePrefix = {arXiv},
eprint = {2006.09403},
primaryClass = {astro-ph.EP},
adsurl = {https://ui.adsabs.harvard.edu/abs/2020A&A...641A..23P},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}
Active: F.J. Pozuelos, M. Dévora
A. Thuillier & L. García & Luis Cerdeño Mota
Please visit https://sherlockpipe.readthedocs.io to get a complete set of explanations and tutorials to get started with SHERLOCK.
You can run SHERLOCK PIPEline as a standalone package by using:
python3 -m sherlockpipe --properties my_properties.yaml
You only need to provide a YAML file with any of the properties contained in the internal
properties.yaml
provided by the pipeline. The most important keys to be defined in your YAML file are those under
the GLOBAL OBJECTS RUN SETUP
and SECTOR OBJECTS RUN SETUP
sections because they contain the object ids
or files to be analysed in the execution. You'd need to fill at least one of those keys for the
pipeline to do anything. If you still have any doubts please refer to the
examples/properties directory
Additionally, you could only want to inspect the preparation stage of SHERLOCK and therefore, you can execute it without running the analyse phase so you can watch the light curve, the periodogram and the initial report to take better decisions to tune the execution parameters. Just launch SHERLOCK with:
python3 -m sherlockpipe --properties my_properties.yaml --explore
and it will end as soon as it has processed the preparation stages for each object.
SHERLOCK uses third party data to know TOIs, KOIs, EPICs and to handle FFIs and the vetting process. This data gets frequently updated from the active missions and therefore SHERLOCK will perform better if the metadata gets refreshed. You can simply run:
python3 -m sherlockpipe.update
and SHERLOCK will download the dependencies. It will store a timestamp to remember the last time it was refreshed to prevent several unneeded calls. However, if you find that there are more updates and you need them now, you can call:
python3 -m sherlockpipe.update --force
and SHERLOCK will ignore the timestamps and perform the update process. In addition, you could be interested in wiping all the metadata and build it again. That's why you could execute:
python3 -m sherlockpipe.update --clean
This last command implies a force
statement and the last executed time will be ignored too.
You can additionally let SHERLOCK refresh the OIs list before running your current execution by adding to the YAML file the next line:
UPDATE_OIS=True
SHERLOCK PIPEline comes with a submodule to examine the most promising transit candidates found by any of its executions. This is done via LATTE and TPFPlotter. Please note that this feature is only enabled for TESS candidates. You should be able to execute the vetting by calling:
python3 -m sherlockpipe.vet --properties my_properties.yaml
Through that command you will run the vetting process for the given parameters within your provided YAML file.
You could watch the generated results under $your_sherlock_object_results_dir/vetting
directory.
Please go to
examples/vetting/
to learn how to inject the proper properties for the vetting process.
There is an additional simplified option which can be used to run the vetting. In case you are sure there is a candidate from the Sherlock results which matches your desired parameters, you can run
python3 -m sherlockpipe.vet --candidate ${theCandidateNumber}
from the sherlock results directory. This execution will automatically read the transit parameters from the Sherlock generated files.
SHERLOCK PIPEline comes with another submodule to fit the most promising transit candidates found by any of its executions. This fit is done via ALLESFITTER code. By calling:
python3 -m sherlockpipe.fit --properties my_properties.yaml
you will run the fitting process for the given parameters within your provided YAML file.
You could watch the generated results under $your_sherlock_object_results_dir/fit
directory.
Please go to
examples/fitting/
to learn how to inject the proper properties for the fitting process.
There is an additional simplified option which can be used to run the fit. In case you are sure there is a candidate from the Sherlock results which matches your desired parameters, you can run
python3 -m sherlockpipe.fit --candidate ${theCandidateNumber}
from the sherlock results directory. This execution will automatically read the transit and star parameters from the Sherlock generated files.
SHERLOCK PIPEline implements a module to execute a statistical validation of a candidate by the usage of TRICERATOPS. By calling:
python3 -m sherlockpipe.validate --candidate ${theCandidateNumber}
you will run the validation for one of the Sherlock candidates.
SHERLOCK PIPEline also implements a module to execute a system stability computation by the usage of Rebound and SPOCK. By calling:
python3 -m sherlockpipe.stability --bodies 1,2,4
where the --bodies
parameter is the set of the SHERLOCK accepted signals as CSV to be used in the scenarios
simulation. You can also provide a
stability properties file)
to run a custom stability simulation:
python3 -m sherlockpipe.stability --properties stability.yaml
and you can even combine SHERLOCK accepted signals with some additional bodies provided by the properties file:
python3 -m sherlockpipe.stability --bodies 1,2,4 --properties stability.yaml
The results will be stored into a stability
directory containing the execution log and a stability.csv
containing one line per simulated scenario, sorted by the best results score.
SHERLOCK PIPEline also adds now a tool to plan your observations from ground-based observatories by using astropy and astroplan. By calling:
python3 -m sherlockpipe.plan --candidate ${theCandidateNumber} --observatories observatories.csv
on the resulting sherlockpipe.fit
directory, where the precise candidate ephemeris are placed.
The observatories.csv
file should contain the list of available observatories for your candidate follow-up.
As an example, you can look at
this file.
It is important to note that SHERLOCK PIPEline uses some csv files with TOIs, KOIs and EPIC IDs from the TESS, Kepler and K2 missions. Therefore your first execution of the pipeline might take longer because it will download the information.
The light curve for every input object needs to be obtained from its mission database. For this we use the high level API of Lightkurve, which enables the download of the desired light curves for TESS, Kepler and K2 missions. We also include Full Frame Images from the TESS mission by the usage of ELEANOR. We always use the PDCSAP signal from the ones provided by any of those two packages.
In many cases we will find light curves which contain several systematics like noise, high dispersion beside the borders, high-amplitude periodicities caused by pulsators, fast rotators, etc. SHERLOCK PIPEline provides some methods to reduce these most important systematics.
For local noise, where very close measurements show high deviation from the local trend, we apply a Savitzky-Golay filter. This has proved a highly increment of the SNR of found transits. This feature can be disabled with a flag.
Sometimes the spacecrafts have to perform reaction wheels momentum dumps by firing thrusters, sometimes there is high light scattering and sometimes the spacecraft can infer some jitter into the signal. For all of those systematics we found that in many cases the data from those regions should be discarded. Thus, SHERLOCK PIPEline includes a binned RMS computation where bins whose RMS value is higher than a configurable factor multiplied by the median get automatically masked. This feature can be disabled with a flag.
If enabled, this feature automatically disables High RMS areas masking for the assigned object. The user can input an array of time ranges to be masked into the original signal.
Our most common foes with high periodicities are fast-rotators, which infer a high sinusoidal-like trend in the PDCSAP signal. This is why SHERLOCK PIPEline includes an automatic high-amplitude periodicities detection and detrending during its preparation stage. This feature can be disabled with a flag.
If enabled, this feature automatically disables Detrend of high-amplitude periodicities for the assigned object. The user can input a period to be used for an initial detrend of the original signal.
You can even inject your own python code to perform:
- A custom signal preparation task by implementing the
CurvePreparer
class that we provide. Then, inject your python file into the
CUSTOM_PREPARER
property and let SHERLOCK use your code. - A custom best signal selection algorithm by implementing the
SignalSelector.
class that we provide. Then, inject your python file into the
CUSTOM_ALGORITHM
property and let SHERLOCK use your code. - A custom search zone definition by implementing the
SearchZone.
class that we provide. Then, inject your python file into the
CUSTOM_SEARCH_ZONE
property and let SHERLOCK use your code. - Custom search modes: 'tls', 'bls', 'grazing', 'comet' or 'custom'. You can search for transits by using TLS, BLS, TLS for a grazing template, TLS for a comet template or even inject your custom transit template (this is currently included as an experimental feature).
For better understanding of usage please see the examples, which references custom implementations that you can inspect in our custom algorithms directory