CMGTooL User's Manual

CMGTooL LIBRARY

The CMGTooL GUI is designed to provide a user-friendly analyzing tool of oceanographic data to the users who would like to utilize the powerful MATLAB processing capability, but might not be proficient in the MATLAB language itself. A shortcoming of the GUI is that it cannot be run in a batch mode. The CMGTooL library was therefore developed to not only enable batch processing of most of the GUI functions, but also to provide a basic data processing toolbox that experienced MATLAB users, who may prefer command-line computing, can utilize. Below, the library functions are listed alphabetically and briefly described. All the programs here are stand-alone routines, many of them are not included in the CMGTooL GUI.

Function: adr2mat (PC and UNIX only)

Purpose: Read the binary file from an ADV recorder into a Struct in the workspace.

Syntax: [xyz] = adr2mat (adrname, [btORbk])

Input:adrname: the binary file name, a string;

btORbk -when it is bk (blocksize): An integer value in MB, optional. It allows users to save the struct (xyz), read from a LARGE binary file, into multiple mat files when the computer memory is limited.

btORbk<=0, No mat file saved, same as btORbk being omitted, default.

btORbk>0, divides the binary file into blocks of [btORbk] (approximately) MB and saves each block, along with the metadata, into a mat file identified by the ADV serial number. The saved file could be several times larger than btORbk MB.

btORbk -when it is bt (burst range): In the form of [b0, b1] where b0 and b1 represent the starting and ending burst numbers. It MUST have two values and b1 >= b0.

Output: xyz: The Struct that holds everything, optional

Function: adr2nc (PC and UNIX only)

Purpose:To read a binary file (*.adr) from an ADV recorder and write the data into a netcdf file. The new file has the same base name but with the '.nc' extension.

Syntax: adr2nc (adrname)

Input:adrname: a string, the name of binary *.adr file

Output: none

Function: advmat2nc (PC and UNIX only)

Purpose:Creates a NetCDF file from a Struct generated by adr2mat

Syntax: advmat2nc (mystruct, [ncfilename])

Input:mystruct: the struct created using adr2mat

ncfilename: optional. the netcdf file name (a string).

Output: ;none

Example:advmat2nc (xyz, 'southcal.nc')

advmat2nc(xyz); which create a netcdf file named 'xyz.nc'

Function: cmgadcpview

Purpose:View profile of ADCP data

Syntax: cmgadcpview (jdaytime, east,north [,dep, angle]); -To view ADCP data that already in the MATLAB workspace.

cmgadcpview (fname, uname, vname [,dname, angle]); -To view ADCP data from a NetCDF file. Require NetCDF capability on your system, use ncdump to see the names U, V, and depth

Input:jdaytime = time in true Julian dates

east,north = the east and north components of ADCP data matrix of size (M x N) where M = length of jdaytime

dep = array of water depths where measurements are made, OPTIONAL

fname = a text string of the NetCDF file name

uname, vname = the text strings of the east and north velocity components (make sure they exist in the file).

dname = a text string of the depth, OPTIONAL

Output: none

Function: cmgavg

Purpose:A points-averaging function

Syntax: [gout] = cmgavg (gin, theta)

Input:gin=input data vector. If gin is a matrix, each column of the matrix is treated as a vector.

theta=length of average.

Output: gout=output data.

Example:ts2 = cmgavg (ts1, 4); produces a 4-point average.

Function: cmgbridge

Purpose:To fill gaps in time-series files using Joseph's scheme (a spectral method) after filling short gaps with a linear fit from neighbors' values.

Syntax:[dat,[nogap]] = cmgbridge (dat, nlin, nmaxbr, maxngaps)

Input: dat = data to be bridged. if matrix, bridging performed on each column

nlin = max gap length to be filled linearly, optional (default =2)

nmaxtbr = max gap length to be filled spectrally, optional (default = 48)

maxngaps = max number of gaps to be filled, optional (default = 1000)

Output: nogap = 0 if gaps found, 1 if no gaps, optional;

dat = gap-filled data output

Function: cmgcdemodulate

Purpose:Complex demodulation of a vector or scalar variable

Syntax:[newt,ap,pp [,am,pm]] = cmgcdemodulate (pd, pl, t, u, [v])

Description: Based on algorithm in "Data analyses methods in physical oceanography" by W.J. Emery and R.E. Thomson, page: 402 - 404

Input:pd = the period (in hours) of interest, maybe an [Mx1] array

pl = segment length

t = time variable (in true Julian dates), [Nx1]

u = time-series of interest, [Nx1]

v = same as u, optional

Output: newt = new time at midpoint of segment, in true Julian date

ap, pp = amplitude and phase of counterclockwise components

am, pm = amplitude and phase of clockwise components, output only when v is present

The ellipse parameters may be computed from the above output

semi-major axis = ap + am

semi-minor axis = ap - am

inclination (angle between major and u) = 0.5*(pp+pm)

Function: cmgcolock

Purpose:Checks for time gap. Gaps in time are rebuilt and gaps in data are filled with NANs

Syntax:[t, data] = cmgcolock (t, [data], [dt])

Input:t = time

data = data, vector or matrix, optional.

dt = time increment of the input data, optional.

Output: t = time

data = If gaps are found, the same rows of each column are filled with NANs

Function: cmgdataclean

Purpose:Replaces bad data points with NANs

Syntax:[gout] = cmgdataclean (gin, threshold)

Input:gin = input data vector or matrix

threshold = bad data threshold. If the absolute value of the input data points are greather than is, those points are replace with NaNs. optional (default = 1.0E35)

Output: gout = output data vector or matrix

Function: cmgeof

Purpose:Empirical Orthogonal Function analysis

Syntax:[ampt, amps, sv, mv] = cmgeof (x, [,y] [,modes]);

Description: Based on Noble and Ramp (2000), Deep-Sea Res. II (47), 871-906; and Kundu and Allen (1976), JPO (6) 181-199

Input:x = data matrix (M x N), M observations and N variables. Maybe complex, in which case, y is not allowed.

y = OPTIONAL, used in complex EOF, same size as x

modes = OPTIONAL, the first [modes] number of modes are outputted, default=N

Output: ampt = temporal amplitude of each mode (M x num).

amps = spatial amplitude of each mode (N x num).

sv = site variance in percentage (N x num).

mv = modal variance in percentage (num x 1).

If complex EOF, the on-screen print-out of both amplitudes have this format AMP*exp(PHASE*i), where PHASE is in degrees

Function: cmgidgaps

Purpose:Identifies gaps in a time series

Syntax:[ngaps, nfirstbad, nlastbad, lgap] = cmgidgaps (dat, maxgaps)

Description:Adapted from a fortran program bridge.f

Input:dat = input data series. If dat is a matrix, gap search is performed columnwise.

maxgaps = max number of gaps to be filled, optional (default = 1000)

Output: ngaps = the number of gaps to fill (excludes gaps that can't be filled because they go to the end of the file)

nfirstbad,nlastbad,lgap = integer arrays containing the indices for the first bad point of each gap, the last bad point, and the length of each gap

Function:cmgmat2nc

Purpose:Converts a MATLAB workspace or MATLAB files into a NetCDF file(s)

Syntax:cmgmat2nc (ss, [matname], [cdfname]) — Converts some variables in the MATLAB workspace or a MATLAB file to a NetCDF file.

cmgmat2nc (batchname) — Converts one or multiple MATLAB files to NetCDF files

Input: ss = a cell array that lists the names of all variables (the first one MUST be the time variable) that will be saved into the new NetCDF file. Strings may be case-sensitive depending on platform. An example of ss reads like ss={'velU','velV','temperature'}.

matname = optional, the name of the MATLAB file containing all the variables. If omitted, the function will try to load variables from the base workspace.

cdfname = optional, a string designates the NetCDF file name. ONLY used when a matname is provided.

Batchname = the name of a text file that contains all information of the source files/variables that will be written into NetCDF files. The format of the text file must be strictly followed. Example batch file:

[1] test.mat :mat file name

time, velU, velV, temp :variable names

Jdays, cm/s, cm/s, degC :variable units

0, 25, 25, 25 :depth (M) where measurements were made

GMT :time zone

33 34.6 :latitude

-117 56.5 :longitude

62 :water depth (M)

USGS :data origin

656 :mooring number

OCSD, M07 mooring :description

Noble :PI

13.75EAST :magnetic variation

Time series :data type

Geographical :coordinate system

Data chopped from tail :data comment

ADV :instrument

B206 :serial number

Created using cmgmat2nc :history

Mync.nc :NetCDF file name

[2] test2.mat

[3] test3.mat

Output: none

NOTES: The timebase and all variables listed in ss will be loaded into the workspace first. So it may take a few seconds...

Function: cmgnielsen

Purpose:Computes local wave number using Nielsen (1982)'s empirical function.

Syntax:klocal = cmgnielsen (period, depth)

Input:period = vector of wave period in SECONDS

depth = vector of water depth in METERS

Output: klocal = output local wave number

Function: cmgpca

Purpose:A function for principal component analysis.

Syntax:cmgpca(u,v,[onoff]);

Input:u, v = vectors of the two components of, e.g. currents.

onoff = flag determine if data points are plotted (=1) or not (=0, default)

Output:none

Function: cmgplotspectra

Purpose:A spectral plot function.

Syntax:cmgplotspectra (specStruct, [options...])

Description:REQUIRE spectral output from cmgspectra or cmgspecavg.

Input:specStruct = Structure array that at least contains these fields:

.spec: auto- (size of M x 5) or cross- (size of M x 19) power spectra

.freq: (M x 1) frequency in Hz

.nfft: nfft used in computing the spectra

options could be one or more of the following (need not to be in order):

Plot types: AND/OR plot contents:

loglog' (default) 'auto': ploting two auto spectra

'semilogx''coquad': plotting co- and quad spectra

'semilogy''chph': plotting coherence and phase

'linear''rotary': plotting rotary spectra

'vp' (variance preserving) 'combo': plotting auto-, rotary, coherence, and phase in one plot (default).

Ouput: none

Function: cmgprintspectra

Purpose:Print spectra to a file.

Syntax:cmgprintspectra (spec Struct, [ptype], [frange])

Description:REQUIRE spectral output from cmgspectra or cmgspecavg.

Input:specStruct = Structure array that at least contains these fields:

.spec: auto- (size of M x 5) or cross- (size of M x 19) power spectra

.freq: (M x 1) frequency in Hz

.nfft: nfft used in computing the spectra

.npieces: number of pieces

.conf: confidence level

.name:

ptype = one of two choices (optional):

'chph': print auto- and cross- spectral properties (default)

'rotary': print auto- and rotary spectral properties

frange: = [low high], 2 elements define the range of period (in hours) that is interested in printing.

Function: cmgrotate

Purpose:Rotate a vector in Cartesian coordinate

Syntax:[newx, newy] = cmgrotate (east, north, theta)

[newdata] = cmgrotate (data, theta)

Input: east, north= east and north component, vector or matrix

data = [east1,north1, east2,north2, ....] with an EVEN number of columns

theta = the angle (degrees) of rotation, positive in counterclockwise

east and north must be the same size. If matrices, rotation is performed columnwise.

Output: newx, newy, newdata = data output after rotation.

Function: cmgsmoothie

Purpose:Smoothes a time-series using MATLAB function conv.m

Syntax:smoothed = cmgsmoothie (vari, [fsize]);

Input: fsize: size of a kernel, optional, (default = 3);

vari: variable to be smoothed, vector or matrix; if a matrix, convolution performed on each column.

Output: smoothed: the smoothed time-series

Function: cmgspacebuster

Purpose:Removes both the leading and trailing white spaces from string

Syntax:newstring= cmgspacebuster (oldstring)

Function: cmgspd2uv

Purpose:Creates the East and North components from speed and direction in Cartesian coordinate.

Syntax:[east,north] = cmgspd2uv (spd, direc)

Input:spd = speed

direc = direction (degrees) in true north

Output: east, north = east and north components vector or matrix

spd and direc must be the same size. If matrices, calculation is performed columnwise.

Function: cmgspecavg

Purpose:Band-averaging spectra, PROSPECT style.

Syntax:theSpec = cmgspecavg (specStruct, [nfreq])

Description: REQUIRE spectral output from cmgspectra. Modified from Chuck Denhams specav.m

Input:specStruct = Structure array from cmgspectra that contains these fields:

.spec: auto- (size of M x 5) or cross- (size of M x 19) power spectra

.freq: (M x 1) frequency in Hz

.npieces: number of pieces

.conf: confidence level

.window: no window(=0); hanned (=1)

.nfft: nfft

nfreq = optional, a (N x 2) matrix specifying a varying number of frequencies in each band, e.g. a [4 5; 10 15; 28 30] matrix specifies that there will be 4 frequencies in the first 5 band, 10 in the next 15 bands, and 28 in the next 30 bands.

Output: theSpec, is also a struct similar to the input specStruct.

Function: cmgspectra

Purpose:Computes auto- and cross- spectra.

Syntax:results=cmgspectra(x, [y], [nfft], [noverlap], [window], [fs], [p], [dflag])

Description:The output are powers, not power density.

Inputs:x = time-series, vector or matrix

y = second time-series, optional. If present, both auto- and cross- spectra are calculated, and both x and y must NOT be a matrix.

nfft = length of each section to be FFT'ed (default=256)

noverlap = length of overlap (default=nfft/2)

window = (default=hanning(nfft))

fs = sampling frequency (default=2)

p = confidence interval (default=0.95)

dflag = detrending mode (default='linear')

You can obtain a default parameter by leaving it out or inserting an empty matrix [], e.g. cmgspectra(x,y,[],128,[],2), in which nfft and window are set to default, p and dflag are left out (default).

Output: results = A struct containing the following fields:

.spec (M x 5 for auto-; M x 19 for cross- spectra)

.freq

.npieces --used in averaging in the plot routine

.nfft

.conf (a scalar, confidence level)

.window

.name

.averaged

Function: cmgstats

Purpose:Computes the error bar, mean, standard deviation, maximum and minimum of a time-series.

Syntax:cmgstats (x, [dof])

Input: x = time-series, vector or matrix. If matrix, calculations are performed along each column.

dof = degree of freedom, optional. If omitted, users are asked to choose a value of autocorrelation scale to estimate the dof.

Output: All output are printed in the command window.

Function: cmgtssview

Purpose:Displays vertical profile of temperature, salinity or density collected from moorings.

Syntax:cmgtssview (jdaytime, dep, temp);

Input:jdaytime = time vector in true Julian days

temp = temperature, salinity or density matrix of size (M x N), where M = length of jdaytime

depth = array of water depths where measurements are made

Output: none

Function: cmguv2spd

Purpose:Creates speed and direction from (u, v) in Cartesian coordinate.

Syntax:[spd, direc] = cmgspd2uv (east, north)

Input:east, north = east and north components vector or matrix

Output: spd = speed

direc = direction (degrees) in true north

east and north must be the same size. If matrices, calculation is performed columnwise.

Function: cmgwindstress

Purpose:Computes wind shear stress based on given speed, direction, and sensor height.

Syntax:[ustr, vstr] = cmgwindstress (wspd, wdir, [height])

Input:wspd = wind speed vector in m/s

wdir = wind direction vector in degrees (true North)

height = height of measurement in m above sea level. if omitted, height=10 m.

Ouput: ustr, vstr = wind stress in east and north directions.

Function:cmgxlabel

Purpose:To relabel the time axis from Julian day (or datenum) to Gregorian labels.

Syntax:cmgxlabel (jd, [hand])

Input:jd = True Julian day or datenum

hand = graphic handle, optional, default is gca

Output: none

Function: nc2struct

Purpose:Loads a NetCDF file into MATLAB workspace as a struct

Syntax: x = nc2struct (ncfilename, [vflag]);

Input:ncfilename = name of the NetCDF file

Vflag = optional. If exist, variable attributes are loaded

Output: x = optional. The struct

All global attributes are stored in the 'metadata' field. The attribute of individual variables are not loaded by default, but users have options to load them into the 'vattrib' field.

Top of Page

For more information, contact the PCMSC team.

Any use of trade, product, or firm names is for descriptive purposes only and does not imply endorsement by the U.S. Government.

Suggested citation:

Xu, Jingping, Lightsom, Fran, Noble, Marlene A., Denham, Charles, 2002, CMGTooL user's manual: U.S. Geological Survey Open-File Report 02-19, https://pubs.usgs.gov/of/2002/0019/.

U.S. Department of the Interior
SALLY JEWELL, Secretary

U.S. Geological Survey
Suzette M. Kimball, Acting Director