Product Description

1. Introduction

LcTools is a Windows based software system designed for processing Kepler and K2 lightcurves. The system consists of six main applications:


 ApplicationPurpose 
LcViewer View lightcurve files. Detect, record, and analyze signals of interest. 
LcSignalFinder Automatically detect and record periodic signals found in a set of lightcurve files.
LcGenerator Generate 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.
LcStackAnalyzerDetermine 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 artifacts found in Kepler and K2 lightcurves. Using LcViewer, lightcurves may be generated, loaded, detrended, edited, saved, and viewed. 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, planetary transits, moon transits and eclipses, star spot crossings, and stellar flares. Examples of the latter include Kepler data processing errors and instrumentation artifacts. Using LcViewer, signals of any type may be measured, recorded, highlighted, tracked, queried, located, phase folded or stacked, and checked for periodicity.


2.2 Features

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


Lightcurve Generation & Loading
  • Generate local lightcurve files from time series data downloaded from MAST.
  • Open lightcurve files previously built by LcGenerator, LcViewer, or LcStacker.
  • Open user supplied lightcurve files that were produced outside the LcTools system.
  • Via a work group, open 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 cursor.
  • 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.
Signal Detection & Vetting
  • Detect periodic signals in a lightcurve using several different methods (automatic/BLS, semi-automatic, and manual).
  • Vet periodic signals previously detected by LcSignalFinder or LcViewer.
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 from NEA when opening a lightcurve file. Signals include KOIs, K2OIs, and TCEs.
  • 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 cursor.
  • 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 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:
  1. Downloads the requested time series files for the host star from MAST.
  2. Converts the time series files from FITS to text.
  3. Removes "bad" data points from the files per the quality filter.
  4. Normalizes the flux values in each file.
  5. Bins the data points in each file per the requested bin size (short-cadence time series files only).
  6. Merges the resulting files together as a single lightcurve file that can be opened and viewed. 

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 lightcurve showing a highlighted KOI transit signal. KOI, K2OI, and TCE signals are obtained from the NASA Exoplanet Archive (NEA).



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 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.

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 period in which to look for signals in lightcurves with long timespans. This in turn governs the BLS execution speed.
  • Set a minimum signal-to-noise ratio for signals to find.
When BLS is run, the data points for all defined signals such as KOIs, K2OIs, and TCEs 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 period to obtain a more accurate fit.
  • Phase fold the signal and then measure it to obtain the duration, depth, estimated 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.
  • Set the initial bin size in minutes for the phase folded data.

Snapshot 10d: The phase folded lightcurve for candidate signal #1 plus 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 serve as context.
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.


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 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 in a set of lightcurves files for the Kepler or K2 project. The tool is designed to work with a large set of files. For example, the application can be used to find and record periodic signals in the lightcurve files for an entire 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.
  • Set up the lightcurve preparation options. Includes outlier removal and lightcurve detrending. High and low outliers can be removed separately.
  • Set up the BLS runtime parameters. Includes the minimum period in which to look for signals and the minimum signal-to-noise ratio.
  • Start a new job, pause a job in progress, or resume a paused job.
  • Monitor the progress of a job in real-time. 
When BLS is run on a lightcurve, the data points for all defined signals such as KOIs, K2OIs, and TCEs 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 is a batch application designed to build lightcurve files in bulk for LcViewer and LcSignalFinder. The tool is particularly useful for performing large-scale builds involving hundreds or perhaps thousands of lightcurves. For example, LcGenerator can be used to build lightcurve files for all the stars in a K2 campaign. 

LcGenerator is invoked through a command line interface. Parameters which can be specified include a star list file, target lightcurve directory, time series periods and cadence, flux type, short cadence bin size, and data point quality filter. A sample execution transcript is shown below:


As part of the build process for a lightcurve file, LcGenerator:
  1. Downloads the requested time series files for the host star from MAST.
  2. Converts the time series files from FITS to text.
  3. Removes "bad" data points from the files per the quality filter.
  4. Normalizes the flux values in each file.
  5. Bins the data points in each file per the requested bin size (short-cadence time series files only).
  6. Merges the resulting files together as a single lightcurve file that can be loaded by LcViewer and LcSignalFinder. 

5. LcStacker

LcStacker combines a set of phase folded lightcurve files 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 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 800 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:

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