Product Description

1. Introduction

LcTools is a Windows based set of applications designed for processing TESS, K2, and Kepler lightcurves in addition to lightcurves for the TESS-TASOC, K2SFF, and K2-EVEREST High Level Science Products (HLSPs) at MAST. The system consists of the following applications:

Application Purpose
LcViewer Build, view, detrend, edit, and phase fold lightcurves. Detect, record, display, and analyze signals of interest.
LcSignalFinder Automatically detect and record periodic signals found in a large set of lightcurve files.
LcGenerator Build lightcurve files in bulk for use by LcViewer and LcSignalFinder.
LcStacker Combine a set of phase folded lightcurve files into a stacked lightcurve file for subsequent use with LcViewer.
LcStackAnalyzer Determine the contribution of each phase folded lightcurve file to a reference signal in a stacked lightcurve file.
LcReporter Create an Excel report listing the user defined signals recorded with LcViewer.

A detailed description of each application is provided below.

2. LcViewer

2.1 Overview

LcViewer is a combined lightcurve viewer and signal processor designed to help detect, measure, and record signals of interest found in TESS, K2, and Kepler lightcurves and associated HLSPs. Using LcViewer, lightcurves may be generated, viewed, detrended, edited, and phase folded. The product provides an advanced suite of navigation controls for selecting, panning, and zooming a lightcurve in a fast and efficient manner using several different techniques.

The most powerful feature of the product is its ability to handle signals. Loosely defined, a signal is three or more data points in a lightcurve that represents some astrophysical phenomenon or lightcurve anomaly. Examples of the former include eclipsing binaries and planetary transits. Examples of the latter include data processing errors and instrumentation artifacts. Using LcViewer, signals of any type can be measured, recorded, highlighted, tracked, queried, located, phase folded or stacked, and checked for periodicity. Project defined signals such as TOIs, CTOIs, K2OIs, KOIs, and TCEs can be downloaded from an online data archive and highlighted in the lightcurve for easy identification.

2.2 Features

Using LcViewer, you are able to perform the following operations:

Lightcurve Generation & Loading

Build and load lightcurve files for the TESS, K2, and Kepler projects in addition to the TESS-TASOC, K2SFF, and K2-EVEREST HLSPs. Source data is obtained from MAST.
Load lightcurve files previously built by LcGenerator and LcStacker.
Load user supplied lightcurve files that were produced outside the LcTools system.
Via a work group, load lightcurve files sequentially at the click of a button. Ideal for iterating through a large set of lightcurve files quickly and efficiently.

Lightcurve Modification

Detrend a lightcurve.
Remove selected data points from a lightcurve.
Save a modified lightcurve to a file.

Lightcurve Navigation

Track time and flux in real-time using the mouse.
Select a view with the mouse.
Pan the view using scroll bars or by dragging the view with the mouse.
Zoom in or out of the lightcurve using independent horizontal and vertical controls.
Quickly zoom into a small area of the lightcurve by double-clicking the mouse.
Save and restore views.

Lightcurve Rendering

Scale the size of data points in the lightcurve to mitigate congestion and improve fidelity.
Connect data points in the lightcurve with lines to facilitate the detection of signals.
Show background flux in TESS lightcurves to help identify false positive candidate signals caused by light scattering events.

Signal Detection & Vetting

Detect periodic signals in a lightcurve using several different search methods (automatic, semi-automatic, and manual).
Import and vet periodic signals previously detected and recorded by LcSignalFinder.

Signal Folding & Stacking

Phase fold the instances of a periodic signal.
Stack the instances of a non-periodic signal.

Signal Recording & Sharing

Automatically download and highlight project defined signals such as TOIs, CTOIs, K2OIs, KOIs, and TCEs when opening a lightcurve file.
Manually create and highlight user defined signals in the lightcurve (periodic or non-periodic).
Edit and delete signals.
Share signals between users across the Internet via public signal libraries.

Signal Alignment & Sharing of TTV Data

Automatically align TTV shifted signals in the lightcurve based on supplied TTV libraries (public or private).
Manually align TTV shifted signals using the mouse.
Share TTV alignment data between users across the Internet via public TTV libraries.

Signal Highlighting

Automatically assign colors to signals at run time to help differentiate signals in a lightcurve.
Via color coding, show where two or more signals overlap in the lightcurve.

Signal Navigation

Track signals in real-time using the mouse.
Sequentially navigate to each instance of a signal in the lightcurve at the click of a button.
Quickly zoom into a signal by double-clicking the mouse.

Signal Information

Query the physical properties of a defined signal.
Measure the time and flux interval between two candidate signals or locations in the lightcurve.
Measure the dimensions of a candidate signal in the lightcurve. Estimate the minimum size of the underlying object in REarth units.

Other Utilities & Services

Query the stellar properties for the lightcurve.
Draw a temporary line in the lightcurve for reference purposes or for use as a straight-edge.
Capture and save screen images.
Obtain supporting documentation (Quick Reference Manual and User Guide).
Configure colors, hotkeys, and mouse buttons.

2.3 Sample Screen Snapshots

The following screen snapshots will help illustrate some of the key features listed above.

Snapshot 1: The “Open Lightcurve” dialog box. Enables you to specify the lightcurve directory, star ID, and lightcurve file to generate or open for a project.

Snapshot 2: The “Time Series Selection” dialog box. Enables you to specify the time series periods, cadence, flux type, data point quality filter, short cadence bin size, and filename of a lightcurve file to build.

As part of the build process for a lightcurve file, LcViewer:
Downloads the requested time series files for the host star from MAST.
Converts the time series files from FITS to text.
Removes unwanted data points from the files per the quality filter.
For short cadence files, bins the data points at a specified data rate.
Normalizes the flux values in each file.
Merges the resulting files together as a single lightcurve file that can be opened in LcViewer or LcSignalFinder.

Snapshot 3: The “View Settings” dialog box. Enables you to track the current position and signal in the lightcurve, scale the size of data points, connect data points with lines, set the signal region timescale, and select the signals to be highlighted.

Snapshot 4: A Kepler lightcurve showing a highlighted KOI transit signal. Project defined signals are obtained from MAST, NEA, or ExoFOP-TESS as applicable.

Snapshot 5: The Tracking Information Box showing the time, flux, and signal at the cursor. Values are updated in real-time.

Snapshot 6: Two overlapping KOI transit signals. LcViewer automatically marks the overlapping region of mutual signals in red.

Snapshot 7: A TTV shifted KOI transit signal. Signals can be automatically aligned using public TTV libraries available in shared Google Drive folders or manually aligned using the mouse.

Snapshot 8a: Measuring the time interval between two candidate signals in the lightcurve.

Snapshot 8b: Measuring the depth and estimating the minimum object size in REarth units for a candidate signal in the lightcurve.

Snapshot 9a: A Kepler SAP_FLUX lightcurve to be detrended.

Snapshot 9b: Same lightcurve with a fitted trend line plus associated dialog box for controlling the detrending operation.

Via the dialog box, you can:

Remove single point outliers prior to fitting a trend line. High and low outliers can be removed separately.
Select a trend line fitting method (Spline or Moving Median).
Adjust the trend line fitting level. The higher the level, the flatter the lightcurve will be after detrending.
Visually check the trend line to guard against overfitting and underfitting.

Snapshot 9c: The detrended lightcurve after the Detrend button is clicked.

You can click the Redo button to retry the detrending operation using different settings. The Redo button can also be used to quickly compare the before and after images to see what changed.

Snapshot 10a: Preparing to automatically detect periodic signals in a K2 lightcurve using the Box-fitting Least Squares (BLS) algorithm.

Via the dialog box, you can:

Remove single point outliers from the lightcurve prior to detrending it. High and low outliers can be removed separately.
Detrend the lightcurve before running BLS.
Set a minimum signal-to-noise ratio for signals to find.
Set the maximum number of signals that can be returned from BLS.

Before BLS is run, the data points for all defined signals are removed from the lightcurve so that BLS does not return known signals.

Snapshot 10b: Detected candidate signal #1 (in green) plus an associated dialog box for controlling the signal detection operation.

Via the dialog box and lightcurve you can:

Navigate to each instance of the signal in the lightcurve to check the fit between the green rectangle and the actual signal.
Fine-tune the reference epoch, duration, and period to obtain a more accurate fit.
Phase fold the signal and then measure it to obtain the duration, depth, minimum object size, and sigma value.
For a viable signal, create (record) a user defined signal in a signal library. For a non-viable signal, delete the candidate signal from the list.
Find another periodic signal in the lightcurve.

Snapshot 10c: Preparing to phase fold candidate signal #1.

Via the dialog box, you can:

Set the timescale for the signals.
Remove single point outliers and overlapping signals from the lightcurve prior to detrending the signals.
Set the trend line fitting method (Polynomial or Spline) and the flattening level for detrending the signals.
Show the detrending stages to visually check the results for overfitting and underfitting.
Set the initial bin size in minutes for the phase folded data.

Snapshot 10d: The phase folded lightcurve for candidate signal #1 plus the associated dialog box for controlling the phase fold operation.

The small grey dots represent the phase folded unbinned data points. The large green dots represent the binned data points. Via the dialog box, you can:

Adjust the timescale for the signals.
Adjust the trend line fitting method (Polynomial or Spline) and the flattening level for detrending the signals.
Mirror fold the left side of the lightcurve over the right side to check for symmetry.
Change the method used for averaging the flux value in each bin.
Change the bin size in minutes.
Control which data points are displayed.
Fit a smooth curve through the binned data points. Adjust the smoothing level if desired.
Connect the binned data points with straight lines as an alternative to a fitted curve.
Show horizontal and vertical reference lines to indicate signal location and duration.

A phase folded lightcurve can be saved to a file and then opened at a later time just like a regular lightcurve. You can also measure and create user defined signals in the phase folded lightcurve.

Snapshot 10e: Creating a user defined planetary transit signal in the lightcurve for candidate signal #1.

Snapshot 10f: The created planetary transit signal for candidate signal #1 (partial view).

Snapshot 11: Setting Up a Work Group for the TESS project.

A work group is a set of lightcurve files that you wish to view or process in LcViewer. For example, a work group could contain all the lightcurve files in a TESS sector or K2 campaign. Once a work group is set up, files can be quickly loaded (opened) from the work group in sequential order at the click of a button. This is a fast, easy, and efficient alternative to the "Open Lightcurve" dialog box. Ideal for iterating though a large list of files.

3. LcSignalFinder

LcSignalFinder uses the BLS algorithm to detect and record periodic signals found in a large set of lightcurves files for the TESS, K2, and Kepler projects in addition to the TESS-TASOC, K2SFF, and K2-EVEREST HLSPs. For example, the tool can be used to find and record periodic signals in the lightcurve files for an entire TESS sector or K2 campaign typically consisting of over 20,000 files. A sample application window is shown below:

Via the application window you can:

Select a set of lightcurve files to process.
Specify the lightcurve preparation options and BLS settings.
Select the signal types to find and record.
Start a new job, pause a job in progress, or resume a paused job.
Monitor the progress of a job in real-time.

Before BLS is run on a lightcurve, the data points for all defined signals are removed from the lightcurve so that BLS does not return known signals.

LcSignalFinder works in conjunction with LcViewer. While LcSignalFinder is detecting and recording new signals, LcViewer can be used to vet the signals previously recorded by LcSignalFinder. By running both applications concurrently, processing time across the set of files can be minimized.

4. LcGenerator

LcGenerator builds lightcurve files in bulk for the TESS, K2, and Kepler projects in addition to the TESS-TASOC, K2SFF, and K2-EVEREST HLSPs for subsequent use by LcViewer and LcSignalFinder. For example, LcGenerator can be used to build lightcurve files for all the stars in a TESS sector or K2 campaign typically consisting of over 20,000 files. A sample application window is shown below:

Via the application window, you can specify the target lightcurve directory, list of stars to process, time series periods, cadence, flux type, and data point quality filter.

As part of the build process for a lightcurve file, LcGenerator:

Downloads the requested time series files for the host star from MAST.
Converts the time series files from FITS to text.
Removes unwanted data points from the files per the quality filter.
For short cadence files, bins the data points at a specified data rate.
Normalizes the flux values in each file.
Merges the resulting files together as a single lightcurve file that can be opened in LcViewer or LcSignalFinder.

To minimize overall processing time, LcGenerator can be run concurrently with LcSignalFinder and LcViewer.

5. LcStacker

LcStacker combines a set of phase folded lightcurve files produced by LcViewer into a stacked lightcurve file for subsequent use with LcViewer. By combining many files together, a stacked lightcurve file can achieve a very high signal-to-noise ratio thereby enabling small artifacts to be detected in the combined lightcurve that might otherwise be hidden in the noise of the individual lightcurves.

LcStacker is invoked through a command line interface. Parameters include the list of files to stack, the target lightcurve directory, and the ensemble number for the stack. You may also specify various clipping options for removing unwanted data points from the stacked lightcurve. A sample execution transcript is shown below:

When combining phase folded lightcurves, LcStacker normalizes the time and flux value for each data point. Time is scaled such that each phase folded signal starts at -1.0 normalized hours and ends at +1.0 normalized hours (2 hours duration centered at time 0.0). Flux is scaled for a 1.0 Rsol reference star.

6. LcStackAnalyzer

LcStackAnalyzer determines the contribution of each phase folded lightcurve file for a specified reference signal recorded in a stacked lightcurve file. Reference signals are recorded with LcViewer and can represent any type of phenomena. The contribution is expressed as a sigma value indicating the strength of the signal where a value of 4 and above is generally considered to be significant.

LcStackAnalyzer is invoked through a command line interface. Parameters include the stacked lightcurve file and the signal number in the file to analyze. An analysis report file is created as shown in the example below. Sigma contributions are listed from highest to lowest.

7. LcReporter

LcReporter creates an Excel report listing the user defined signals found in a specified signal library or lightcurve directory. The signals from multiple signal libraries may be combined into one report. A partial sample report is shown below:

8. Run-Time Requirements (Minimum)

Windows OS (XP, Vista, 7, 8, 10).
2.7 GHz CPU.
5 GB memory.
100 GB free disk space.
1024 x 768 screen resolution.
2-Button mouse or equivalent.
High-speed Internet connection.
Microsoft Word.
Microsoft Excel (if using LcReporter).
Google Drive (if using public signal libraries or public TTV libraries).

9. Contact Information

To obtain this product for use or to learn more about it, please contact the author at aschmitt@comcast.net.

Acknowledgements

I would like to sincerely thank the following individuals for contributing to this product:

Joel D. Hartman, Princeton University, Department of Astrophysical Sciences for providing the C source code and follow-up technical assistance for the Box-fitting Least Squares (BLS) function obtained from his VARTOOLS product. The scientific and technical reference for VARTOOLS can be found in Hartman and Bakos, 2016, Astronomy and Computing, 17, 1.

David Kipping, Columbia University, Department of Astronomy for providing the underlying algorithms and technical assistance for phase folding signals and stacking lightcurves.

lctools	Search this site