6.10.1 Three-argument (curvilinear) version of SHADE, FILL, CONTOUR, and VECTOR
The SHADE, FILL, CONTOUR and VECTOR commands now have a 3-argument mode which allows them to create output in "curvilinear" coordinates; i.e. those on curvilinear grids or if a map projection has been defined.This allows for easy generation of output plots using sigma coordinates as well as the application of various map projections. A typical command line entry will look like:
yes? SHADE sst, x_page, y_page yes? VECTOR/OVER/PEN=1 uwnd, vwnd, x_page, y_page
where the last two arguments, x_page(i,j) and y_page(i,j), must be (at least) 2-dimensional grids which specify the X page (horizontal) position and Y page (vertical) position for each (i,j) index pair. The page positions may be in any units; Ferret will scale the plot according to the ranges of values in the position fields.
The location coordinates, here described as X and Y coordinates, do NOT need to represent the directions X and Y. They tell the graphics code the horizontal and vertical locations to use on the page. See for example the FAQ about using sigma-coordinates where the descriptions of graphical methods for plotting data with sigma coordinates use a 3-argument graphics command with the vertical coordinate being depth.
Notes:
1. The default axis labeling for the 3-argument commands will be the ranges of the position fields: inappropriate when map projections are being used. The /NOAXIS qualifier is provided for this purpose.
The /NOAXIS qualifier causes the axes and axis labels to be omitted from the plot. The qualifier has been added to support the curvilinear coordinate and map projection capabilities of the 3-argument versions of SHADE, FILL, CONTOUR and VECTOR in which linear axes are inappropriate.
2. In the 3-argument SHADE syntax you can specify either the coordinates of the points or the coordinates of the cell boundaries. In the command
yes? SHADE values, xcoords, ycoords
say that nVx is the size of the "x" dimension of the values argument, and nCx is the size of the "x" dimension of the coordinate arguments.
If nCx = nVx then the xcoords argument is presumed to give the locations of the points in the values argument and (as you say), the boundaries between points are computed to be the midpoints.
However, if nCx = nVx + 1 then the xcoords and ycoords arguments are presumed to give the locations of the boundaries. For an example see the FAQ on cell edges when using the 3-argument SHADE command. In all cases the size of the xcoords argument must match the size of the ycoords argument.
3. Beginning with Ferret v5.81 the argument /MODULO for SHADE, CONTOUR, or FILL plots will draw modulo replications in longitude for curvilinear data in order to fill out the specified extent in the longitude direction. For instance, if the xcoords variable contains longitudes in the range -270:90 we can draw a plot with longitudes 0:360 with the command
yes? SHADE/HLIMITS=0:360/MODULO values, xcoords, ycoords
4. There is an alternative to the 4-argument VECTOR command. The script mp_poly_vectors sets up to plot vectors in curvilinear coordinates using filled polygons. See the script poly_vec_demo.jnl for a demonstration of this capability.
6.10.2 Gridded data sets on curvilinear coordinates
If a given gridded variable is defined on a curvilinear coordinate system, then one need only provide the X and Y coordinate fields in the 3-argument SHADE or FILL command to accurately depict the field. For example, if a data set contained a variable TEMP, which was Nx x Ny in the longitude-latitude plane, and the data set also contained variables LON_POSITION and LAT_POSITION of the same size, then the command:
yes? SHADE TEMP, LON_POSITION, LAT_POSITION
would render the curvilinear plot.
6.10.3 Layered (sigma) coordinates
The capability to render curvilinear coordinates allows Ferret to display sigma coordinate fields without interpolating or regridding the variable to be displayed.
In this example the variable flow is defined on the gg grid where the Z axis is in layers. To display the field we need only create multidimensional fields specifying the relative positions of (i,j) pairs and use the new curvilinear coordinate commands (Figure 6_10):
yes? LET depth = h[k=@rsum]-h/2 yes? SET VARIABLE/TITLE="DEPTH function"/UNIT=meters depth yes? ! regrid 'Y' to the data grid yes? LET ygg = y[g=gg] yes? SET VARIABLE/TITLE="Y"/UNIT=kilometers ygg yes? SHADE flow[x=0,l=1], ygg, depth[x=0,i=1]
For a detailed example illustrating the use of curvilinear coordinates to analyze sigma-coordinate fields see the Ferret FAQ Entry, How to handle sigma coordinate output in Ferret.
6.10.4 Map Projections
Along with general capabilities for curvilinear coordinates, version 4.9 of Ferret and later provide a series of scripts for many common map projections.
Each map projection script will create the following variables:
|
|
|
| mp_central_meridian | central longitude calculated from the currently set region |
|
mp_standard_parallel |
central latitude calculated from the currently set region |
|
x_page |
two dimensional array mapping X world coordinates to page coordinates |
|
two dimensional array mapping Y world coordinates to page coordinate |
|
|
mp_mask |
mask to hide "back side" data in orthographic or other 3-D projections |
6.10.4.1 Using Map Projection scripts
To create output with a particular map projection you must do the following:
1. run the map projection script
2. associate the variable's grid with the projection: set grid var
3. adjust the window aspect ratio (if desired)
4. multiply the variable of interest by mp_mask (required for "3-D" projections)
5. give the three-argument plotting command
Example: (Figure 6_11)
yes? USE coads_climatology yes? SET REGION/L=1 yes? GO mp_hammer yes? GO mp_grid sst yes? GO mp_aspect yes? SHADE/NOAXIS sst*mp_mask, x_page, y_page
Note that if you are drawing the plot in a viewport, "mp_aspect" should not be used. It resets the window, obliterating the viewport setting. See the FAQ,
6.10.4.2 Overlays with Map Projections
Overlays can be drawn once a map projection script has been run. To add a filled land mask, sea level pressure and wind vectors onto our SST map we would issue the following commands (Figure 6_12):
... yes? GO mp_grid uwnd yes? GO mp_fland yes? VECTOR/OVER/PEN=1 uwnd*mp_mask, vwnd*mp_mask, x_page, y_page yes? GO mp_grid slp yes? CONTOUR/OVER/PEN=5 slp*mp_mask, x_page, y_page
If, instead, we wished to overlay sea level pressure for the South Atlantic only, we would need to take advantage of the mp_central_meridian and mp_standard_parallel variables. Normally, the map projection scripts calculate the central meridian and standard parallel from the currently set region and generate the x_page and y_page coordinate transformations accordingly. When we overlay a subregion, we need to rerun the map projection script and pass in values for mp_central_meridian and mp_standard_parallel so that they are match the previous values and are not calculated from the subregion associated with the overlay. (Figure 6_13)
yes? USE coads_climatology yes? SET REGION/L=1 yes? GO mp_hammer yes? GO mp_grid sst yes? GO mp_aspect yes? SHADE/NOAXIS sst*mp_mask, x_page, y_page yes? GO mp_fland yes? LIST mp_central_meridian, mp_standard_parallel LONGITUDE: 20E to 20E(380) LATITUDE: 90S to 90N Column 1: MP_CENTRAL_MERIDIAN is (MP_X[I=@MAX] + MP_X[I=@MIN])/2 Column 2: MP_STANDARD_PARALLEL is (MP_Y[J=@MAX] + MP_Y[J=@MIN])/2 MP_CENTRMP_STAND I / *: 200.0 0.0000 yes? GO mp_hammer 200 0 yes? SET REGION/X=60w:20e/Y=45s:0n yes? GO mp_grid slp yes? CONTOUR/OVER slp, x_page, y_page
Note: Had we used go mp_hammer 200 0 in the beginning we would not have had to rerun mp_hammer.
Showing the grid is often useful. Run the script mp_demo.jnl to see how to call the mp_graticule script. Other ideas are in the FAQ,
How can I show the grid on my map projection plots?
6.10.4.3 Map Projection scripts
Here is the list of utility scripts that support curvilinear coordinates:
|
|
|
| Ferret script | Function |
|
mp_demo.jnl |
demonstration of various map projections |
|
mp_fland.jnl |
curvilinear version of fland.jnl |
|
mp_graticule.jnl |
creates a graticule (lines of longitude and latitude) over the whole globe or any portion |
|
mp_grid.jnl |
Associates a data grid with a predefined map projection. |
|
mp_label.jnl |
correctly places labels using lat-lon coordinates |
|
mp_land.jnl |
curvilinear version of land.jnl |
|
mp_land_stripmap.jnl |
creates a land-centric interrupted map using the current projection |
|
mp_line.jnl |
correctly plots user lat-lon data on the map |
|
mp_ocean_stripmap.jnl |
creates an ocean-centric interrupted map using the current projection |
|
mp_polymark |
overlays "map projected" polygons |