Graphics: NCL - Functions (WRFUserARW.ncl)


function wrf_user_getvar (nc_file, _fld, it)
function wrf_user_list_times (nc_file)
function wrf_contour (nc_file, wks, data, res)
function wrf_vector (nc_file, wks, data_u, data_v, res)
function wrf_map_overlays (nc_file, wks, (/graphics/), pltres, mpres)
function wrf_overlays (nc_file, wks, (/graphics/), pltres)
function wrf_map (nc_file, wks, res)
function wrf_user_intrp3d (var3d, H, plot_type, loc_param, angle, res)
function wrf_user_intrp2d (var2d, loc_param, angle, res)
function wrf_user_ll_to_ij (nc_file, lons, lats, res)
function wrf_user_ij_to_ll (nc_file, i, j, res)
function wrf_user_unstagger (varin, unstagDim)
wrf_wps_dom (wks, mpres, lnres, txres)

Old Functions
wrf_overlay - use wrf_overlays instead
wrf_map_overlay - use wrf_map_overlays instead
wrf_map_zoom - incorporated in wrf_map
wrf_user_latlon_to_ij - use wrf_user_ll_to_ij instead
 

function wrf_user_getvar (nc_file, fld, it)
Usage: ter = wrf_user_getvar (a, “HGT”, 0)

Get fields from a netCDF file for
1. Any given time by setting it to the time required.
2. For all times in the input file(s), by setting it = -1
3. A list of times from the input file(s), by setting it to (/start_time,end_time,interval/) ( e.g. (/0,10,2/) ).
4. A list of times from the input file(s), by setting it to the list required ( e.g. (/1,3,7,10/) ).

Any field available in the netCDF file can be extracted.
fld is case sensitive. The policy adapted during development was to set all diagnostic variables calculated by NCL to lower-case to distinguish them from fields directly available from the netCDF files.

List of available diagnostics:

avo: Absolute Vorticity [10-5 s-1]
eth: Equivalent PotentialTtemperature [K]
cape_2d: Returns 2D fields mcape/mcin/lcl/lfc
cape_3d: Returns 3D fields cape/cin
dbz: Reflectivity [dBZ]
mdbz: Maximum Reflectivity [dBZ]
geopt/geopotential: Full Model Geopotential [m2 s-2]
helicity: Storm Relative Helicity [m-2/s-2]
lat: Latitude (will return either XLAT or XLAT_M, depending on which is available)
lon: Longitude (will return either XLONG or XLONG_M, depending on which is available)
p/pres: Full Model Pressure [Pa]
pressure: Full Model Pressure [hPa]
pvo: Potential Vorticity [PVU]
pw: Precipitable Water
rh2: 2m Relative Humidity [%]
rh: Relative Humidity [%]
slp: Sea Level Pressure [hPa]
ter: Model Terrain Height [m] (will return either HGT or HGT_M, depending on which is available)
td2: 2m Dew Point Temperature [C]
td: Dew Point Temperature [C]
tc: Temperature [C]
th/theta: Potential Temperature [K]
tk: Temperature [K]
times: Times in file (note this return strings - recommended)
Times: Times in file (note this return characters)
updraft_helicity: Updraft Helicity [m-2/s-2]
ua: U component of wind on mass points
va: V component of wind on mass points
wa: W component of wind on mass points
uvmet10: 10m U and V components of wind rotated to earth coordinates
uvmet: U and V components of wind rotated to earth coordinates
z/height: Full Model Height [m]

--- top ---

function wrf_user_list_times (nc_file)
Usage: times = wrf_user_list_times (a)

Obtains a list of times available in the input file. The function returns a 1D array containing the times (type: character) in the input file.
[this function is old, although still available - has been replaced by wrf_user_getvar(a,"times",it)]

--- top ---

function wrf_contour (nc_file, wks, data, res)
Usage: contour = wrf_contour (a, wks, ter, opts)

Returns a graphic (contour), of the data to be contoured. This graphic is only created, but not plotted to a wks. This enables a user to generate many such graphics and overlay them before plotting the resulting picture to a wks.

The returned graphic (contour) does not contain map information, and can therefore be used for both real and idealized data cases.

This function can plot both line contours and shaded contours. Default is line contours.

Many resources are set for a user, of which most can be overwritten. Below is a list of resources you may want to consider changing before generating your own graphics:

Resources unique to ARW WRF Model data
opts@MainTitle : Controls main title on the plot.
opts@MainTitlePos : Main title position – Left/Right/Center. Default is Left.
opts@NoHeaderFooter : Switch off all Headers and Footers.
opts@Footer : Add some model information to the plot as a footer. Default is True.
opts@InitTime : Plot initial time on graphic. Default is True. If True, the initial time will be extracted from the input file.
opts@ValidTime : Plot valid time on graphic. Default is True. A user must set opts@TimeLabel to the correct time.
opts@TimeLabel : Time to plot as valid time.
opts@TimePos : Time position – Left/Right. Default is “Right”.
opts@ContourParameters : A single value is treated as an interval. Three values represent: Start, End, and Interval.
opts@FieldTitle : Overwrite the field title - if not set the field description is used for the title.
opts@UnitLabel : Overwrite the field units - seldom needed as the units associated with the field will be used.
opts@PlotLevelID : Use to add level information to the field title.

General NCL resources (most standard NCL options for cn and lb can be set by the user to overwrite the default values)
opts@cnFillOn : Set to True for shaded plots. Default is False.
opts@cnLineColor : Color of line plot.
opts@lbTitleOn : Set to False to switch the title on the label bar off. Default is True.
opts@cnLevelSelectionMode ; opts @cnLevels ; opts@cnFillColors ; optr@cnConstFLabelOn : Can be used to set contour levels and colors manually.

--- top ---

function wrf_vector (nc_file, wks, data_u, data_v, res)
Usage: vector = wrf_vector (a, wks, ua, va, opts)

Returns a graphic (vector) of the data. This graphic is only created, but not plotted to a wks. This enables a user to generate many such graphics and overlay them before plotting the resulting picture to a wks.

The returned graphic (vector) does not contain map information, and can therefore be used for both real and idealized data cases.

Many resources are set for a user, of which most can be overwritten. Below is a list of resources you may want to consider changing before generating your own graphics:

Resources unique to ARW WRF Model data
opts@MainTitle : Controls main title on the plot.
opts@MainTitlePos : Main title position – Left/Right/Center. Default is Left.
opts@NoHeaderFooter : Switch off all Headers and Footers.
opts@Footer : Add some model information to the plot as a footer. Default is True.
opts@InitTime : Plot initial time on graphic. Default is True. If True, the initial time will be extracted from the input file.
opts@ValidTime : Plot valid time on graphic. Default is True. A user must set opts@TimeLabel to the correct time.
opts@TimeLabel : Time to plot as valid time.
opts@TimePos : Time position – Left/Right. Default is “Right”.
opts@ContourParameters : A single value is treated as an interval. Three values represent: Start, End, and Interval.
opts@FieldTitle : Overwrite the field title - if not set the field description is used for the title.
opts@UnitLabel : Overwrite the field units - seldom needed as the units associated with the field will be used.
opts@PlotLevelID : Use to add level information to the field title.
opts@NumVectors : Density of wind vectors.

General NCL resources (most standard NCL options for vc can be set by the user to overwrite the default values)
opts@vcGlyphStyle : Wind style. “WindBarb” is default.

--- top ---

function wrf_map_overlays (nc_file, wks, (/graphics/), pltres, mpres)
Usage: plot = wrf_map_overlays (a, wks, (/contour,vector/), pltres, mpres)

Overlay contour and vector plots generated with wrf_contour and wrf_vector. Can overlay any number of graphics. Overlays will be done in order give, so always list shaded plots before line or vector plots, to ensure the lines and vectors are visible and not hidden behind the shaded plot.

A map background will automatically be added to the plot. Map details are controlled with the mpres resource. Common map resources you may want to set are:
mpres@mpGeophysicalLineColor ; mpres@mpNationalLineColor ; mpres@mpUSStateLineColor ; mpres@mpGridLineColor ; mpres@mpLimbLineColor ; mpres@mpPerimLineColor

If you want to zoom into the plot, set mpres@ZoomIn to True, and mpres@Xstart, mpres@Xend, mpres@Ystart, mpres@Yend, to the corner x/y positions of the zoomed plot.

pltres@NoTitles : Set to True to remove all field titles on a plot.
pltres@CommonTitle : Overwrite field titles with a common title for the overlaid plots. Must set pltres@PlotTitle to desired new plot title.

If you want to generate images for a panel plot, set pltres@PanelPot to True.

If you want to add text/lines to the plot before advancing the frame, set pltres@FramePlot to False. Add your text/lines directly after the call to the wrf_map_overlays function. Once you are done adding text/lines, advance the frame with the command “frame(wks)”.

--- top ---

function wrf_overlays (nc_file, wks, (/graphics/), pltres)
Usage: plot = wrf_overlays (a, wks, (/contour,vector/), pltres)

Overlay contour and vector plots generated with wrf_contour and wrf_vector. Can overlay any number of graphics. Overlays will be done in order give, so always list shaded plots before line or vector plots, to ensure the lines and vectors are visible and not hidden behind the shaded plot.

Typically used for idealized data or cross-sections, which does not have map background information.

pltres@NoTitles : Set to True to remove all field titles on a plot.
pltres@CommonTitle : Overwrite field titles with a common title for the overlaid plots. Must set pltres@PlotTitle to desired new plot title.

If you want to generate images for a panel plot, set pltres@PanelPot to True.

If you want to add text/lines to the plot before advancing the frame, set pltres@FramePlot to False. Add your text/lines directly after the call to the wrf_overlays function. Once you are done adding text/lines, advance the frame with the command “frame(wks)”.

--- top ---

function wrf_map (nc_file, wks, res)
Usage: map = wrf_map(a, wks, opts)
           
Create a map background.
As maps are added to plots automatically via the wrf_map_overlays function, this function is seldom needed as a stand-alone.

--- top ---

function wrf_user_intrp3d (var3d, H, plot_type, loc_param, angle, res)

This function is used for both horizontal and vertical interpolation.

var3d: The variable to interpolate. This can be a array of up to 5 dimensions. The 3 right-most dimensions must be bottom_top x south_north x west_east.
H: The field to interpolate to. Either pressure (hPa or Pa), or z (m). Dimensionality must match var3d.
plot_type: “h” for horizontally and “v” for vertically interpolated plots.
loc_param: Can be a scalar, or an array holding either 2 or 4 values.
For plot_type = “h:
     This is a scalar representing the level to interpolate too.
     Must match the field to interpolate too (H).
     When interpolating to pressure, this can be in hPa or Pa (e.g. 500., to interpolate to 500 hPa).
     When interpolating to height this must in in m (e.g. 2000., to interpolate to 2 km).
For plot_type = “v”:
     This can be a pivot point though which a line is drawn – in this case a single x/y point (2 values) is required.
     Or this can be a set of x/y points (4 values), indicating start x/y and end x/y locations for the cross-section.
angle:
     Set to 0., for plot_type = “h”, or for plot_type = “v” when start and end locations of cross-section were supplied in loc_param.
     If a single pivot point was supplied in loc_param, angle is the angle of the line that will pass through the pivot point. Where: 0. is SN, and 90. is WE.
res:
     Set to False for plot_type = “h”, or for plot_type = “v” when a single pivot point is supplied.
     Set to True if start and end locations are supplied.

--- top ---

function wrf_user_intrp2d (var2d, loc_param, angle, res)

This function interpolates a 2D field along a given line.

var2d: Is the 2D field to interpolate. This can be a array of up to 3 dimensions. The 2 right-most dimensions must be south_north x west_east.
loc_param:
     Is an array holding either 2 or 4 values.
     This can be a pivot point though which a line is drawn – in this case a single x/y point (2 values) is required.
     Or this can be a set of x/y points (4 values), indicating start x/y and end x/y locations for the cross-section.
angle:
     Set to 0 when start and end locations of the line were supplied in loc_param.
     If a single pivot point was supplied in loc_param, angle is the angle of the line that will pass through the pivot point. Where: 0. is SN, and 90. is WE.
res:
     Set to False when a single pivot point is supplied.
     Set to True if start and end locations is supplied.

--- top ---

function wrf_user_ll_to_ij (nc_file, lons, lats, res)
Usage: loc = wrf_user_latlon_to_ij (a, 100., 40., res)
Usage: loc = wrf_user_latlon_to_ij (a, (/100., 120./), (/40., 50./), res)

Convert a lon/lat location to the nearest x/y location. This function makes use of map information to find the closest point, so this returned value may potentially be outside the model domain.

lons/lats can be scalars or arrays.

Optional resources:
res@returnInt - If set to False, the return values will be real (default is True with integer return values)
res@useTime - Default is 0. Set if want the reference longitude/latitudes must come from a specific time - one will only use this for moving nest output which has been stored in a single file.

loc(0,:) is the x (WE) locations, and loc(1,:) the y (SN) locations.

--- top ---

function wrf_user_ij_to_ll (nc_file, i, j, res)
Usage: loc = wrf_user_latlon_to_ij (a, 10, 40, res)
Usage: loc = wrf_user_latlon_to_ij (a, (/10, 12/), (/40, 50/), res)

Convert a i/j location to a lon/lat location. This function makes use of map information to find the closest point, so this returned value may potentially be outside the model domain.

i/j can be scalars or arrays.

Optional resources:
res@useTime - Default is 0. Set if want the reference longitude/latitudes must come from a specific time - one will only use this for moving nest output which has been stored in a single file.

loc(0,:) is the lons locations, and loc(1,:) the lats locations.

--- top ---

function wrf_user_unstagger (varin, unstagDim)

This function unstaggers an array. This function returns an array on ARW WRF mass points.

varin: Array to be unstaggered.
unstagDim: Dimension to unstagger. Must be either "X", "Y", or "Z". This is case sensitive. If not one of these strings, the returning array will be unchanged.

--- top ---

function wrf_wps_dom (wks, mpres, lnres, txres)

A function has been built into NCL to preview where a potential domain will be placed (similar to plotgrids.exe from WPS).

This functionality is available in NCL version 5.0.1, but is currently still experimental.

The lnres and txres resources are standard NCL Line and Text resources. These are used to add nests to the preview.

The mpres are used for standard map background resources like:
mpres@mpFillOn ; mpres@mpFillColors ; mpres@mpGeophysicalLineColor ; mpres@mpNationalLineColor ; mpres@mpUSStateLineColor ; mpres@mpGridLineColor ; mpres@mpLimbLineColor ; mpres@mpPerimLineColor

But its main function is to set map resources to preview a domain. These resources are similar to the resources set in WPS. Below is an example to display 3 nested domains on a Lambert projection. (The output is shown below).

mpres@max_dom           = 3
mpres@parent_id         = (/ 1,    1,   2 /)
mpres@parent_grid_ratio = (/ 1,    3,   3 /)
mpres@i_parent_start    = (/ 1,   31,  15 /)
mpres@j_parent_start    = (/ 1,   17,  20 /)
mpres@e_we              = (/ 74, 112, 133/)
mpres@e_sn              = (/ 61,  97, 133 /)
mpres@dx                = 30000.
mpres@dy                = 30000.
mpres@map_proj          = "lambert"
mpres@ref_lat           = 34.83
mpres@ref_lon           = -81.03
mpres@truelat1          = 30.0
mpres@truelat2          = 60.0
mpres@stand_lon         = -98.0

--- top ---






Fortran in NCL