Next: , Previous: Language-Types, Up: Variables


6.3 Create a Variable: NF90_DEF_VAR

The function NF90_DEF_VAR adds a new variable to an open netCDF dataset in define mode. It returns (as an argument) a variable ID, given the netCDF ID, the variable name, the variable type, the number of dimensions, and a list of the dimension IDs.

Optional arguments allow additional settings for variables in netCDF-4/HDF5 files. These parameters allow data compression and control of the layout of the data on disk for performance tuning. These parameters may also be used to set the chunk sizes to get chunked storage, or to set the contiguous flag to get contiguous storage.

Variables that make use of one or more unlimited dimensions, compression, or checksums must use chunking. Such variables are created with default chunk sizes of 1 for each unlimited dimension and the dimension length for other dimensions, except that if the resulting chunks are too large, the default chunk sizes for non-record dimensions are reduced.

All parameters after the varid are optional, and only supported if netCDF was built with netCDF-4 features enabled, and if the variable is in a netCDF-4/HDF5 file.

Usage

      function nf90_def_var(ncid, name, xtype, dimids, varid, contiguous, &
            chunksizes, deflate_level, shuffle, fletcher32, endianness, &
            cache_size, cache_nelems, cache_preemption)
        integer, intent(in) :: ncid
        character (len = *), intent(in) :: name
        integer, intent( in) :: xtype
        integer, dimension(:), intent(in) :: dimids
        integer, intent(out) :: varid
        logical, optional, intent(in) :: contiguous
        integer, optional, dimension(:), intent(in) :: chunksizes
        integer, optional, intent(in) :: deflate_level
        logical, optional, intent(in) :: shuffle, fletcher32
        integer, optional, intent(in) :: endianness
         integer, optional, intent(in) :: cache_size, cache_nelems, cache_preemption
        integer                                      :: nf90_def_var
ncid
NetCDF ID, from a previous call to NF90_OPEN or NF90_CREATE.
name
Variable name.
xtype
One of the set of predefined netCDF external data types. The type of this parameter, NF90_TYPE, is defined in the netCDF header file. The valid netCDF external data types are NF90_BYTE, NF90_CHAR, NF90_SHORT, NF90_INT, NF90_FLOAT, and NF90_DOUBLE. If the file is a NetCDF-4/HDF5 file, the additional types NF90_UBYTE, NF90_USHORT, NF90_UINT, NF90_INT64, NF90_UINT64, and NF90_STRING may be used, as well as a user defined type ID.
dimids
Vector of dimension IDs corresponding to the variable dimensions. For example, a vector of 2 dimension IDs specifies a 2-dimensional matrix.

If an integer is passed for this parameter, a 1-D variable is created.

If this parameter is not passed (or is a 1D array of size zero) it means the variable is a scalar with no dimensions.

For classic data model files, if the ID of the unlimited dimension is included, it must be first. In expanded model netCDF4/HDF5 files, there may be any number of unlimited dimensions, and they may be used in any element of the dimids array.

This argument is optional, and if absent specifies a scalar with no dimensions.

varid
Returned variable ID.
storage
If NF90_CONTIGUOUS, then contiguous storage is used for this variable. Variables that use deflation, shuffle filter, or checksums, or that have one or more unlimited dimensions cannot use contiguous storage.

If NF90_CHUNKED, then chunked storage is used for this variable. Chunk sizes may be specified with the chunksizes parameter. Default sizes will be used if chunking is required and this function is not called.

By default contiguous storage is used for fix-sized variables when conpression, chunking, shuffle, and checksums are not used.

chunksizes
An array of chunk number of elements. This array has the number of elements along each dimension of the data chunk. The array must have the one chunksize for each dimension in the variable.

The total size of a chunk must be less than 4 GiB. That is, the product of all chunksizes and the size of the data (or the size of nc_vlen_t for VLEN types) must be less than 4 GiB. (This is a very large chunk size in any case.)

If not provided, but chunked data are needed, then default chunksizes will be chosen. For more information see The NetCDF Users Guide.

shuffle
If non-zero, turn on the shuffle filter.
deflate_level
If the deflate parameter is non-zero, set the deflate level to this value. Must be between 1 and 9.
fletcher32
Set to true to turn on fletcher32 checksums for this variable.
endianness
Set to NF90_ENDIAN_LITTLE for little-endian format, NF90_ENDIAN_BIG for big-endian format, and NF90_ENDIAN_NATIVE (the default) for the native endianness of the platform.
cache_size
The size of the per-variable cache in MegaBytes.
cache_nelems
The number slots in the per-variable chunk cache (should be a prime number larger than the number of chunks in the cache).
cache_preemption
The preemtion value must be between 0 and 100 inclusive and indicates how much chunks that have been fully read are favored for preemption. A value of zero means fully read chunks are treated no differently than other chunks (the preemption is strictly LRU) while a value of 100 means fully read chunks are always preempted before other chunks.

Return Codes

NF90_DEF_VAR returns the value NF90_NOERR if no errors occurred. Otherwise, the returned status indicates an error.

Example

Here is an example using NF90_DEF_VAR to create a variable named rh of type double with three dimensions, time, lat, and lon in a new netCDF dataset named foo.nc:

      use netcdf
      implicit none
      integer :: status, ncid
      integer :: LonDimId, LatDimId, TimeDimId
      integer :: RhVarId
      ...
      status = nf90_create("foo.nc", nf90_NoClobber, ncid)
      if(status /= nf90_NoErr) call handle_error(status)
      ...
      ! Define the dimensions
      status = nf90_def_dim(ncid, "lat", 5, LatDimId)
      if(status /= nf90_NoErr) call handle_error(status)
      status = nf90_def_dim(ncid, "lon", 10, LonDimId)
      if(status /= nf90_NoErr) call handle_error(status)
      status = nf90_def_dim(ncid, "time", nf90_unlimited, TimeDimId)
      if(status /= nf90_NoErr) call handle_error(status)
      ...
      ! Define the variable
      status = nf90_def_var(ncid, "rh", nf90_double, &
                            (/ LonDimId, LatDimID, TimeDimID /), RhVarId)
      if(status /= nf90_NoErr) call handle_error(status)

In the following example, from nf_test/f90tst_vars2.f90, chunking, checksums, and endianness control are all used in a netCDF-4/HDF5 file.

       ! Create the netCDF file.
       call check(nf90_create(FILE_NAME, nf90_netcdf4, ncid, cache_nelems = CACHE_NELEMS, &
            cache_size = CACHE_SIZE))
     
       ! Define the dimensions.
       call check(nf90_def_dim(ncid, "x", NX, x_dimid))
       call check(nf90_def_dim(ncid, "y", NY, y_dimid))
       dimids =  (/ y_dimid, x_dimid /)
     
       ! Define some variables.
       chunksizes = (/ NY, NX /)
       call check(nf90_def_var(ncid, VAR1_NAME, NF90_INT, dimids, varid1, chunksizes = chunksizes, &
            shuffle = .TRUE., fletcher32 = .TRUE., endianness = nf90_endian_big, deflate_level = DEFLATE_LEVEL))
       call check(nf90_def_var(ncid, VAR2_NAME, NF90_INT, dimids, varid2, contiguous = .TRUE.))
       call check(nf90_def_var(ncid, VAR3_NAME, NF90_INT64, varid3))
       call check(nf90_def_var(ncid, VAR4_NAME, NF90_INT, x_dimid, varid4, contiguous = .TRUE.))