Next: , Previous: nc_get_vars_ type, Up: Variables


4.15 Read a Mapped Array of Values: nc_get_varm_ type

The nc_get_varm_ type family of functions reads a mapped array section of values from a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of edge lengths, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode.

Usage

     int nc_get_varm_text  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], char *tp);
     int nc_get_varm_uchar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], unsigned char *up);
     int nc_get_varm_schar (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], signed char *cp);
     int nc_get_varm_short (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], short *sp);
     int nc_get_varm_int   (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], int *ip);
     int nc_get_varm_long  (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], long *lp);
     int nc_get_varm_float (int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], float *fp);
     int nc_get_varm_double(int ncid, int varid, const size_t start[],
                            const size_t count[], const ptrdiff_t stride[],
                            const ptrdiff_t imap[], double *dp);
ncid
NetCDF ID, from a previous call to nc_open or nc_create.
varid
Variable ID.
start
A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index (0, 0, ... , 0). The elements of start correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values.
count
A vector of size_t integers specifying the number of indices selected along each dimension. To read a single value, for example, specify count as (1, 1, ... , 1). The elements of count correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of count corresponds to a count of the number of records to read.
stride
A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A NULL stride argument is treated as (1, 1, ... , 1).
imap
A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. imap[n-1] (where n is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. Intervening imap elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2).
tp
up
cp
sp
ip
lp
fp
dp
Pointer to the location used for computing where the data values are read; the data should be of the type appropriate for the function called. If the type of data value differs from the netCDF variable type, type conversion will occur. See Type Conversion.

Errors

nc_get_varm_ type returns the value NC_NOERR if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:

Example

The following imap vector maps in the trivial way a 4x3x2 netCDF variable and an internal array of the same shape:

     float a[4][3][2];       /* same shape as netCDF variable */
     size_t imap[3] = {6, 2, 1};
                             /* netCDF dimension       inter-element distance */
                             /* ----------------       ---------------------- */
                             /* most rapidly varying       1                  */
                             /* intermediate               2 (=imap[2]*2)     */
                             /* most slowly varying        6 (=imap[1]*3)     */

Using the imap vector above with nc_get_varm_float obtains the same result as simply using nc_get_var_float.

Here is an example of using nc_get_varm_float to transpose a netCDF variable named rh which is described by the C declaration float rh[6][4] (note the size and order of the dimensions):

     #include <netcdf.h>
        ...
     #define NDIM 2                /* rank of netCDF variable */
     int ncid;                     /* netCDF ID */
     int status;                   /* error status */
     int rhid;                     /* variable ID */
     static size_t start[NDIM]     /* netCDF variable start point: */
                      = {0, 0};    /* first element */
     static size_t count[NDIM]     /* size of internal array: entire netCDF */
                      = {6, 4};    /* variable; order corresponds to netCDF */
                                   /* variable -- not internal array */
     static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
                      = {1, 1};    /* sample every netCDF element */
     static ptrdiff_t imap[NDIM]   /* internal array inter-element distances; */
                      = {1, 6};    /* would be {4, 1} if not transposing */
     float rh[4][6];               /* note transposition of netCDF variable */
                                   /* dimensions */
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid(ncid, "rh", &rhid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
     if (status != NC_NOERR) handle_error(status);

Here is another example of using nc_get_varm_float to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:

     #include <netcdf.h>
        ...
     #define NDIM 2               /* rank of netCDF variable */
     int ncid;                    /* netCDF ID */
     int status;                  /* error status */
     int rhid;                    /* variable ID */
     static size_t start[NDIM]    /* netCDF variable start point: */
                      = {0, 0};   /* first element */
     static size_t count[NDIM]    /* size of internal array: entire */
                        = {3, 2}; /* (subsampled) netCDF variable; order of */
                                  /* dimensions corresponds to netCDF */
                                  /* variable -- not internal array */
     static ptrdiff_t stride[NDIM]/* variable subsampling intervals: */
                      = {2, 2};   /* sample every other netCDF element */
     static ptrdiff_t imap[NDIM]  /* internal array inter-element distances; */
                      = {1, 3};   /* would be {2, 1} if not transposing */
     float rh[2][3];              /* note transposition of (subsampled) */
                                  /* netCDF variable dimensions */
        ...
     status = nc_open("foo.nc", NC_WRITE, &ncid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_inq_varid(ncid, "rh", &rhid);
     if (status != NC_NOERR) handle_error(status);
        ...
     status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
     if (status != NC_NOERR) handle_error(status);