LcTools Product Description
1. Introduction
LcTools is a Windows based set of applications for finding, recording, analyzing, and viewing signals in light curves for supported missions and associated high-level science products (HLSPs) at MAST. Supported missions include TESS, K2, and Kepler. Supported HLSPs include QLP, TESS-SPOC, and GSFC-ELEANOR-LITE for the TESS mission, K2SFF and EVEREST for the K2 mission, and KBONUS-BKG for the Kepler mission.
The LcTools system consists of the following applications:
LcViewer Enables you to build, view, edit, and detrend light curves and to
detect, record, measure, display, and phase folds signals.
LcSignalFinder Detects and records signals and associated TTVs found in a large set of light curve files.
LcGenerator Builds light curve files in bulk for subsequent use with LcViewer and LcSignalFinder.
LcReporter Creates Excel reports for signals recorded by LcSignalFinder and LcViewer in addition
to reports for mission based and community based signals.
See the following LcTools reseach papers for additional information:
A detailed description of the system is provided below.
2. LcViewer
2.1 Overview
LcViewer is a multi-purpose graphics based application designed for analyzing light curves. Using LcViewer, you are able to 1) build, view, edit, and detrend light curves, 2) detect, record, measure, display, query, locate, and phase fold signals, 3) import and display mission based and community based signals including TOIs, CTOIs, K2OIs, KOIs, and TCEs, 4) detect, record, and display TTVs, 5) display background flux, 6) measure time and flux intervals, and 7) query stellar properties. Both periodic and non-periodic signals are supported. Signals may be dips or peaks.
2.2 Opening a Light Curve
A light curve can be opened for a project using the dialog box below.
If the "Generate File From Time Series" option is selected, a second dialog box is opened for selecting the time series periods, cadence, flux type, data point quality filter, short cadence bin size, and filename of the light curve file to generate.
2.3 Work Group
A work group is a set of light curve files that can be viewed or analyzed in LcViewer. A work group is normally set up to vet the candidate signals and TTVs recorded by LcSignalFinder. See section 3 below for details.
Once a work group is set up using the dialog box below, files can be quickly loaded (opened) from the work group in sequential order by clicking the "Next" or "Prev" button at the bottom left corner of the Main Application Window (see section 2.4.1 below). This is a fast and efficient way to iterate though a large list of files.
2.4 Displaying a Light Curve
2.4.1 Main Application Window
The Main Application Window is used for viewing a light curve and its signals. Major components in the window are shown below.
When a light curve file is loaded, all associated signals and TTVs are imported from signal libraries and TTV libraries. Signals are color coded in the light curve for easy identification.
Via the window, you can perform the following operations:
Select a view using the mouse.
Pan the view using the mouse or scroll bars.
Zoom into or out of the view using the mouse, arrow keys, or Zoom View Control.
Sequentially navigate (view) the instances of a selected signal in the light curve via the Locate Signal Control. Double-clicking the mouse on a signal in the light curve quickly zooms into the signal.
Load the next or previous light curve file from the work group via the Load Work Group File Control.
Save and restore views using the Save/Restore View Control.
Open the user guide or quick reference manual to obtain help.
2.4.2 Tracking Information Box
The Tracking Information Box shows the time, flux, timeseries period, and signal at the cursor. Values are updated in real-time as the cursor is moved.
2.4.3 Making Measurements
Using the mouse, the time interval between two signals or locations in the light curve can be measured.
The flux interval, depth, and object size of a signal can also be measured.
2.4.4 Displaying Background Flux
Background flux can be displayed in red to indicate light scattering events. Such events may produce false positive candidate signals like that shown in white below.
2.5 Modifying a Light Curve
2.5.1 Detrending a Light Curve
A light curve can be detrended (flattened) to facilitate the seach for signals. The operation is controlled through an accompanying dialog box as shown below.
The green line represents the fitted trend line. The tighter the fit with the data points, the flatter the light curve will be after detrending. Via the dialog box, you can do the following:
Remove outliers from the light curve to improve the detrended results.
Select a trend line fitting method (Moving Median or Spline).
Adjust the trend line fitting level.
Specify a signal duration to flatten out all sections of the light curve excluding the signal itself.
The detrended light curve for this example is shown below:
2.5.2 Editing a Light Curve
Using the mouse, you can manually remove sections of a light curve. Normally, this is done to eliminate areas with poor quality prior to searching for signals. The edited light curve can optionally be saved to a file.
2.6 Signal Management
2.6.1 Recording a Signal
A candidate signal in a light curve can be recorded in a user defined signal library using the dialog box below.
2.6.2 Displaying Signal Properties
The properties for a defined signal in a light curve can be displayed via the dialog box below:
2.6.3 Phase Folding a Signal
A defined signal in a light curve can be phase folded in order to obtain the overall size and shape. An example is shown below.
The small grey dots represent the unbinned data points. The large green dots represent the binned data points. Via the dialog box, you can:
Adjust the horizontal region timescale for the signal.
Select the fitting method (Moving Median, Polynomial, or Spline) for detrending the signal.
Select the flattening level for detrending the signal.
Fold the left side of the light curve over the right side to check for symmetry and to combine data points.
Select the method for averaging binned flux (Mean or Median).
Change the bin size in minutes.
Control the type of data points displayed (unbinned, binned, or both).
Fit a smooth curve through the binned data points. Adjust the smoothing level.
Connect the binned data points with straight lines as an alternative to a fitted curve.
Show horizontal and vertical reference lines to indicate the location and duration of the phase folded signal.
2.7 Finding Signals
2.7.1 Finding Transit Based Signals Using QuickFind or BLS
Transit based signals include planets, EBs, trojans, and moons. Before conducting an automated search for these signals, the search parameters must first be set up using the dialog box below.
Via the dialog box, you can:
Select the light curve preparation options.
Select the signal detection method -- QuickFind or BLS.
Select the number of instances per signal.
Set the target signal direction -- down for dips or up for peaks.
Specify the target signal properties including the maximum number of signals to find in the light curve, minimum signal-to-noise ratio, period range, duration range, and object size range.
Upon completion of the search or when vetting the signals previously recorded by LcSignalFinder, the detected signals will be listed in an accompanying dialog box as shown below. The first signal in the list is selected by default. Each instance of the selected signal in the light curve is marked with a green rectangle for easy identification.
Via the dialog box you can do the following:
Navigate to each instance of the signal in the light curve to check the alignment between the calculated instance and the observed instance.
For a misaligned instance, manually move the green rectangle with the mouse so that it aligns with the observed instance. This creates a TTV record.
If a signal has TTVs, toggle the display between the observed instances and the calculated instances.
Phase fold the signal to obtain the overall size and shape.
Record the signal in a user defined signal library. If the signal has TTVs, record them in a TTV library.
Delete unwanted signals from the list to disposition them.
For a false positive signal that occurs repeatedly across multiple light curves at the same location, exclude the data points for the signal from the light curves to prevent the signal from being found again.
Detrend the light curve to correct for underfitting and overfitting of signals. This will automatically start a new signal search.
If the "Show TTV Diagram" button is clicked, the light curve will be replaced with a TTV diagram as shown in the example below.
Each TTV data point in the diagram shows the time difference in hours between the observed instance and the calculated instance in the light curve. If you double-click the mouse on an outlier in the diagram such as the one shown at 680 BKJD above, you will be returned to the regular light curve with the view centered at the corresponding calculated instance of the signal in the light curve. To resolve the outlier, you can use the mouse to manually align the green rectangle with the observed instance.
2.7.2 Finding Sinusoidal Signals with LombScargle
Sinusoidal signals include but are not limited to Cepheids (Type I and II), RR Lyrae, RV Tauri, Mira, Delta Scuti, roAp, and stellar rotation. Signals can be detected in the frequency range of 0.002 to 720 cycles per day (CPD) which corresponds to a period range of 2 minutes to 500 days. Before conducting an automated search for these signals, the search parameters must first be set up using the dialog box below.
Via the dialog box, you can specify the target signal properties including the maximum number of signals to find in the light curve, minimum signal-to-noise ratio, minimum power level, and the frequency range.
Upon completion of the search or when vetting the signals previously recorded by LcSignalFinder, the detected signals will be listed in an accompanying dialog box as shown below. The first signal in the list is selected by default. Each instance (cycle) of the selected signal in the light curve is marked with a green rectangle for easy identification.
Via the dialog box you can do the following:
Navigate to each instance of the signal in the light curve to check the alignment between the calculated instance and the observed instance.
Phase fold the signal to obtain the overall size and shape.
Record the signal in a user defined signal library.
Delete unwanted signals from the list to disposition them.
Detrend the light curve to flatten a signal. This will automatically start a new signal search.
If the "Show Periodogram" button is clicked, the light curve will be replaced with a LombScargle periodogram as shown in the example below.
Each peak (signal) detected by LombScargle is plotted as a data point in the periodogram, where the x-coordinate is the frequency and the y-coordinate is the power level. Up to 500 signals are plotted. If you double-click the mouse on a data point, the regular light curve will be restored, the associated signal will be selected in the list box, and selected signal displayed in the light curve.
2.8 Displaying Stellar Properties
Stellar properties for the current light curve can be displayed via the dialog box below.
3. LcSignalFinder
LcSignalFinder detects and records candidate signals and associated TTVs found in a large set of light curve files. Signals may be periodic or non-periodic, dips or peaks. A sample application window is shown below:
Via the application window you can:
Set up a job for execution. Parameters include the target light curve files, light curve preparation options, signal detection method (QuickFind, BLS, or LombScargle), number of instances per signal, signal direction, maximum number of signals per light curve, minimum signal-to-noise ratio, minimum power level, period or frequency range, duration range, size range, and target signal types.
Start, pause, and resume a job.
Monitor the progress of the job in real-time.
Open the user guide to obtain help.
Upon completion of the job, the signals and TTVs recorded by LcSignalFinder must be vetted using LcViewer.
4. LcGenerator
LcGenerator builds light curve files in bulk for subsequent use with LcViewer and LcSignalFinder. A sample application window is shown below:
Via the application window, you can:
Set up a job for execution. Parameters include the target light curve directory, list of stars to process, time series periods, cadence, flux type, and data point quality filter.
Start, pause, and resume a job.
Monitor the progress of the job in real-time.
Open the user guide to obtain help.
5. LcReporter
LcReporter creates Excel reports for signals recorded by LcSignalFinder and LcViewer in addition to reports for mission based and community based signals. Signals include TOIs, CTOIs, K2OIs, and KOIs. A sample report for signals and associated TTVs recorded by LcSignalFinder is shown below.
6. Minimum Run-Time Requirements
Windows OS (8/10/11).
2.7 GHz CPU.
5 GB memory.
50 GB free disk space for light curve files and associated data files on any drive. 25 MB for the LcTools software system on drive C.
1024 x 768 screen resolution.
2-Button mouse or equivalent.
High-speed Internet connection.
Microsoft Word.
Microsoft Excel (if generating Excel reports).
7. Contact Information
To obtain this product for use or to learn more about it, please contact the LcTools author at aschmitt@comcast.net.
Acknowledgements
I wish 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 from VARTOOLS that was used to implement the BLS and LombScargle features. 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 design for detrending light curves and phase folding signals.