CMGTooL User's Manual

PROSPECT-in-MATLAB

PROSPECT is a legacy software package for spectral analysis of equally-spaced time series. The package is written for the VAX 11/780 computer at WHOI, entirely in FORTRAN 77. PROSPECT-in-MATLAB is the MATLAB adaptation of PROSPECT. It has kept some of the features that are familiar to original PROSPECT users. Many others, such as optional switches in some PROSPECT programs, are deemed unnecessary in the MATLAB computing environment and therefore not included in the adaptation. The new codes run much faster due to the matrix operation capability of MATLAB. All program script files are included in the CMGTooL library.

Following the tradition of PROSPECT, a typical PROSPECT-in-MATLAB session may be summarized in flow-charts displayed in Figure 14.

Figure 14 (39K)

Figure 14. Flow-chart of a typical PROSPECT-in-MATLAB session

5.1 Data files

PROSPECT in MATLAB assumes that all data files are in NetCDF format. In order to be able to manipulate NetCDF files, a NetCDF gateway for MATLAB, mexcdf, and the NetCDF toolbox have to be installed on your computer. All data files must be in the current directory or in a directory that is listed in MATLAB’s searching path.

5.2 Building the data matrix with cmgfbuild:

Function: cmgfbuild

Purpose: Reads all specified variables from all relevant files that are also specified in a user-defined text file.

Syntax: mydata=cmgfbuild ( infoname, [dtflag], [tflag] )

Input: infoname= name of the text file that contains the name of file-building information. See the example:

5121-a.cdf, 5123-a.nc, 5125-a.nc,5126-a.nc,5127-a.cdf :the names of input files

2, 2,2,2,2 :the number of variables in each file

east,north, u_1205, v_1206, u_1205, v_1206, u_1205, v_1206,east,north :the name of variables

3600 :delta-t in seconds

20-Nov-1997 09:00:00 :start time

04-May-1998 09:00:00 :end time

In this example, the program reads 2 variables from each of the 5 NetCDF files. If the sampling intervals of a file is different from 3600 seconds, the variables are interpolated so that all variables in the result data matrix have the same delta-t as well as the same start and stop times that are given in the last two lines of the example file.

dtflag= optional, when time-series of different dt are loaded, dtflag helps determine either the smallest (=0, default) or largest (=1) dt to use to form anew timebase. If dt is provided in the infoname file, dtflag is not used.

tflag= optional, when time-series of different lengths are loaded, tflag helps determine either to shrink (=0, default) or expand (=1) in forming a new timebase.

Output: mydata: a structure array that contains the following fields.

.time: time in Julian days

.data: the data matrix (M x N)

.fname: a [1 x N] cell array providing the name of source files for each variable

.vname: a [1 x N] cell array of variable names

5.3 Pre-processing the data matrix, mydata, if necessary:

Gap-bridging: mydata.data=cmgbridge( mydata.data, …. )
Filtering: mydata.data=PL33 ( mydata.data,…. )
Rotating:mydata.data=cmgrotate( mydata.data,….a )

5.4 Computing spectral properties using SPECACR:

Function: SPECACR

Purpose: Spectra estimator

Syntax: myspec = SPECACR ( mydata, infoname )

Input: mydata: the struct variable generated by cmgfbuild.m

infoname: Name of a file that contains parameters used in spectral computation. An example is listed below (the format must be strictly followed):

------ information used in SPECACR.M ---------

[1,2], [1,12], [2,11] : specify which pairs of variables to compute spectra

[ ] :starting point, default is 1

[ ], :length to use, default is to use entire series

[ ] :band-avg param, ****SEE BELOW FOR DETAIL****

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

0 :length of overlap (default=0)

boxcar :windowing (hanning or boxcar) (default=boxcar)

3600 :sampling interval in seconds (default=0.5)

0.95 :confidence interval (default=0.95)

none :detrending mode (default=none)

****DETAIL OF BAND AVERAGING INPUT****

if the entry is [ ]

use the default ([1,40], [2,15], [5,6], [10,30], [20,15], [50,6], [100,30], [200,15], [500,6])

if the entry is 0,

there will be no band averaging

if the entry is an scalar > 1,

using the same number of freq in each band

if the entry is like [4,5], [10,15], [28,30]...

using the actual input

****DETAIL OF BAND AVERAGING INPUT****

Output: myspec: A struct array, each of the N elements contains the following fields.

myspec (1:N).spec (M x 5 for auto-; M x 19 for cross- spectra)

myspec (1:N).freq

myspec (1:N).npieces --used in averaging in the plot routine

myspec (1:N).nfft

myspec (1:N).conf (a scalar, confidence level)

myspec (1:N).window

myspec (1:N).name

myspec (1:N).averaged

5.5 Generating spectral plots using SPECPLT:

Function: SPECPLT

Purpose: Creates spectral plot

Syntax: SPECPLT ( myspec, fname, [options…])

Input: myspec: see above.

fname: base string for filenames of plotted graphics.

options: (optional)

one of the following output types:

'jpeg' (default)

'ill'

'epsc'

AND/OR

one of the following plot types:

'loglog' (default)

'semilogx'

'semilogy'

'linear'

'vp' (variance preserving)

AND/OR

one of the following plot contents:

'auto': ploting two auto spectra

'coquad': plotting co- and quad spectra

'chph': plotting coherence and phase

'rotary': plotting rotary spectra

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

Output: There is no output into the MATLAB workspace. Each and every appears briefly on screen before being overlaid bye the next plot. All plots are saved to files whose name are specified by the graphic format, plot content, and pair number. These files are stored in the current directory.

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