README TAP v 1.7
Zach Gazak, zgazak@ifa.hawaii.edu, jzgazak@gmail.com
Downloading TAP:
-Download the most recent version: TAP_v1.7.tar.gz
-extract and place folder in your IDL path: tar xzf TAP_v1.7.tar.gz
Example Video: http://ifa.hawaii.edu/users/zgazak/TAP/TAP_example.mp4
1) Starting TAP:
a) start a session of IDL in a directory where you would like the savefiles
created by the program to be stored.
b) run 'tap' at the IDL prompt.
NOTE: If you are analyzing data with significant integration times
(longer than one or two minutes), run 'tap,/rebin' instead--
this will resample your time grid to 60 second cadence then
rebin the fine time grid model onto the time grid of your data.
This slows the code significantly but is important to properly
handle light curve distortions due to long integrations.
2) Load a transit file:
a) click on "Transit File" under the "Load Transit" Button
b) select your file, hit "ok" in the pop up window.
c) select file type:
'ASCII File': 2 to 4 columns. First column must be time in days: JD, HJD,
MJD, BJD, etc. Second column must be flux and should be
normalized to an out of transit value of 1. The other
columns are not used.
'IDL Save File': TAP creates an IDL save file for the transit when an
MCMC analysis is run. These can be reloaded at later
times by selecting this type. These files will appear
as 'TAP_MCMC_YYYYMMDD_HHMM_StoreTransit.idlsav'
d) Click "Load Transit"
The plot window will display the transit light curve in the top plot
and the residuals in the bottom plot. The initial transit guess is
not intelligent (as of v1.7) so do not be concerned by a poor fit.
Regardless, that transit will appear as a blue curve, and the residuals
will be plotted as distance from that blue curve. The default strength
for "correlated red noise" is 0 (i.e. no red noise). If you choose to
fit for red noise as well, a red curve will also be overplotted, showing
instead the transit model with the red noise signal added to it.
3) Fit the transit light curve:
a) click on the "Fit" button... the lower workspace will change.
b) The workspace has 3 "sub windows":
1) "Setup":
"Manual Parameter Adjustment": this button opens a new window with
13 sliders. These represent the possible free parameters for MCMC
fitting. The values can be adjusted by dragging the sliders or by
typing in values and pressing "return". The light curve plotted
in the main window will update automatically.
"System Parameters": The parameters of the transiting system from
the Mandel & Agol (2002) analytic light curve.
"Quadratic Limb Darkening": Linear and quadratic Limb Darkening
Coefficients.
"Airmass Trend Correction": A linear correction for airmass or
normalization. Slope and Y-intercept of the "out of transit"
level to account for any trend in the data.
"Noise Analysis Parameters": Strength of "White" uncorrelated
gaussian noise and "Red" (1/f) correlated noise.
"Parameter Limits and Locks": this button opens a new window with one
row for each of the 13 possible free parameters.
"Min/Max": The minimum and maximum of the sliders for "Manual
Parameter Adjustment", and, if "Apply Limits to Fitting" is
selected, the MCMC is not allowed to wander beyond these
limits.
"Lock": Select this to lock a parameter during fitting. This is
used for parameters that are unable to be determined from the
transit light curve, such as period in the case of a single
light curve.
"MCMC Accept Rate": This is the percent of jumps for which the MCMC
algorithm will optimize the jump betas. The typical value
for efficient MCMC convergence is ~44%, which is set as the
default value.
"Apply Limits to Fitting": Will force the MCMC execution to explore
a parameter space limited by the "Max/Min" values.
2) Levenberg-Markwart: the "Run Markwart Fit" button will perform a Levenberg-
Markwart fit using IDL's "mpfit". This fit does not optimize the noise
parameters and should be considered a tool just to move the model "close"
to the correct fit. This fit is constrained by the "locks" and "limits"
selected in the "Parameter Limits and Locks" window.
3) Markov Chain Monte Carlo:
"Setup":
"Run Parameters": Characteristics for the MCMC chain execution.
"Number of Chains": Number of separate chains to be calculated.
Multiple chains allow for certain (non conclusive) tests of
convergence and can be combined in the final analysis.
"Chain Length:
"Minimum Links": Each chain will be at least this long.
"Maximum Links": If greater than Minimum Links, a Gelman-Rubin
non-convergence test will be performed and while the test
is consistent with non-convergence the chains will be
extended out to, at maximum, this value.
"Chi-Sq. Penalties": Penalty terms allowing a parameter to vary in
the MCMC analysis but under a gaussian penalty term. The term
works as a modification to the Likelihood of any particular fit
by adding a term of the form exp[-(Value-model_param)^2/Sigma^2].
This is useful when a parameter is theoretically known but should
be allowed to wander, most commonly the limb darkening parameters.
The code will then find an ideal solution between the "Value" and
mathematically most likely solution. Set a value, sigma, and click
the Penalize box to activate this feature.
"Execute Chain": This will open a new window and freeze the base window. The
new window will display the progress of the MCMC chain analysis and the
plot window on the frozen TAP base will cycle through the evolving
parameter distributions.
3) Analyze MCMC chain(s):
a) click on the "MCMC Inference" button. The lower workspace will change.
b) click on the "MCMC Save File" button, select one of the TAP chain save files, which
will appear as "TAP_MCMC_YYYYDDMM_HHMM_0Xof0Y.idlsav". Click OK.
c) click "Load"... the code will perform a Bayesian analysis on the MCMC chain after
conservatively removing the first 25% of the chain to account for "burn in". The
"most likely" (median) value and the "1 sigma" (15.9%,85.1%) uncertainties in the
upper left section. The plot will display the "most likely" (median) solution.
d) if multiple chains were created, click "Combine Chains" which strips the first 25%
from each chain and combines them into a single chain.
e) click "Prepare Summary"--this will create up to seven plots and a .tex file and takes
a few minutes to run. The first 3 plots, labeled *PLOT1a,b,c* represent the MCMC
parameter distributions from which the best fit values and their uncertainties were
drawn. The next plot, *PLOT2* shows your light curve and the most likely solution.
If either or both of the limb darkening parameters were allowed to vary, you will see
*PLOT3* with "u1" or "u2"... which shows 2D distributions and histograms along with
the best fit values and uncertainties. Finally, *PLOT4* plots the 2D distributions
of some of the System Parameters. Once the process is complete, open the .tex file
into a LaTeX compiler (or compile on command line), and a pdf will be generated with
a table of the parameter results (you will need to adjust significant figures), and
all of the plots.