NCL Website header
NCL Home > Documentation > Functions > File I/O

getfilevarnames

Returns an array of file variable names on the given file.

Prototype

	function getfilevarnames (
		thefile [1] : file   
	)

	return_val [*] :  string

Arguments

thefile

A reference to a file created from a call to addfile or addfiles. The file referenced must be one in the supported file format list.

Description

This function returns an array of strings containing the name of each variable in the given file. The length of this array is equal to the number of variables in the file.

If the file is a NetCDF4 file containing groups, then this function returns the variable names with group name(s) inserted at the beginning. If it is at the root group, then a "/" is inserted. See example below for more details.

This function is useful when accessing file variables by string name. (See Files.)

Note: since addfiles returns a variable of type "list", you must subscript the list before calling this function.

See Also

getfilevardimsizes, getfilevardimnames, getfilevaratts, getfilevartypes, getfiledimsizes, getfiledimnames, getfileatts, addfile, addfiles

Examples

Example 1

The following example gets all the variables names from a netCDF file. It will work for any file referenced by addfile. The dollar sign syntax used in this example is described at "NCL Variables".

    f = addfile ("X.nc" , "r")   ; could also have ccm, grb or hdf suffix
    vNames = getfilevarnames (f) ; get names of all variables on file
      
    nNames = dimsizes (vNames)   ; number of variables on the file
      
    print (vNames)               ; print all variable names on file
      
    do n=0,nNames-1              ; loop thru each variable
       v = f->$vNames(n)$        ; read the varible to memory
         
       dimv = dimsizes(v)        ; dimension size of the variable
       rank = dimsizes(dimv)     ; rank [ie: number of dimensions]
         
       [SNIP]
         
       delete ([v,rank/])
   end do

Example 2

Consider a list of WRF output files starting with the prefix "wrfout_d01_2008-09". To retrieve the variable names across the files, you must subscript the list variable returned by addfiles:

  wrf_files = systemfunc("ls wrfout_d01_2008-09*")
  f = addfiles(wrf_files+".nc","r")
  print(str_join(getfilevarnames(f[0]),", "))

Output (new lines were added to the output to make it more readable):

(0)     Times, LU_INDEX, ZNU, ZNW, ZS, DZS, U, Z_FORCE, U_G, U_G_TEND, 
V, V_G, V_G_TEND, W, W_SUBS, W_SUBS_TEND, PH, PHB, T, TH_UPSTREAM_X,
TH_UPSTREAM_X_TEND, TH_UPSTREAM_Y, TH_UPSTREAM_Y_TEND, QV_UPSTREAM_X,
QV_UPSTREAM_X_TEND, QV_UPSTREAM_Y, QV_UPSTREAM_Y_TEND, U_UPSTREAM_X,
U_UPSTREAM_X_TEND, U_UPSTREAM_Y, U_UPSTREAM_Y_TEND, V_UPSTREAM_X,
V_UPSTREAM_X_TEND, V_UPSTREAM_Y, V_UPSTREAM_Y_TEND, MU, MUB, NEST_POS,
P, PB, SR, POTEVP, SNOPCX, SOILTB, FNM, FNP, RDNW, RDN, DNW, DN, CFN,
CFN1, Q2, T2, TH2, PSFC, U10, V10, RDX, RDY, RESM, ZETATOP, CF1, CF2,
CF3, ITIMESTEP, XTIME, QVAPOR, QCLOUD, QRAIN, QICE, QSNOW, QGRAUP,
LANDMASK, TSLB, SMOIS, SH2O, SEAICE, XICEM, SFROFF, UDROFF, IVGTYP,
ISLTYP, VEGFRA, GRDFLX, ACGRDFLX, SNOW, SNOWH, RHOSN, CANWAT, SST,
SSTSK, LAI, Z0, VAR, CON, OA1, OA2, OA3, OA4, OL1, OL2, OL3, OL4,
H_DIABATIC, MAPFAC_M, MAPFAC_U, MAPFAC_V, MAPFAC_MX, MAPFAC_MY,
MAPFAC_UX, MAPFAC_UY, MAPFAC_VX, MF_VX_INV, MAPFAC_VY, F, E, SINALPHA,
COSALPHA, HGT, HGT_SHAD, TSK, P_TOP, T00, P00, TLP, TISO, MAX_MSTFX,
MAX_MSTFY, RAINC, RAINNC, I_RAINC, I_RAINNC, SNOWNC, GRAUPELNC,
EDT_OUT, SWDOWN, GLW, OLR, XLAT, XLONG, XLAT_U, XLONG_U, XLAT_V,
XLONG_V, ALBEDO, ALBBCK, EMISS, NOAHRES, TMN, XLAND, UST, PBLH, HFX,
QFX, LH, ACHFX, ACLHF, SNOWC, SAVE_TOPO_FROM_REAL
Example 3

When opening a NetCDF4 file, the variable names have group names inserted at the beginning. If it is a root (group), then a "/" is inserted (to represent the root group).

 fn = "nc4_out_nc4uvt.nc"
 fi = addfile(fn, "r")

 vNames = getfilevarnames(fi) ; get variable names of all groups on file
      
 print (vNames)               ; print all variable names on file

The above script produces:

Variable: vNames
Type: string
Total Size: 112 bytes
            14 values
Number of Dimensions: 1
Dimensions and sizes:   [14]
Coordinates: 
(0)     /time
(1)     /lev
(2)     /lat
(3)     /lon
(4)     /T
(5)     /U
(6)     /V
(7)     /grp1/time
(8)     /grp1/lev
(9)     /grp1/lat
(10)    /grp1/lon
(11)    /grp1/T
(12)    /grp1/U
(13)    /grp1/V

Here, one can see that there are T, U, V, and other variables under the "/" (root) group and the group "grp1".

Example 4

For each variable on a file, print its type, attributes, dimension names, and dimension sizes. It's possible for a variable to not contain dimension names and/or attributes, so the any and ismissing functions are used to check for this:

  f = addfile("$NCARG_ROOT/lib/ncarg/data/cdf/Ustorm.cdf","r")

  vnames = getfilevarnames(f)           ; all variable names
  nvars  = dimsizes(vnames)

  do nv = 0,nvars-1
    vtype  = getfilevartypes(f,vnames(nv))
    vatts  := getfilevaratts(f,vnames(nv))       ; The := is important because these
    dnames := getfilevardimnames(f,vnames(nv))   ; variables may be a different size
    dsizes := getfilevardimsizes(f,vnames(nv))   ; the next time through the loop

;   print("==================================================")
    print("Variable '" + vnames(nv) + "'")
    print("  type            : " + vtype)
    if(.not.any(ismissing(dnames))) then
      print("  dimension names : " + str_join(dnames,","))
    else
      print("  dimension names : ")
    end if
    print("  dimension sizes : " + str_join(""+dsizes,","))
    if(.not.any(ismissing(vatts))) then
      print("  attributes      : " + str_join(vatts,","))
    else
      print("  attributes      : ")
    end if
 end do

Output:

Variable 'u'
  type            : float
  dimension names : timestep,lat,lon
  dimension sizes : 64,33,36
  attributes      : _FillValue
Variable 'timestep'
  type            : integer
  dimension names : timestep
  dimension sizes : 64
  attributes      : 
Variable 'lat'
  type            : float
  dimension names : lat
  dimension sizes : 33
  attributes      : 
Variable 'lon'
  type            : float
  dimension names : lon
  dimension sizes : 36
  attributes      : 
Variable 'reftime'
  type            : character
  dimension names : timelen
  dimension sizes : 20
  attributes      : units,long_name