FORECAST/MATLAB PAGE

REVISION DATE: 5 MAY 1999

This page describes the MATLAB-based products that the GLOBEC/Georges Bank Data/Assimilation project needs for the on-ship postprocessing of the forecast output. The postprocessing of the forecast information relies on a collection of MATLAB toolboxes written by C. Naimie, C. Lewis, B. Blanton, among others, and is centered around the OPNML matlab toolbox. We describe here all the needed components for the generation of the standard products output and additional visialization tools (see below).

This revision includes small changes to the output plots, to include heat flux and wind stress observation plots. There are no other changes. In order to use these revisions, two additional MATLAB files must be placed in the FCAST_1.2 directory, and the files defplots.m and fcast.html must be retrieved again and placed in the forecast MATLAB directory, as always. See the section "HERE ARE THE DEFAULT PLOT SCRIPTS" below.

The versions of the products below are essentially called "1.2". This pertains to the FCAST toolbox, and the associated VIZICQ4 amd BUILDIND utilities.

Needed MATLAB stuff

OPNML/Matlab toolbox. This is the standard distribution, the last update of which is approx. 1 Feb, 1999. Goto to the OPNML/Matlab page to retrieve.
FCAST toolbox. This contains new MATLAB facilities written that are not part of the above OPNML distribution. as well as codes written by C. Lewis to plot ship track surfaces, and necessary details like the QUODDY equation of state for density computations within VIZICQ4. It also contains C Naimie's matlab_cen directory just in case. Retrieve the FCAST toolbox below.
For additional visualization, VIZICQ4 and BUILDIND will be needed. These tools are now basically stable beta-versions and can be retrieved below.
The default plotting functions defplots.m and defplot_params.m, and the two additional codes run.defplots and fcast.html.

TOOLBOX RETRIEVAL

Get the following "readme"'s (they are also included in the tar files below.

buildind_1.2 readme
fcast_1.2 readme
vizicq4_1.2 readme (Read this one first)

The following tar files should be untarred below the main OPNML toolbox location. indicated subdirectories, which must be below the main OPNML matlab directory.

fcast_1.2 untars into FCAST_1.2
buildind_1.2 untars into BUILDIND_1.2
vizicq4_1.2 untars into VIZICQ4_1.2

Add the following to your startup.m or opnmlinit.m (mix-and-match), where /usr/local/OPNML_MATLAB may depend on the details of the MATLAB and/or OPNML/matlab installation.

   addpath('/usr/local/OPNML_MATLAB/FCAST_1.2','-end') 
   addpath('/usr/local/OPNML_MATLAB/FCAST_1.2/matlab_cen','-end') 
   addpath('/usr/local/OPNML_MATLAB/FCAST_1.2/timefun','-end') 
   addpath('/usr/local/OPNML_MATLAB/VIZICQ4_1.2','-end') 
   addpath('/usr/local/OPNML_MATLAB/BUILDIND_1.2','-end')

The point is that these new directories should reside alongside the other OPNML_MATLAB directories like FDCONT, MEX, etc. For example, the path in MATLAB for the test user account fcast looks like:

   /home/fcast/OPNML_MATLAB
   /home/fcast/OPNML_MATLAB/FDCONT
   /home/fcast/OPNML_MATLAB/FEM
   /home/fcast/OPNML_MATLAB/IO_Functions
   /home/fcast/OPNML_MATLAB/MEX
   /home/fcast/OPNML_MATLAB/basics
   /home/fcast/OPNML_MATLAB/mat4
   /home/fcast/OPNML_MATLAB/FCAST_1.2
   /home/fcast/OPNML_MATLAB/FCAST_1.2/matlab_cen
   /home/fcast/OPNML_MATLAB/FCAST_1.2/timefun
   /home/fcast/OPNML_MATLAB/VIZICQ4_1.2
   /home/fcast/OPNML_MATLAB/BUILDIND_1.2

VERY IMPORTANT POINT!!

The matlab_cen directory contains an old version of the OPNML function READ_PTH that does not handle .pth files from DROG3DDT correctly. The version that behaves properly is in "OPNML_MATLAB/IO_Functions". Thus, in the above MATLAB paths, the matlab_cen path MUST come after the "OPNML_MATLAB/IO_Functions" path. Likewise, if you add the "matlab_cen" directory to your own MATLAB path elsewhere, it MUST come after all the other paths above so that there is not the possibility of function confusion. (CVL: this is the source of the problem whereby READ_PTH was returning nts=0.) Because the matlab_cen directory is contained in the FCAST_1.2 toolbox, you should not need to include the toolbox elsewhere, and the matlab_cen directory can be safely removed from the operational forecasting directories.

DESCRIPTION OF THE DEFAULT PLOTS SCRIPTS AND WEBPAGE CODE

defplots.m The default plots script "defplots.m" provides a standard set of plots from a forecast directory. It generates jpg images that the web-page code html loads for the web-posting. Currently, the script generates:
1. horizontal slices at (surf, -25 meters, bot) levels.
2. 6 transects at specified end-points
3. shiptrack ribbon plots
4. timeseries at specific locations
5. several other plots like transect locations, etc...
There are two flags in the defplots.m function that control #3 and #4 above. Since the shiptrack file (UV-INTEG_Q4.m3d) can be very large, and possibly the entire ITER*.icq4 inventory will be read, these two plot sections can be "turned off" in defplots.m with the flags SHIPTRACK and BUOYPLOTS. They are currently set to "ON". The shiptrack can be subsampled by the user at the lines marked "ALTER SHIPTRACK HERE" in defplots.m. This requires the user extract from the .m3d file only the part of the shiptrack to be plotted. It is currently unaltered; i.e. whatever track was assimilated will be plotted. NOTE: that the horizontal and vertical slices are performed on the last 3 daily average .icq4 files in the CRUISE_Q4.? directory. These correspond to the 3 forecast days.
defplot_params.m This script defines the location of the standard slices, transects, and mooring locations. It is configured for 6 transects, 3 horizontal slices, and
fcast.html This code resides in the /MATLAB directory and gets copied to the CRUISE_Q4.?/html directory. It loads the files generated by defplots.m. It is hard-wired to look for specific file names corresponding to the default plots, and requires that there be 6 default transect locations, 3 horizontal slice levels, etc. If a specific file is not available in the CRUISE_Q4.?/html directory, the page will contain the "NO PLOT" image.
run.defplots This is a cshell script that copies the above files into the CRUISE_Q4.> directory and submits the defplots.m script to matlab.

RUNNING THE DEFAULT PLOTS SCRIPTS

This describes the scripts added to the run.forecast sequence for default post-processing of the hind/forecast data. The default plots are generated using the c-shell script "run.defplots", which can either be run from the unix commandline after the forecast has been completed or from within the normal run.forecast script. To include in the run.forecast script, run.defplots should be added as follows:

   mv OBS/*Q4* CRUISE_Q4.3/
   mv OBS/DRIFTERS.pth CRUISE_Q4.3/
   mv OBS/DRIFTERS.diag CRUISE_Q4.3/
   mv DAY*.icq4 CRUISE_Q4.3/
   mv ITER_* CRUISE_Q4.3/

   run.defplots CRUISE_Q4.3

Note that run.defplots takes as an argument the forward run results directory. Change "4.3" to "4.2" or "4.1" to make the default plots on previous forward iterations. To execute run.defplots from the unix commandline after a forecast has completed, type:


  <%> run.defplots CRUISE_Q4.3

where <%> is the unix prompt.

HERE ARE THE DEFAULT PLOT SCRIPTS

As seen in the included code fragment above, we will need the following additional files:

defplots.m
defplot_params.m
fcast.html
run.defplots (this script must be executable. chmod u+x run.defplots)

Retrieve these files, save them as the filenames above indicate, and place them in the directory MATLAB in the forecast directory structure.

Also retrieve the files read_o1d.m and stick3.m and place them in the FCAST_1.2 toolbox directory. This version of read_o1d.m is specific to files called "QFLUX.o1d" and "TAUXY.o1d" that reside in the OBS directory. It should not be used on .o1d files whose prefix is not QFLUX or TAUXY.

Additional Things (REQUIRED)

The function READ_ICQ4 in $OPNML/IO_Functions must be renamed to any other name. The FCAST toolbox contains a version with a bug fix, and new features required by the FCAST plotting routines.
A newer version of read_pth.m (located in OPNML_MATLAB/FCAST_1.2) can optionally return a structure, so that a call like
```
   >> [gridname,ndrog,ndts,tsec,pth]=read_pth(fname,ncol,fmtstr);
```
can now be called as
```
   >> P=read_pth(fname,ncol,fmtstr);
```
P is now a structure with the following fields:
```
   P.gridname
   P.ndrog
   P.ndts
   P.tsec
   P.pth
```
The only issue is that the read_pth.m functions that already resides must be renamed to anything other than read_pth.m Functionally, the FCAST_1.2/read_pth.m can replace IO_Functions/read_pth.m entirely.

Latest Standard Forecast Output Products Example

This example was constructed with the above codes and information, with both the shiptrack and buoy plotting flags set to "0", i.e., the machine I am testing this on is too slow to process the entire shiptrack file. Click Here.