File Exchange

image thumbnail

UTide Unified Tidal Analysis and Prediction Functions

version 1.0.0.0 (387 KB) by Daniel Codiga
Sea level & vector current; irregular times; confidence intervals; constituent selection diagnostics

42 Downloads

Updated 06 Mar 2017

View License

[ If you have questions, instead of leaving a note in "comments and ratings" below, please contact me at dcodiga@uri.edu ]
Unified Tidal Analysis and Prediction Using the “UTide” Matlab Functions

* Designed specifically to handle record times that are irregularly distributed and/or gappy.

* Suitable for multi-year analyses: accurate nodal/satellite corrections are not limited to record lengths shorter than 1-2 years.

* Can provide easy-to-use and comprehensive diagnostics to aid the constituent selection process.

* Handles sea level (amplitude and phase), or currents (current ellipse parameters), with similar syntax.

* Generates confidence intervals based on spectra (FFT for regular times, Lomb-Scargle for irregular times) of the residuals between the raw input and the harmonic fit.

* Incorporates the robust L1/L2 solution method to minimize influence of outliers.

* Enables analysis of groups of time sequences (such as records from an array of instruments, or from a group of model gridpoints) with one m-function call.

* Builds on, and integrates in to a common framework, the t_tide (Pawlowicz et al 2002), r_t_tide (Leffler and Jay 2009), and "versatile" (Foreman et al 2009) approaches.

* Flexible interface with mix-and-match choices of analysis configurations accessible by arguments to m-functions.

* Download the m-files together with the technical report / user’s manual describing them here: ftp://www.po.gso.uri.edu/pub/downloads/codiga/utide/UTideCurrentVersion.zip

Technical Report / User’s Manual:
Codiga, D.L., 2011. Unified Tidal Analysis and Prediction Using the UTide Matlab Functions. Technical Report 2011-01. Graduate School of Oceanography, University of Rhode Island, Narragansett, RI. 59pp.
ftp://www.po.gso.uri.edu/pub/downloads/codiga/pubs/2011Codiga-UTide-Report.pdf

Also note:

1. The file UTideCurrentVersion.zip, containing the m-files, is also available at ResarchGate (researchgate.net)

2. For a python adaptation see: https://github.com/wesleybowman/UTide

Comments and Ratings (35)

Daniel Codiga

Hi Cristina
The syntax for ut_solv(), when treating 1D input like sea level, is:
coef = ut_solv ( t_raw, sl_raw, [], lat, cnstit , {options} );
Notice that there is a [ ] input required, between the sl_raw and lat inputs-- that is what the code uses, in order to know whether you are treating the 1D or 2D case (in the 2D case, you pass in u_raw and u_raw instead of sl_raw and [ ] ).
Did you include the [ ]?
To continue the conversation please email me directly (see the comment I just posted, below, just prior to this comment) rather than continue posting comments here.
Hope this helps,
Dan

Daniel Codiga

All,

If you are using UTide and you have questions please email me directly at dcodiga@uri.edu. (Note: the old email address, d.codiga at gso.uri.edu, has been retired and will no longer work.) If you instead post a question here it may be a lot longer before I am able to respond.

Before contacting me please do read the User's Guide / Technical Report because it may likely help you answer your own question. But if you still have a question, no problem, I don't mind trying to help.

When explaining your question, give context for what your overall goal is, and if appropriate then mention the relevant page or section of the User's Guide.

Also, if you are getting an error, then when you contact me be sure provide both the error message and the syntax of the call to ut_solv() or ut_reconstr() that you made, which resulted in the error.

Cheers,
Dan

Hi Daniel,
I'm sorry if my question sounds stupid, but I'm a bit stuck using the Utide. I want to predict the tide for a specific period based on seawater levels. I already have time and the sea level renamed 't_raw' and 'sl_raw', and I've specified the constituents I'm considering. When I run it though, I get an error in line 381 displayed as "Error in ut_solv (line 381) if isequal(sum(size(uin)>2),1) % single record". It seems to me that this is a velocity vector, for a 2D case while I'm on a 1D scenario. What does it mean, and how can I fix it?

I also removed {options} from my general expression, and it says that there are not enough input arguments. Any clue?

Your help is appreciated.

Cheers
Cristina

Daniel Codiga

Hi Simon
Sounds like adding 'OLS' as input to your ut_solv() call helped resolve your issue. Lots of users find that to be the case: the default is the robust solver, but for many use cases robust may be unnecessary and lead to problems, so I wish I had made OLS (which turns off robust and uses ordinary least squares instead) the default.

Hi Andrew
Your syntax wasn't quite right at first-- and in your case OLS also helped-- but I'm glad you've got it going properly now.

Hope this helps,
Dan

Andrew BELL

Hi Dan, I keep getting an error message
"ut_solv: SWITCH expression must be a scalar or a character vector.

Error in ut_solv>ut_slvinit (line 1454)
switch(lower(args{1}))

Error in ut_solv>ut_solv1 (line 816)
ut_slvinit(tin,uin,vin,cnstit,varargin);

Error in ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});"

I am a newby to MATLAB, so if can keep the answer in easy English please? ;-) Many thanks
Andy

Simon

Thank you Dan - email sent.

Hi Simon
Please send me (at dcodiga@uri.edu) the syntax of the call that you are making and I'll be happy to look in to what is going on.
Thanks
Dan
dcodiga@uri.edu

Simon

Much as I prefer to use U-tide for its advantages over older systems, the unreliability is vexing. This particular error is new to me. Can anybody help?

conf. int'vls ... Error using mvnrnd (line 112)
SIGMA must be a symmetric positive semi-definite matrix.
Error in ut_solv>ut_solv1 (line 1097)
mCall = mvnrnd([Xu(c) Yu(c) Xv(c) Yv(c)],...
Error in ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});

Hi John,
Thanks for emailing me directly. As I mentioned:
* There is no way to exclude one or more chosen constituents (such as Sa and/or SSa).
* For an example of specifying a particular set of constituents you DO want to include, try
cnstit = {'M2 '; 'S2 '; 'N2 '; 'K1 '; 'O1 ';}; % each entry is a 4-character string
and then pass in cnstit in place of 'auto'.
* Using a minimum SNR threshold is an easy way to keep only the constituents that 'matter', for a given fit.
The Technical Report explains these topics in more detail.
Hope this helps,
Dan

Code is running great. I do have a question about the Sa and SSa components. I am performing my tidal analysis in 1-year chunks. UTide will compute SSa but not Sa, which is expected. However, my thought is that I would rather the code not produce either. Or force UTide to use known values as determined by NOAA (e.g., https://tidesandcurrents.noaa.gov/harcon.html?unit=0&timezone=0&id=8557380&name=Lewes&state=DE). Any suggestions on how I could handle this? Thanks.

Daniel Codiga

Hi Diana
For some datasets, this sometimes happens when using the default confidence interval calculation method, which computes the spectra of the residuals. If you try including 'White' as an input to your ut_solv() call and the error no longer occurs, that likely was the problem. When using 'White' a white noise floor is assumed and the spectral calc is skipped. If doing that is acceptable for your purposes, it is a one solution to get past the error. See the Technical Report for more details.
Dan

Hi Dan,

I am experiencing difficulty in fixing this error:
Error using eig Input to EIG must not contain NaN or Inf (upon checking my data does not have any of this value)

Another error is ut_solv at lines 2467 and 1059

Hope you can help me. Thanks

Hi Thomas
Did you try this yet?
cnstit = 'auto'
Dan

Thomas Eiff

Hi Dan,

For my thesis research on bi-variate extremes I need to reconstruct tides for a Vietnamese station. Somehow my input values seem incorrect. My raw data consist of datenum and absolute SWL values but both with some NaN’s. Error statement:

ut_solv: Error using error
The message must be specified as either a character vector, string scalar, or a message
structure.

Error in ut_solv>ut_cnstitsel (line 1642)
error(['ut_solv: unrecognized non-reference constituent: '...

Error in ut_solv>ut_solv1 (line 820)
[nNR,nR,nI,cnstit,coef] = ut_cnstitsel(tref,opt.rmin/(24*lor),...

Error in ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});

The trouble seems to occur from the cnstit variable, have I defined it in a wrong way?
cnstit = [string('auto')];
I tried a lot of different inputs but can’t seem to find the error.
Any quick solution for this?

Kind Regards,

Thomas Eiff

Meagan Lowe

Hi again,
I managed to solve my issue and get UTide running successfully - many thanks for the great program!
Cheers,
Meagan

Meagan Lowe

Hi Dan,
I'm trying to run UTide and am getting the following error. I'm quite new to MatLab and have had no luck googling a possible solution. Any advice would be much appreciated!

>> coef = ut_solv ( t_raw, sl_raw, [], lat, cnstit )
ut_solv: Undefined function 'isnan' for input arguments of type 'datetime'.

Error in ut_solv>ut_slvinit (line 1380)
tgd = ~isnan(tin);

Error in ut_solv>ut_solv1 (line 816)
ut_slvinit(tin,uin,vin,cnstit,varargin);

Error in ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});

Thanks in advance!
Meagan

Daniel Codiga

Hello yudi30,
Please take a look at the Technical Report. It includes examples of the function syntax.
If you have further questions, email me at d.codiga@gso.uri.edu directly.
Hope this helps,
Dan

yudi30

Thanks for advance
This code is excellent but i still hard to understand it,
If you do not mind, Would you like to give me some examples...
I just want make a nodal correction for some harmonic constituent such as M2, K1, etc

Thanks for your help

Hi Roy van Weerdenburg

I did not incorporate IRLS weighting parameters in to the output structure (coef) generated by the harmonic fit solver ut_solv().

So you would need to do some customizing of the code to get those parameters out. For a one-time run Iit shouldn't be too hard to throw in a 'keyboard' command right before the call to the IRLS solve command, then execute it manually, and use the capabilities of the built-in Matlab function to obtain the weighting parameters etc.

Good luck
Dan

---

Hi corvianawatie,

That common error almost always results from the fact that you don't have the needed toolbox (with Robust Fitting) installed. You should be able to avoid the error by including the 'OLS' flag in your call to ut_solv(), which will mean the ordinary least squares solver gets used (instead of the robust solver, which you apparently are missing). In many cases 'OLS' is a better choice anyway, unless you have some specific reason to be using the IRLS method. This is all explained in the User's Guide Technical Report-- search it for 'OLS'.

Good luck,
Dan

---

Hi dong nguyen,

Basically, the output of the ut_solv() function is called coef; and the input to the ut_reconstr() function is coef. The syntax is explained in detail in the User's Guide Technical Report. See page 41, for example.

Good luck,
Dan

---

All,

The best way to reach me is directly by email to d.codiga@gso.uri.edu.
If you post a question here it may take a long while before I respond.

Cheers
Dan

@Daniel Codiga: Thank you for the great work and the excellent user manual!

@Discussion: What is the best way to derive the weighting parameters that were eventually used in the IRLS method? I would like to see the weighting factors for each data point to see how much of the storm in my dataset is still affecting the outcome, like for example in fig 4b in Leffler and Jay (2008). Are the factors hidden somewhere in the output structure or can I derive them easily? Would be great.

coef= ut_solv(datenew,elv,[],-6.0,'auto');
ut_solv: matrix prep ... sol'n ... Undefined function 'robustfit' for input arguments of type 'double'.

Error in ut_solv>ut_solv1 (line 881)
[m,solnstats] = robustfit(B,ctranspose(xraw),...

Error in ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});

How to solve this one?

dong nguyen

What is a coef of Ut_solv? How to run ut_reconstr? Please help me.

Daniel Codiga

Hi Yi Fei Zhao,
Your error is in the confidence interval calculation and your call to ut_solv() is using the default method for calculation of confidence intervals (based on Monte Carlo and spectral residuals). This can happen for various reasons depending on the details of the dataset (irregular times or not, tidal signal to noise, etc. My first suggestion is for you to instead try the linearized method (add parameter 'LinCI') and/or the white spectral assumption (add parameter 'White'), for the confidence interval calculations-- unless you have specific reasons not to. This should clear up your problem. In addition you may want to use the ordinary least squares method (parameter 'OLS') instead of the default robust solver. These issues are all explained in the Technical Report. I have other suggestions as well, for example if you still want to get the Monet Carlo spectral residuals method (default) for confidence intervals to work--but if that would be helpful it will be best if you contact me directly by email at d.codiga@gso.uri.edu to continue the conversation.
Good luck,
Dan

Yi Fei Zhao

Hi, I want to run ut_solv(tin,uin,vin,lat,cnstit,varargin) with u_raw and v_raw, but it appears the error:
>> ut_solv(TIME,u1,v1,40.23,'auto')
ut_solv: matrix prep ... sol'n ... conf. int'vls ... wrong usage eig
EIG input can not contain NaN or Inf。

Error: ut_solv>ut_nearposdef (line 2463)
if all(eig(cov)>=0)

Error: ut_solv>ut_solv1 (line 1092)
varcov_mCc(c,:,:) = ut_nearposdef(squeeze(...

Error: ut_solv (line 382)
coef = ut_solv1(tin,uin,vin,lat,cnstit,varargin{:});
Both u and v are real, and the same size with TIME. I have no idea how to deal with it, can you help me?
Thank you!!!

Hi Tomi
Please read section III B on page 39 of the Technical Report. It tells you specifically what other parts of the report to read first, in order to get going the fastest. An concise introduction to the syntax is given in section III C on page 40. If you have additional questions email me at d.codiga@gso.uri.edu.
Good luck,
Dan

Tomi Aris

anybody help me give an easy tutorial using utide?
i'm sorry i don't know what should i do to use t-tide,.. i need it for my research
thanks

Daniel Codiga

prashanth J -- It seems your copy of ut_solv may have somehow become corrupted? I suggest downloading a fresh copy.

skykeithtr -- The first three inputs to ut_solv are t, u, and v. In the case of sea level data, one passes in t, u, and []. Try the command coef = ut_solv(t_raw,sl_raw,[],lat,'auto') instead of your "coef = ut_solv ( t_raw, sl_raw, lat, 'auto' );"

prashanth J

Hi, When I try to run ut_solv command I am getting following error.

coef = ut_solv(t_raw,sl_raw,[],lat,'auto');

However,appears the error:

??? Error: File: ut_solv.m Line: 914 Column: 14
Expression or statement is incorrect--possibly unbalanced (, {, or
[.

Anyone could help me??

skykeithtr

Hi,
I was using this code with my data:
"coef = ut_solv ( t_raw, sl_raw, lat, 'auto' );"
and it appears:
"Error using statrobustfit (line 21)
Not enough points to perform robust estimation."

The data length is 259 with a time interval of 9.9156 days. But it contains 95 points of NaNs in the t_raw.

Could somebody help me?
Thanks in advance

Ben Modra

Robert

Excellent and easy-to-use functions with in-depth documentation. Particularly useful for analysis and forecasting tides using measurement data with gaps in the measurement.

Daniel Codiga

Hi Rita,

Thanks for sending the data, then helping troubleshoot this problem until we were able to confirm it was associated with using an older (~2005) Matlab version. I wrote UTide using a ~2010 Matlab version.

Glad you were able to use a 2012 version of Matlab, and get UTide to work for your project.

Dan

p.s. To others who have questions the best way to reach me is directly at d.codiga@gso.uri.edu, as opposed to posting your question here.

Rita

Hi!
I have the same error than Eva, when I try to do a sea-level analysis...
Anyone could hel me/us??
Thanks

Eva

Hi!
I was trying to use this code with my data obtained from Vessel Mounted ADCP (with irregular intervals), in the way:

coef=ut_solv(t,u,v,42.25,'auto')

where,

t= detenum vector
u=real component of velocity
v=imaginary component of velocity

However,appears the error:

??? Error: File: ut_solv.m Line: 914 Column: 14
Expression or statement is incorrect--possibly unbalanced (, {, or
[.

Anyone could help me??
It would possible that I can't use the selection algorithm for some reason??

Thanks in advance

Updates

1.0.0.0

Added note about ResearchGate

1.0.0.0

Added link to python adaptation.

1.0.0.0

Direct contact info added

MATLAB Release Compatibility
Created with R2010a
Compatible with any release
Platform Compatibility
Windows macOS Linux