NCL Home > Documentation > Functions > WRF, File I/O

wrf_user_getvar

Extracts data from ARW WRF model output, and does basic diagnostics calculations.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"      ; These two libraries are automatically
load "$NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl"    ; loaded from NCL V6.4.0 onward.
                                                              ; No need for user to explicitly load.

	function wrf_user_getvar (
		file_handle  : file or list,  
		variable     : string,        
		time         : integer        
	)

	return_val  :  numeric

Arguments

file_handle

Reference to an input netCDF file opened with addfile, or, as of V6.0.0, can be a list of NetCDF files opened with addfiles.

variable

Variable to retrieve. This can be either a variable in the ARW WRF output file(s), or a diagnostic - a limited number of diagnostics are available, see description below.

time

Time in file to retrieve. A value of -1 will retrieve all times in the file(s).

Return value

Data of requested field.

Description

This function extracts data from the ARW WRF file, and, if available, calculates the requested diagnostic.

For WRF variable names and their definitions, you can easily check them by using "ncl_filedump":

  ncl_filedump wrfout_d01_2000-01-24_12:00:00.nc

Available diagnostics (some diagnostics - marked in red below - are only available in version 6.6.0 or later):

avo absolute vorticity [10-5 s-1]
eth Equivalent Potential Temperature [K]
cape_2d Returns 2D fields mcape/mcin/lcl/lfc
Bug fixed in NCL V6.4.0: the surface pressure values were not being converted to hPa properly as required by the internal cape routines.

cape_3d Returns 3D fields cape and cin

cfrac Cloud fraction
This diagnostic is a special one that allows variable to either just be "cfrac", in which a series of default values are assumed, or it can be an array of six ordered string values that represent the following:

variable(0) - diagnostic name - "cfrac" (no other values possible)

variable(1) - vertical type - "height_agl", "height_msl", "pressure", "pres"
Default: "height_agl"

variable(2) - low threshold - the low cloud threshold value
Default: "300." for height_agl

variable(3) - mid threshold - The middle cloud threshold value
Default: "2000." for height_agl

variable(4) - high threshold - the high cloud threshold value
Default: "6000." for height_agl

variable(5) - missing value - the missing/fill value to use for non-cloud areas
Default: "9.9692099683868690E36"

ctt Cloud Top Temperature [degC]
Bug fixed in NCL V6.4.0: the pressure values were not being converted properly. Also, the values are now returned in degC and not in degK as previously advertised.

variable(0) - diagnostic name - "ctt" (no other values possible)

variable(1) - fill no cloud - set to True to fill the cloud free regions with fill values rather than using surface temperature
Default: "False"

variable(2) - missing value - the fill value to use for the non-cloud areas
Default: "9.9692099683868690E36"

variable(3) - optical threshold - The optical threshold used to determine when a cloud top is detected
Default: "1.0"

dbz Reflectivity [dBZ]
mdbz Maximum reflectivity [dBZ]
geopt/geopotential Full model geopotential [m2 s-2]
helicity Storm Relative Helicity [m-2/s-2]
Note: this is over the 0-3000 m AGL layer.
lat latitude
lon longitude
omg Omega [C]
Bug fixed in NCL V6.4.0: the calculation was incorrectly using the temperature values for the water vapor mixing ratio, making the output results nonsensical.
p/pres Full model pressure [Pa]
pressure Full model pressure [hPa]
pvo potential vorticity [PVU]
pw Precipitable Water
Bug fixed in NCL V6.4.0: the returned array will now have named dimensions.
rh2 2m Relative Humidity [%]
rh Relative Humidity [%]
slp Sea level pressure [hPa]
ter Model terrain height [m]
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 (return strings - recommended)
Times Times in file (return characters)
tv Virtual temperature [K]
twb Wet bulb temperature [K]
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
wspd_wdir grid relative wind speed and direction
wspd_wdir10 10m grid relative wind speed and direction
uvmet_wspd_wdir earth relative wind speed and direction
uvmet10_wspd_wdir 10m earth relative wind speed and direction
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]

wrf_user_getvar is modifiable by the user, if you want to add your own diagnostics. To add your own diagnostics:

Copy the file "$NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl" to your own directory.

Edit this file with any UNIX editor and look for the lines:

undef("wrf_user_getvar")
function wrf_user_getvar( file_handle, varin[*]:string, time:integer )

Before the final lines in this function:

  return(var)

end

Add these lines, replacing newvar as appropriate:

  if( variable .eq. "newvar" ) then
    . . . fill in code here . . .
  end if

To use the new version of this function, you can do one of two things:
1. Copy your modified script over "$NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl" and use the new "wrf_user_getvar" with your new entry:
```
xxx = wrf_usr_getvar(f,"XXX",0)
```
2. Remove all but the modified "wrf_user_getvar" function from your copy, rename the function ("wrf_user_getvar2"), and rename the file ("my_new_script.ncl"). You will need to load your new script to use the new function:
```
load "my_new_script.ncl"
xxx = wrf_usr_getvar2(f,"XXX",0)
```

wrf_user_getvar is part of a library of functions and procedures in WRFUserARW.ncl written to help users plot ARW WRF model data.

Examples

Example 1

Get variables from a single WRF ARW file:

  a = addfile("wrfout_d01_2000-01-24_12:00:00.nc","r")

  time = 1
  slp = wrf_user_getvar(a,"slp",time)  ; slp
  tc2 = wrf_user_getvar(a,"T2",time)   ; T2 in Kelvin
  u10 = wrf_user_getvar(a,"U10",time)  ; u at 10 m
  v10 = wrf_user_getvar(a,"V10",time)  ; v at 10 m

  ua  = wrf_user_getvar(a,"ua",time)   ; u on mass points
  va  = wrf_user_getvar(a,"va",time)   ; v on mass points

  avo = wrf_user_getvar(a,"avo",-1)    ; calculate avo for all times in file

Example 2

As of NCL V6.0.0, you can get a variable from a list of WRF ARW NetCDF files:

  files = systemfunc("ls -1 wrfout_d01_2000*") + ".nc"
  a = addfiles(files,"r")

  slp = wrf_user_getvar(a,"slp",-1)