LcTools Product Description
1. Introduction
LcTools is a Windows-based set of applications for finding, recording, and viewing signals in light curves for supported missions and associated HLSPs (High Level Science Products) at MAST. Supported missions include TESS, K2, and Kepler. Supported HLSPs include QLP, TESS-SPOC, and GSFC-ELEANOR-LITE for the TESS mission and K2SFF and EVEREST for the K2 mission. The system consists of the following applications:
LcViewer Build, view, edit, and detrend light curves. Detect, record, measure, locate, query,
display, and phase fold signals.
LcSignalFinder Detect and record signals and associated TTVs found in a large set of light curve files.
LcGenerator Build light curve files in bulk for subsequent use with LcViewer and LcSignalFinder.
LcReporter Create an Excel report for signals recorded by LcSignalFinder and LcViewer
in addition to pre-recorded signals for project-based and community-based
planetary objects of interest (TOIs, CTOIs, K2OIs, and KOIs).
A high level overview of features provided is presented below. See the LcTools research paper for system details.
2. LcViewer
2.1 Overview
LcViewer is a multi-purpose graphics based application designed for processing light curves and their signals. 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 project based signals including TOIs, CTOIs, K2OIs, KOIs, and TCEs, 4) automatically align TTV shifted transits in project based signals, 5) detect, record, and display TTVs, 6) display background flux, 7) measure time and flux intervals, and 8) query stellar properties. Both periodic and non-periodic signals are supported. Signals may be dips or peaks.
The application provides advanced light curve navigation and display features with multiple ways to select views, pan, and zoom. Navigation also includes auto-scrolling, real-time tracking of the current position and signal at the cursor, and the ability to save and restore views.
2.2 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 light curve directory, star ID, and light curve 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 light curve file to build.
As part of the build process for a light curve 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 light curve file that can be opened in LcViewer or LcSignalFinder.
__________________________________________
Snapshot 3: A Kepler light curve showing a highlighted planetary transit signal. Project defined signals are obtained from MAST, NEA, or ExoFOP-TESS as applicable and include TOIs, CTOIs, K2OIs, KOIs, and TCEs.
__________________________________________
Snapshot 4: The Tracking Information Box showing the time, flux, and signal at the cursor. Values are updated in real-time.
__________________________________________
Snapshot 5: Two overlapping KOI transit signals. LcViewer automatically marks the overlapping region of mutual signals in red.
__________________________________________
Snapshot 6: A TTV shifted planetary transit signal. Signals can be aligned in three ways: 1) automatically using imported TTV libraries, 2) automatically using the QuickFind signal detection method, and 3) manually using the mouse.
__________________________________________
Snapshot 7a: Measuring the time interval between two candidate signals in the light curve.
__________________________________________
Snapshot 7b: Measuring the depth and signal size for a candidate signal in the light curve.
__________________________________________
Snapshot 8a: A Kepler SAP_FLUX light curve to be detrended.
__________________________________________
Snapshot 8b: Same light curve with a fitted trend line plus associated dialog box for controlling the detrending operation.
Via the dialog box, you can:
Remove data point outliers prior to fitting a trend line. High and low outliers can be removed separately.
Select a trend line fitting method (Moving Median or Spline).
Adjust the trend line fitting level. The higher the level, the flatter the light curve will be after detrending.
Select a signal duration to optimize the detrending result for a signal of known duration.
Visually check the trend line to guard against overfitting and underfitting.
__________________________________________
Snapshot 8c: The detrended light curve 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 9a: Preparing to search for periodic signals in a Kepler light curve using the QuickFind signal detection method.
Via the dialog box, you can:
Select the light curve preparation options prior to searching for signals. Includes outlier removal and detrending.
Select the signal detection method (QuickFind or BLS).
Select the minimum and maximum number of instances per signal.
Set the target signal direction -- down for dips or up for peaks.
Specify the properties for signals to find. Includes the maximum number of signals that can be returned per light curve, minimum signal-to-noise ratio, minimum and maximum signal size, minimum and maximum period, and minimum and maximum signal duration.
Before a signal search is started, the data points for all defined signals are removed from the light curve so that already known signals are not found again.
__________________________________________
Snapshot 9b: A detected periodic signal highlighted in green plus an accompanying dialog box for controlling the signal detection operation.
Via the dialog box and light curve you can:
Navigate to each instance of the signal in the light curve to check the alignment between the detected or calculated instance marked with a green rectangle and the observed instance.
For a misaligned instance, move the green rectangle with the mouse so that it aligns with the observed instance. In the case of a periodic signal, this creates a TTV record.
For a periodic signal with TTVs, show the shift in positions between the observed instances and the calculated instances.
For a periodic signal, show a TTV diagram (aka, O-C diagram). See Snapshot 10 below for an example.
For a periodic signal, phase fold the signal to obtain a composite signal for study.
For a viable signal, create (record) a user defined signal in a signal library. For a periodic signal, record the associated TTVs in a TTV library.
For a non-viable signal, delete the candidate signal from the list.
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.
Manually detrend the light curve to correct for underfitting and overfitting of signals before starting a new signal search.
__________________________________________
Snapshot 9c: Preparing to phase fold the selected periodic signal.
Via the dialog box, you can:
Set the duration timescale for the signals.
Remove data point outliers and overlapping signals from the light curve prior to detrending the signals.
Set the trend line fitting method (Moving Median, 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 9d: The phase folded light curve for the selected signal plus accompanying dialog box for controlling the phase fold operation.
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 duration timescale for the signals.
Adjust the trend line fitting method (Moving Median, Polynomial, or Spline) and the flattening level for detrending the signals.
Fold the left side of the light curve over the right side to check for symmetry and to combine data points.
Change the binning method (mean or median).
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 the location and duration of the phase folded signal.
A phase folded light curve can be saved to a file and then opened at a later time just like a regular light curve. You can also measure and create user defined signals in the phase folded light curve.
__________________________________________
Snapshot 9e: Creating (recording) a user defined EB-P signal in a private signal library. Associated TTVs are recorded in a default TTV library. Note that the dialog box is populated automatically.
__________________________________________
Snapshot 9f: The created EB-P signal.
__________________________________________
Snapshot 10: A TTV diagram (aka, O-C diagram) for a periodic signal in a light curve.
A TTV diagram can be displayed for any periodic signal in a light curve having recorded TTVs. Each data point in the diagram shows the time difference in hours between the observed (detected) instance and the calculated instance in the light curve.
If there are any significant outliers in the plot such as the one shown at 373.8 BKJD above, you can double-click on the outlier and you will be returned to the regular light curve with the view centered at the corresponding instance of the signal in the light curve. You can then either move the color coded instance manually using the mouse or delete the color coded instance in an effort to resolve the outlier.
__________________________________________
Snapshot 11: Setting Up a Work Group for a TESS light curve directory.
A work group is a set of light curve files that you wish to view or process in LcViewer. You can select files based on a file filter, a build list, a star list, a file list, or from the files having signals from LcSignalFinder. For example, a work group could contain all the TESS CTL light curve files in a TESS sector typically consisting of 20,000 files.
Once a work group is set up, files can be quickly loaded (opened) from the work group in sequential order by clicking the "Next" button at the bottom left corner of the main application window. 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 detects and records signals and associated TTVs found in a large set of light curve files for subsequent use with LcViewer. Signals may be periodic or non-periodic, dips or peaks. For example, LcSignalFinder can be used to find and record periodic signals and associated TTVs in the TESS CTL light curve files for an entire TESS sector typically consisting of 20,000 files. A sample application window is shown below:
Via the application window you can:
Select a set of light curve files to process.
Select the light curve preparation options prior to searching for signals. Includes outlier removal and detrending.
Select the signal detection method (QuickFind or BLS).
Select the minimum and maximum number of instances per signal.
Set the target signal direction -- down for dips or up for peaks.
Specify the properties for signals to find. Includes the maximum number of signals that can be returned per light curve, minimum signal-to-noise ratio, minimum and maximum signal size, minimum and maximum period, and minimum and maximum signal duration.
Select the types of dipping periodic signals to find and record. Types include eclipsing binaries (EBs), planets (PCs), trojans, moons, and other.
Start, pause, and resume a job.
Monitor the progress of a job in real-time.
LcSignalFinder works in conjunction with LcViewer. While LcSignalFinder is executing, 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 light curve files in bulk for subsequent use with LcViewer and LcSignalFinder. For example, LcGenerator can be used to build TESS CTL light curve files for all the stars in a TESS sector typically consisting of 20,000 files. A sample application window is shown below:
Via the application window, you can:
Specify the settings for the job including 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 a job in real-time.
As part of the build process for a light curve 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 light curve file that can be opened in LcViewer or LcSignalFinder.
5. LcReporter
LcReporter generates Excel reports for signals recorded by LcSignalFinder and LcViewer in addition to pre-recorded signals for project-based and community-based planetary objects of interest (TOIs, CTOIs, K2OIs, and KOIs). A partial sample report for candidate signals and associated TTVs recorded by LcSignalFinder in a light curve directory is shown below:
6. Run-Time Requirements (Minimum)
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 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 derived from VARTOOLS. 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.