Readme for r_t_tide (t-tide v1.03)
r_t_tide (robust t_tide) is an experimental fork of t-tide v1.1, originally written by Rich Pawlowicz
and modified by Keith Leffler
Many thanks to Rich for making the code available.
The original t-tide is described in
R. Pawlowicz, B. Beardsley, and S. Lentz, "Classical tidal harmonic analysis including error estimates in MATLAB using T_TIDE", Computers and Geosciences 28 (2002), 929-937.
The modifications in r_t_tide are described in
K Leffler, DA Jay, "Enhancing tidal harmonic analysis: Robust (hybrid L1/L2) solutions", Continental Shelf Research, 29, 78-88.
Please cite both if you find the code useful.
Differences from t_tide:
--------------------------------------------------------------------------------------
A r_ has been added to all the function names, to
distinguish from the original t_tide. Most functions are nearly identical to
the t_tide original. Additional files from the original are mostly code that was formerly a subfunction
somewhere, or was duplicate code.
The major differences between t_tide.m and r_t_tide.m are in the arguements.
r_t_tide REQUIRES that the sample time be passed in as the first arguement. The other
major difference is that r_t_tide accepts a method parameter. This is passed in as an arguement
name/value pair: For example :
[name,freq,tidecon,xout] = r_t_tide(t,x,'method','cauchy');
method can be any of the weight functions supported by the Matlab (Statistics Toolbox) function
robustfit. The default value is 'ols', which causes r_t_tide to
use Ordinary Least Squares, the method implemented by the original t_tide.
The supported methods are 'ols','andrews','bisquare','cauchy','fair','huber','logistic','talwar', and 'welsch'.
The arguement is not case sensitive, but the spelling must be correct.
By default, the tuning constant (refer to the robustfit documentation) is set to the Matlab default
when the method is set. We have found that better results are obtained by reducing the tuning constant
by some factor. (default value)/3 tend to give good results. Reducing the tuning constant too much will eventually
cause the algorithm to fail to converge, regardless of the number of iterations (see next section). The code is written so it should not matter if the tuning constant or
method is set first.
--------------------------------------------------------------------------------------
Possible error : robustfit sets an iteration limit, which is sometimes too low for tidal
data. A warning might be displayed that says something about 'Iteration limit reached'.
The easiest way to fix this is to simply increase the allowed number of iterations. Click on
underlined error (in the command window, if and when it shows up). Look up a few lines from
the cursor for a line that says
iterlim = 50;
In Matlab version 2008a, this was line 63 of MATLABROOT\toolbox\stats\private\statrobustfit.m
Change the 50 to something larger, like 250. Save the file ... you may have to run Matlab as root
if you're running Linux (maybe Mac as well?). You'll have to repeat this every time you use a different
computer and/or upgrade Matlab. Be warned that this change applies to everything that on your computer that uses
robustfit. It shouldn't be a problem, because the value is a limit on maximum number of iterations to
reach a stable error value. Anything that converged in 50 iterations before will converge in the same
number of iterations and give the same answer. We're just increasing number of allowed iterations, but
not changing the convergence criteria itself.