Syntax:

-TFA_SR trendlist ["readformat" Nskip jdcol magcol] dates_file ["decorr" iterativeflag Nlcterms lccolumn1 lcorder1 ...] pixelsep ["xycol" colx coly] correctlc ocoeff [coeff_outdir] omodel [model_outdir] dotfafirst tfathresh maxiter <"bin" nbins ["period" <"aov" | "ls" | "bls" | "spec" | "fix" period>] | "signal" filename | "harm" Nharm Nsubharm ["period" <"aov" | "ls" | "bls" | "spec" | "fix" period>]>

Example 1.
$ ./vartools -l EXAMPLES/lc_list_tfa_sr_harm -oneline -rms \
    -LS 0.1 10. 0.1 1 0 \
    -savelc \
    -Killharm ls 0 0 0 \
    -rms -restorelc 1 \
    -TFA EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa 25.0 xycol 2 3 1 0 0 \
    -Killharm ls 0 0 0 \
    -rms -restorelc 1 \
    -TFA_SR EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa 25.0 xycol 2 3 1 \
        1 EXAMPLES/OUTDIR1 1 EXAMPLES/OUTDIR1 \
        0 0.001 100 harm 0 0 period ls \
    -o EXAMPLES/OUTDIR1 nameformat 2.test_tfa_sr_harm \
    -Killharm ls 0 0 0 \
    -rms -restorelc 1 

Name                                  = EXAMPLES/2
Mean_Mag_0                            =  10.11802
RMS_0                                 =   0.03663
Expected_RMS_0                        =   0.00102
Npoints_0                             =  3313
LS_Period_1_1                         =     1.23440877
Log10_LS_Prob_1_1                     = -4000.59209
LS_Periodogram_Value_1_1              =    0.99619
LS_SNR_1_1                            =   45.98308
Killharm_Mean_Mag_3                   =  10.12217
Killharm_Period_1_3                   =     1.23440877
Killharm_Per1_Fundamental_Sincoeff_3  =   0.05008
Killharm_Per1_Fundamental_Coscoeff_3  =  -0.00222
Killharm_Per1_Amplitude_3             =   0.10026
Mean_Mag_4                            =  10.11176
RMS_4                                 =   0.00231
Expected_RMS_4                        =   0.00102
Npoints_4                             =  3313
TFA_MeanMag_6                         =  10.11766
TFA_RMS_6                             =   0.03555
Killharm_Mean_Mag_7                   =  10.12211
Killharm_Period_1_7                   =     1.23440877
Killharm_Per1_Fundamental_Sincoeff_7  =   0.04802
Killharm_Per1_Fundamental_Coscoeff_7  =  -0.00268
Killharm_Per1_Amplitude_7             =   0.09620
Mean_Mag_8                            =  10.11169
RMS_8                                 =   0.00725
Expected_RMS_8                        =   0.00102
Npoints_8                             =  3313
TFA_SR_MeanMag_10                     =  10.11788
TFA_SR_RMS_10                         =   0.03642
Killharm_Mean_Mag_12                  =  10.12210
Killharm_Period_1_12                  =     1.23440877
Killharm_Per1_Fundamental_Sincoeff_12 =   0.04986
Killharm_Per1_Fundamental_Coscoeff_12 =  -0.00237
Killharm_Per1_Amplitude_12            =   0.09984
Mean_Mag_13                           =  10.11166
RMS_13                                =   0.00210
Expected_RMS_13                       =   0.00102
Npoints_13                            =  3313

Example illustrating the use of signal-reconstruction TFA with a harmonic series for the model signal. We process light curves in the list EXAMPLES/lc_list_tfa_sr_harm (EXAMPLES/2 is the only light curve in this list). We first use -LS to find the period of the signal. We save a copy of the light curve and then use the -Killharm command followed by the -rms command to determine the amplitude of the signal and the RMS of the residual. We restore the light curve to its initial state (this is needed because -Killharm removes the signal from the light curve when the "fitonly" keyword is not used). We then filter the light curve using the -TFA command (no signal-reconstruction; see "vartools -TFA" or "vartools -example -TFA" for an explanation of the syntax). After applying -TFA we run -Killharm and -rms to determine the amplitude of the signal in the trend-filtered light curve and the RMS of the residual. Note that the amplitude is lower, and the residual RMS is higher after applying -TFA than before applying -TFA. This is because non-reconstructive TFA filters the signal in addition to filtering the noise from the light curve. We restore the light curve to its initial (pre-filtered) state using the -restorelc command, and then apply signal-reconstruction TFA. The syntax for the -TFA_SR command is similar to that for the -TFA command, however this time we choose to output the TFA coefficients and the TFA model to the directory EXAMPLES/OUTDIR1. For the signal-reconstruction specific parameters we set dotfafirst to 0, tfathresh to 0.001 and maxiter to 100 (these parameters only matter if we are using "decorr", "bin" or "signal" which can be used to iteratively fit the signal and filter the light curve, for the "harm" mode there is no iteration). We then give the "harm" keyword to indicate that we will be using a harmonic series for the signal. We use 0 harmonics and 0 sub-harmonics (only the fundamental is used, i.e. we fit a simple sine-curve). We specify "period" to indicate that we wish to fit a period other than the time-span of the light curve, and we specify "ls" to have the period taken from the previous -LS command. We output the filtered light curve to the file EXAMPLES/OUTDIR1/2.test_tfa_sr_harm, and we then use the -Killharm and -rms commands to determine the amplitude of the signal after -TFA_SR and the residual RMS. In this case the amplitude is comparable to the value before filtering, but the residual RMS is lower than without filtering.

Example 2.
$ ./vartools -l EXAMPLES/lc_list_tfa_sr_bin -oneline -rms \
    -aov Nbin 20 0.1 10. 0.1 0.01 1 0 \
    -savelc \
    -Killharm aov 5 0 0 \
    -rms -restorelc 1 \
    -TFA EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa 25.0 xycol 2 3 1 0 0 \
    -Killharm aov 5 0 0 \
    -rms -restorelc 1 \
    -TFA_SR EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa 25.0 xycol 2 3 1 \
        1 EXAMPLES/OUTDIR1 1 EXAMPLES/OUTDIR1 \
        0 0.001 100 bin 100 period aov \
    -o EXAMPLES/OUTDIR1 nameformat %s.test_tfa_sr_bin \
    -Killharm aov 5 0 0 \
    -rms -restorelc 1 

Name                                  = EXAMPLES/2
Mean_Mag_0                            =  10.11802
RMS_0                                 =   0.03663
Expected_RMS_0                        =   0.00102
Npoints_0                             =  3313
Period_1_1                            =     1.23583047
AOV_1_1                               = 18330.55450
AOV_SNR_1_1                           = 3093.61938
AOV_NEG_LN_FAP_1_1                    = 7633.23914
Killharm_Mean_Mag_3                   =  10.12175
Killharm_Period_1_3                   =     1.23583047
Killharm_Per1_Fundamental_Sincoeff_3  =   0.04514
Killharm_Per1_Fundamental_Coscoeff_3  =   0.02155
Killharm_Per1_Harm_2_Sincoeff_3       =   0.00033
Killharm_Per1_Harm_2_Coscoeff_3       =   0.00006
Killharm_Per1_Harm_3_Sincoeff_3       =   0.00017
Killharm_Per1_Harm_3_Coscoeff_3       =   0.00007
Killharm_Per1_Harm_4_Sincoeff_3       =   0.00015
Killharm_Per1_Harm_4_Coscoeff_3       =  -0.00015
Killharm_Per1_Harm_5_Sincoeff_3       =   0.00012
Killharm_Per1_Harm_5_Coscoeff_3       =   0.00023
Killharm_Per1_Harm_6_Sincoeff_3       =  -0.00011
Killharm_Per1_Harm_6_Coscoeff_3       =  -0.00006
Killharm_Per1_Amplitude_3             =   0.10012
Mean_Mag_4                            =  10.11187
RMS_4                                 =   0.00200
Expected_RMS_4                        =   0.00102
Npoints_4                             =  3313
TFA_MeanMag_6                         =  10.11766
TFA_RMS_6                             =   0.03555
Killharm_Mean_Mag_7                   =  10.12162
Killharm_Period_1_7                   =     1.23583047
Killharm_Per1_Fundamental_Sincoeff_7  =   0.04303
Killharm_Per1_Fundamental_Coscoeff_7  =   0.02062
Killharm_Per1_Harm_2_Sincoeff_7       =   0.00119
Killharm_Per1_Harm_2_Coscoeff_7       =   0.00122
Killharm_Per1_Harm_3_Sincoeff_7       =   0.00029
Killharm_Per1_Harm_3_Coscoeff_7       =  -0.00134
Killharm_Per1_Harm_4_Sincoeff_7       =  -0.00144
Killharm_Per1_Harm_4_Coscoeff_7       =  -0.00052
Killharm_Per1_Harm_5_Sincoeff_7       =   0.00032
Killharm_Per1_Harm_5_Coscoeff_7       =  -0.00036
Killharm_Per1_Harm_6_Sincoeff_7       =  -0.00006
Killharm_Per1_Harm_6_Coscoeff_7       =  -0.00079
Killharm_Per1_Amplitude_7             =   0.09712
Mean_Mag_8                            =  10.11188
RMS_8                                 =   0.00723
Expected_RMS_8                        =   0.00102
Npoints_8                             =  3313
TFA_SR_MeanMag_10                     =  10.11796
TFA_SR_RMS_10                         =   0.03655
Killharm_Mean_Mag_12                  =  10.12173
Killharm_Period_1_12                  =     1.23583047
Killharm_Per1_Fundamental_Sincoeff_12 =   0.04509
Killharm_Per1_Fundamental_Coscoeff_12 =   0.02147
Killharm_Per1_Harm_2_Sincoeff_12      =   0.00034
Killharm_Per1_Harm_2_Coscoeff_12      =   0.00010
Killharm_Per1_Harm_3_Sincoeff_12      =   0.00017
Killharm_Per1_Harm_3_Coscoeff_12      =  -0.00001
Killharm_Per1_Harm_4_Sincoeff_12      =   0.00005
Killharm_Per1_Harm_4_Coscoeff_12      =  -0.00017
Killharm_Per1_Harm_5_Sincoeff_12      =   0.00009
Killharm_Per1_Harm_5_Coscoeff_12      =   0.00014
Killharm_Per1_Harm_6_Sincoeff_12      =  -0.00012
Killharm_Per1_Harm_6_Coscoeff_12      =  -0.00007
Killharm_Per1_Amplitude_12            =   0.09998
Mean_Mag_13                           =  10.11183
RMS_13                                =   0.00183
Expected_RMS_13                       =   0.00102
Npoints_13                            =  3313

Name                                  = EXAMPLES/3.starspot
Mean_Mag_0                            =  10.18727
RMS_0                                 =   0.02402
Expected_RMS_0                        =   0.00104
Npoints_0                             =  3417
Period_1_1                            =     3.07960303
AOV_1_1                               = 2861.35783
AOV_SNR_1_1                           = 605.83431
AOV_NEG_LN_FAP_1_1                    = 4755.85353
Killharm_Mean_Mag_3                   =  10.18395
Killharm_Period_1_3                   =     3.07960303
Killharm_Per1_Fundamental_Sincoeff_3  =  -0.01015
Killharm_Per1_Fundamental_Coscoeff_3  =  -0.02571
Killharm_Per1_Harm_2_Sincoeff_3       =   0.00906
Killharm_Per1_Harm_2_Coscoeff_3       =   0.01009
Killharm_Per1_Harm_3_Sincoeff_3       =  -0.00185
Killharm_Per1_Harm_3_Coscoeff_3       =  -0.00049
Killharm_Per1_Harm_4_Sincoeff_3       =  -0.00401
Killharm_Per1_Harm_4_Coscoeff_3       =   0.00008
Killharm_Per1_Harm_5_Sincoeff_3       =   0.00318
Killharm_Per1_Harm_5_Coscoeff_3       =  -0.00045
Killharm_Per1_Harm_6_Sincoeff_3       =  -0.00149
Killharm_Per1_Harm_6_Coscoeff_3       =  -0.00022
Killharm_Per1_Amplitude_3             =   0.05709
Mean_Mag_4                            =  10.18396
RMS_4                                 =   0.00526
Expected_RMS_4                        =   0.00104
Npoints_4                             =  3417
TFA_MeanMag_6                         =  10.18678
TFA_RMS_6                             =   0.02225
Killharm_Mean_Mag_7                   =  10.18344
Killharm_Period_1_7                   =     3.07960303
Killharm_Per1_Fundamental_Sincoeff_7  =  -0.01043
Killharm_Per1_Fundamental_Coscoeff_7  =  -0.02290
Killharm_Per1_Harm_2_Sincoeff_7       =   0.00982
Killharm_Per1_Harm_2_Coscoeff_7       =   0.00950
Killharm_Per1_Harm_3_Sincoeff_7       =  -0.00044
Killharm_Per1_Harm_3_Coscoeff_7       =  -0.00123
Killharm_Per1_Harm_4_Sincoeff_7       =  -0.00238
Killharm_Per1_Harm_4_Coscoeff_7       =   0.00067
Killharm_Per1_Harm_5_Sincoeff_7       =   0.00269
Killharm_Per1_Harm_5_Coscoeff_7       =  -0.00121
Killharm_Per1_Harm_6_Sincoeff_7       =  -0.00152
Killharm_Per1_Harm_6_Coscoeff_7       =  -0.00013
Killharm_Per1_Amplitude_7             =   0.05327
Mean_Mag_8                            =  10.18380
RMS_8                                 =   0.00805
Expected_RMS_8                        =   0.00104
Npoints_8                             =  3417
TFA_SR_MeanMag_10                     =  10.18717
TFA_SR_RMS_10                         =   0.02379
Killharm_Mean_Mag_12                  =  10.18425
Killharm_Period_1_12                  =     3.07960303
Killharm_Per1_Fundamental_Sincoeff_12 =  -0.00973
Killharm_Per1_Fundamental_Coscoeff_12 =  -0.02591
Killharm_Per1_Harm_2_Sincoeff_12      =   0.00864
Killharm_Per1_Harm_2_Coscoeff_12      =   0.00976
Killharm_Per1_Harm_3_Sincoeff_12      =  -0.00198
Killharm_Per1_Harm_3_Coscoeff_12      =   0.00004
Killharm_Per1_Harm_4_Sincoeff_12      =  -0.00381
Killharm_Per1_Harm_4_Coscoeff_12      =  -0.00022
Killharm_Per1_Harm_5_Sincoeff_12      =   0.00297
Killharm_Per1_Harm_5_Coscoeff_12      =  -0.00065
Killharm_Per1_Harm_6_Sincoeff_12      =  -0.00139
Killharm_Per1_Harm_6_Coscoeff_12      =  -0.00004
Killharm_Per1_Amplitude_12            =   0.05705
Mean_Mag_13                           =  10.18388
RMS_13                                =   0.00449
Expected_RMS_13                       =   0.00104
Npoints_13                            =  3417

This example is the same as Example 1, except that this time we use phase-binning to determine the signal to preserve while filtering the noise, rather than fitting a harmonic series. In addition to filtering EXAMPLES/2, we also filter EXAMPLES/3.starspot. In this example we use the -aov command to search for the period rather than -LS, and we include 5 higher-order harmonics in the -Killharm commands (to give a somewhat better fit to the non-sinusoidal starspot signal). In this case the values for dotfafirst tfathresh and maxiter which are supplied to the -TFA_SR command matter. In this case -TFA_SR will iterate between binning the light curve to define the signal, and applying -TFA to the residual light curve to filter the noise. Setting dotfafirst=0 has the signal measured first before applying TFA (this is generally the best approach), we set tfathresh=0.001 and maxiter=100 to set the conditions for when the iteration will terminate. We use 100 bins and do the binning in phase rather than time (by giving the "period" keyword), and we use "aov" is the source for the period.

Example 3.
$ ./vartools -l EXAMPLES/lc_list_tfa_sr_decorr -oneline -rms \
    -savelc \
    -decorr 1 1 1 0 1 1 2 0 \
    -rms -restorelc 1 \
    -TFA EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa 25.0 xycol 2 3 1 0 0 \
    -decorr 1 1 1 0 1 1 2 0 \
    -rms -restorelc 1 \
    -TFA_SR EXAMPLES/trendlist_tfa EXAMPLES/dates_tfa \
        decorr 0 1 1 2 \
        25.0 xycol 2 3 1 \
        1 EXAMPLES/OUTDIR1 1 EXAMPLES/OUTDIR1 \
        0 0.001 100 bin 100 \
    -o EXAMPLES/OUTDIR1 nameformat %s.test_tfa_sr_decorr \
    -decorr 1 1 1 0 1 1 2 0 \
    -rms -restorelc 1

Name                        = EXAMPLES/1
Mean_Mag_0                  =  10.24745
RMS_0                       =   0.15944
Expected_RMS_0              =   0.00101
Npoints_0                   =  3122
Decorr_constant_term_2      =     10.0830375984825
Decorr_constant_term_err_2  =      0.0000325849746
LCColumn_1_coeff_1_2        =      0.0097933162509
LCColumn_1_coeff_err_1_2    =      0.0000059117875
LCColumn_1_coeff_2_2        =      0.0002554062775
LCColumn_1_coeff_err_2_2    =      0.0000001956124
Decorr_chi2_2               =      6.68601
Mean_Mag_3                  =  10.24728
RMS_3                       =   0.00211
Expected_RMS_3              =   0.00101
Npoints_3                   =  3122
TFA_MeanMag_5               =  10.24577
TFA_RMS_5                   =   0.15642
Decorr_constant_term_6      =     10.0894399398392
Decorr_constant_term_err_6  =      0.0000325849746
LCColumn_1_coeff_1_6        =      0.0092745178509
LCColumn_1_coeff_err_1_6    =      0.0000059117875
LCColumn_1_coeff_2_6        =      0.0002510444516
LCColumn_1_coeff_err_2_6    =      0.0000001956124
Decorr_chi2_6               =    945.72347
Mean_Mag_7                  =  10.24429
RMS_7                       =   0.02623
Expected_RMS_7              =   0.00101
Npoints_7                   =  3122
TFA_SR_MeanMag_9            =  10.24745
TFA_SR_RMS_9                =   0.15944
Decorr_constant_term_11     =     10.0830881231895
Decorr_constant_term_err_11 =      0.0000325849746
LCColumn_1_coeff_1_11       =      0.0097704933097
LCColumn_1_coeff_err_1_11   =      0.0000059117875
LCColumn_1_coeff_2_11       =      0.0002562034043
LCColumn_1_coeff_err_2_11   =      0.0000001956124
Decorr_chi2_11              =      5.15430
Mean_Mag_12                 =  10.24732
RMS_12                      =   0.00188
Expected_RMS_12             =   0.00101
Npoints_12                  =  3122

This example illustrates the use of simultaneous decorrelation against light-curve specific trends. In this case we process the light curve EXAMPLES/1 and give the "decorr" keyword to the -TFA_SR command. We set iterativeflag=0 after the "decorr" keyword to have the routine simultaneously fit the light-curve specific trends and the TFA templates given in EXAMPLES/trendlist_tfa (this is more correct than if we iterated, but would run significantly slower than the iterative procedure if we were processing several light curves). We read in one column to decorrelate from the light curve (set Nlcterms=1), we take that to be the first column in the light curve (set lccolumn1=1; the JD in this case) and we fit a 2nd order polynomial in that term (set lcorder1=2). We still have to provide a source for the signal in addition to the decorrelation, in this case we use binning with 100 bins (as in Example 2), but we do not provide a period (so the binning is done in time rather than phase). In this example we use the -decorr command rather than -aov and -Killharm to illustrate how -TFA vs. -TFA_SR affects the light curve. Note that -TFA_SR does not reduce the signal, the way -TFA does, but does reduce the residual RMS compared with not applying trend-filtering at all.