USGS Home
Contact USGS
Search USGS

ECOM-viz

A Matlab toolbox for analyzing and visualizing NetCDF output files from the Blumberg & Mellor ocean circulation models (ECOM-3D, ECOM-si, POM)

Five steps to using ECOM-viz to visualize POM output:

1. Buy MATLAB .
2. Get and build the NetCDF source code .
3. Get and build the UNIX style (compressed-tar) file or PC style (zip) file of POM source code modified to output NetCDF.
4. Get the appropriate executable of the MEXCDF NetCDF/Matlab interface for your system.
5. Get the OMVIZ distribution and run "pomdemo" from within Matlab. Also check out CSLICE , a cool point-and-click Matlab application for visualizing ECOM.CDF or POM.CDF files.

NetCDF output files

The standard output files from the Blumberg & Mellor models (ECOM-3D and POM) are in ASCII and machine-specific binary format. To allow efficient and machine-independent access to the model output, a new subroutine and small modifications to the existing Fortran code have been made to allow writing the output as NetCDF files. The NetCDF files are self-describing, machine-independent binary files that are ideally suited for numerical modeling.

For example, here is the FORTRAN routine for POM that will write the output as NetCDF files. Or if you with, here is a self-contained compressed tar file of POM code that generates an ECOMviz compatible NetCDF output file.

Running ECOM-3D creates two NetCDF files called ecom3d.cdf and tsepic.cdf, while running POM creates one NetCDF file called pom.cdf. Ecom3d.cdf contains full 1D, 2D, and 3D fields of variables averaged over IAVGE time steps, while tsepic.cdf contains time series of variables at EPTS grid locations and averaged over ISKILL time steps. The frequency of output to pom.cdf is the same as for the print file and is controlled by IPRTD1, ISWTCH, and IPRTD2.

For ECOM-3D the variables that are stored in these files is controlled by the presense of a 'Y' instead of a 'N' in the beginning of the run_data file. For POM, the switches are set in the beginning of putcdf.f

The tsepic.cdf file created by ECOM-3D use conventions that allow them to be compatible with PMEL's EPIC analysis and visualization system (in addition to the ECOM-viz system described here). Each dependent variable (temp, salt, u, v, etc.) has 4 dimensions reflecting that earth-related data exists in time and 3-space. The contents of NetCDF files may be examined from the system command line using "ncdump -h ecom.nc" or from Matlab using mexdump.

And here is a ECOM-viz compatible NetCDF output file from Massachusetts Bay , all ready to go. Use load-to-local-disk or shift-click!

Time Convention

Time is stored in the NetCDF files as two one-dimensional variables, time and time2. Time is a long integer variable containing the Julian day using the astronomical convention, but where the day starts at midnight. For example, in this convention, Julian day 2440000 begins at 0000 hours, May 23, 1968. Time2 is a long integer containing the number of milliseconds since midnight on the corresponding Julian day element of time.

In the ECOM-viz Matlab routines time is represented as decimal Julian day, typically called something like jd. Gregorian time is represented by a six-column variable where the columns contain year, month, day, hour, minute and second. Thus [1968 5 23 0 0 0] represents 0000 hours, May 23, 1968. The function gregorian converts Julian time to Gregorian time, while the function julian converts Gregorian to Julian.

Extracting data from NetCDF files

Since Matlab is limited to 2D arrays, many of the ECOM-viz routines return some type of 2D array of values -- slices along the i,j, or k model coordinates or at a fixed depth z.

• kslice - returns a scalar variable on a fixed sigma level (fixed k).
• islice - returns a scalar variable along a vertical section at fixed i. The y locations (distance along the section) are returned in km, while the z locations are in m.
• jslice - returns a scalar variable along a vertical section at fixed j. The x locations (distance along the section) are returned in km, while the z locations are in m.
• zslice - returns a scalar variable at a fixed depth z (interpolates between sigma levels).
• depave - returns depth-averaged values of a scalar variable.
• ksliceuv - returns the a complex variable containing the horizontal velocity field on a fixed sigma level (fixed k).
• zsliceuv - returns a complex matrix containing the horizontal velocity field at a fixed depth z (interpolates between sigma levels).
• depaveuv - returns depth-averaged velocity as a complex matrix.

Viewing Data Extracted from NetCDF files

• pslice - displays scalar variables as a color-shaded image. Pslice sets the aspect ratio of the plot to 1 (it assumes that you are doing horizontal sections and that your x and y coordinates are in the same distance units (km, m, etc.). It will also work for displaying vertical slices, however. Just do set(gca,'aspect',[NaN <your_ratio>]); in Matlab after the plot is drawn if you don't like the aspect ratio. (Remember that islice and jslice return distance along the slice in km, but vertical distance in m. Therefore the default behavior with pslice is to show vertical sections with vertical exaggeration of 1000.
• psliceuv - displays vector variables as a field of arrows. This routine assumes that you want to overlay the vectors on a plot that is already created, so if you want to just display vectors, plot the coastline or something first (or create the axes explicitly).
• extcontour - displays scalar variables as contour plot with optional color contour fill and contour labeling. Getting extcontour to do what you want can be a bit tricky. For example, extcontour labels every contour line, so if you want only some contour lines labeled you must call extcontour twice (using a "hold on" in between), once for the lines you don't want labeled and once for the lines you do. Another example is when you want extcontour to use the same colors on successive plots to indicate certain variable values. Here you can set(gca,'clim') explicitly after every plot to ensure that the color fill is consistent from plot to plot.