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

getfilevardims

Returns all dimension names associated with a variable on the given file.

Prototype

	function getfilevardims (
		thefile [1] : file,    
		varname [1] : string   
	)

	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.

varname

The name of the variable in single string format.

Return value

A one-dimensional array of strings.

Description

This function returns an array of dimension names for a variable on the given file. It returns a missing value if no dimension names exist or the variable is not defined.

If the dimension sizes are also desired, then getfilevardimsizes returns the dimension sizes in the same order as the dimension names returned from this function.

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

In NCL version 6.5.0, in order to make the various getfilevarxxxx function names more meaningful and consistent, we added a getfilevardimnames function that is an alias for this function.

See Also

getfilevardimnames, getfilevaratts, getfilevardimsizes, getfilevartypes, getfilevarnames, addfile, addfiles

Examples

Example 1

Consider a netCDF file where "ncdump -h Tstorm.nc" yields:

netcdf Tstorm {
dimensions:
        timestep = 64 ;
        lat = 33 ;
        lon = 36 ;
        timelen = 20 ;
variables:
        float t(timestep, lat, lon) ;
                t:_FillValue = -9999.f ;
        int timestep(timestep) ;
        float lat(lat) ;
        float lon(lon) ;
        char reftime(timelen) ;
                reftime:units = "text_time" ;
                reftime:long_name = "reference time" ;
}
To retrieve the dimension names of the variable "t" on the file, you can use the following code snippet:

   f      = addfile ("$NCARG_ROOT/lib/ncarg/data/cdf/Tstorm.cdf" , "r")
   dNames = getfilevardims(f,"t")      ; NCL 6.4.0 and earlier
;  dNames = getfilevardimnames(f,"t")  ; NCL 6.5.0 and later
   print (dNames)
Output:

Variable: dNames
Type: string
Total Size: 12 bytes
            3 values
Number of Dimensions: 1
Dimensions and sizes:   [3]
Coordinates: 
(0)     timestep
(1)     lat
(2)     lon
Note: you can also accomplish the above with the following code snippet:

   f      = addfile ("$NCARG_ROOT/lib/ncarg/data/cdf/Tstorm.cdf" , "r")
   dNames = getvardims(f->t)  
   print (dNames)
This is more inefficient, however, because the reference "f->t" causes the variable "t" to be read off the file. In using "getfilevardims", only the dimension names are read off the file.

Example 2

To return the dimension names and sizes for a particular variable on a file:

   f      = addfile ("$NCARG_ROOT/lib/ncarg/data/cdf/Tstorm.cdf" , "r")
   dNames = getfilevardims(f,"t")        ; NCL 6.4.0 and earlier
;  dNames = getfilevardimnames(f,"t")    ; NCL 6.5.0 and later
   dSizes = getfilevardimsizes(f,"t")  
   print (dNames + " : " + dSizes)

Output:

(0)     timestep : 64
(1)     lat : 33
(2)     lon : 36

Example 3

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