ncvar_get: Read data from a netCDF file
In ncdf4: Interface to Unidata netCDF (Version 4 or Earlier) Format Data Files
ncvar_get R Documentation
Read data from a netCDF file
Description
Reads data from an existing netCDF file.
Usage
ncvar_get(nc, varid=NA, start=NA, count=NA, verbose=FALSE,
signedbyte=TRUE, collapse_degen=TRUE, raw_datavals=FALSE )
Arguments
nc
An object of class ncdf4 (as returned by either
function nc_open
or function nc_create), indicating what file to read from.
varid
What variable to read the data from. Can be a string with the name
of the variable or an object of class ncvar4
If left unspecified, the function will determine if there
is only one variable in the file and, if so, read from that. If left unspecified
and there are multiple variables in the file, an error is generated.
This argument can also, optionally, specify the name of a dimension (usually the
unlimited dimension) in order to read values from a coordinate variable.
Note this is not usual practice, because the ncdim object already
contains all the dimension's values in the field named "vals". However, it can
sometimes be faster to turn off this automatic reading of the unlimited dimension's
values by using nc_open(filename, readunlim=FALSE), then read the
dimension values in later with this function.
start
A vector of indices indicating where to start reading the passed values
(beginning at 1).
The length of this vector must equal the number of dimensions the variable has.
Order is X-Y-Z-T (i.e., the time dimension is last). If not specified, reading
starts at the beginning of the file (1,1,1,...).
count
A vector of integers indicating the count of values to read
along each dimension (order is X-Y-Z-T).
The length of this vector must equal the number of dimensions the variable has.
If not specified and the variable does
NOT have an unlimited dimension, the entire variable is read.
As a special case, the value
"-1" indicates that all entries along that dimension should be read.
verbose
If TRUE, then progress information is printed.
signedbyte
If TRUE (default), then on-disk byte variables are interpreted
as signed. This is in accord with the netCDF standard. If FALSE, then
on-disk byte variables are interpreted as unsigned.
collapse_degen
If TRUE (the default), then degenerate (length==1) dimensions
in the returned array are removed.
raw_datavals
If TRUE, then the actual raw data values from the
file are returned with no conversion to NA (if equal to the missing value/fill value) or
scale/offset applied. Default is FALSE.
Details
This routine reads data values from a variable in an existing netCDF file. The file
must already have been opened with a call to nc_open.
Returned values will be in ordinary R double precision if the netCDF
variable type is float or double.
Returned values will be in R's integer storage mode if the netCDF
variable type is short or int.
Returned values will be of character type if the netCDF variable is
of character type.
Values of "NA" are supported; values in the data file that match the
variable's missing value attribute are automatically converted to "NA" before
being returned to the user.
See ncvar_change_missval for more information.
Data in a netCDF file is conceived as being a multi-dimensional array.
The number and length of dimensions is determined when the variable is
created. The 'start' and 'count' indices that this routine takes indicate
where the writing starts along each dimension, and the count of values
along each dimension to write. Note that the special count value "-1"
means "all the values along that dimension".
If the variable in the netCDF file has a scale and/or offset attribute defined,
the returned data are automatically and silently scaled and/or offset as requested.
Author(s)
David W. Pierce dpierce@ucsd.edu
References
http://dwpierce.com/software
See Also
ncvar_put.
Examples
## Not run:
# Start with the simplest example. If the file only has one variable in it,
# you can read the data as easily as this:
#
nc <- nc_open("salinity.nc")
# NOTE how not specifying varid reads the "only" var in the file
data <- ncvar_get( nc )
nc_close(nc)
# In this next example we read values from file "writevals.nc", which is created by
# the R code in the example section for function "ncvar_put". We open the
# file with readunlim=FALSE for potentially faster access, and to illustrate
# (below) how to read in the unlimited dimension values.
#
nc <- nc_open( "writevals.nc", readunlim=FALSE )
print(paste("The file has",nc$nvars,"variables"))
# This illustrates how to read all the data from a variable
v1 <- nc$var[[1]]
data1 <- ncvar_get( nc, v1 ) # by default, reads ALL the data
print(paste("Data for var ",v1$name,":",sep=""))
print(data1)
# This shows how the shape of the read data is preserved
v2 <- nc$var[[2]]
data2 <- ncvar_get( nc, v2 )
print(paste("Var 2 has name",v2$name,"and is of shape",dim(data2),
". Here are the values:"))
print(data2)
# This illustrates how to read data one timestep at a time. In this
# example we will elaborately show how to deal with a variable whose
# shape is completely unknown (i.e., how many dimensions, and what their
# sizes are). We will also, for illustration of a common case, show how
# to read in the values of the time dimension at each timestep.
v3 <- nc$var[[3]]
varsize <- v3$varsize
ndims <- v3$ndims
nt <- varsize[ndims] # Remember timelike dim is always the LAST dimension!
for( i in 1:nt ) {
# Initialize start and count to read one timestep of the variable.
start <- rep(1,ndims) # begin with start=(1,1,1,...,1)
start[ndims] <- i # change to start=(1,1,1,...,i) to read timestep i
count <- varsize # begin w/count=(nx,ny,nz,...,nt), reads entire var
count[ndims] <- 1 # change to count=(nx,ny,nz,...,1) to read 1 tstep
data3 <- ncvar_get( nc, v3, start=start, count=count )
# Now read in the value of the timelike dimension
timeval <- ncvar_get( nc, v3$dim[[ndims]]$name, start=i, count=1 )
print(paste("Data for variable",v3$name,"at timestep",i,
" (time value=",timeval,v3$dim[[ndims]]$units,"):"))
print(data3)
}
nc_close(nc)
## End(Not run)
ncdf4 documentation built on Sept. 11, 2024, 8:16 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| ncvar_get | R Documentation |
Read data from a netCDF file
Description
Reads data from an existing netCDF file.
Usage
ncvar_get(nc, varid=NA, start=NA, count=NA, verbose=FALSE,
signedbyte=TRUE, collapse_degen=TRUE, raw_datavals=FALSE )
Arguments
nc |
An object of class |
varid |
What variable to read the data from. Can be a string with the name
of the variable or an object of class |
start |
A vector of indices indicating where to start reading the passed values (beginning at 1). The length of this vector must equal the number of dimensions the variable has. Order is X-Y-Z-T (i.e., the time dimension is last). If not specified, reading starts at the beginning of the file (1,1,1,...). |
count |
A vector of integers indicating the count of values to read along each dimension (order is X-Y-Z-T). The length of this vector must equal the number of dimensions the variable has. If not specified and the variable does NOT have an unlimited dimension, the entire variable is read. As a special case, the value "-1" indicates that all entries along that dimension should be read. |
verbose |
If TRUE, then progress information is printed. |
signedbyte |
If TRUE (default), then on-disk byte variables are interpreted as signed. This is in accord with the netCDF standard. If FALSE, then on-disk byte variables are interpreted as unsigned. |
collapse_degen |
If TRUE (the default), then degenerate (length==1) dimensions in the returned array are removed. |
raw_datavals |
If TRUE, then the actual raw data values from the file are returned with no conversion to NA (if equal to the missing value/fill value) or scale/offset applied. Default is FALSE. |
Details
This routine reads data values from a variable in an existing netCDF file. The file
must already have been opened with a call to nc_open.
Returned values will be in ordinary R double precision if the netCDF variable type is float or double. Returned values will be in R's integer storage mode if the netCDF variable type is short or int. Returned values will be of character type if the netCDF variable is of character type.
Values of "NA" are supported; values in the data file that match the
variable's missing value attribute are automatically converted to "NA" before
being returned to the user.
See ncvar_change_missval for more information.
Data in a netCDF file is conceived as being a multi-dimensional array. The number and length of dimensions is determined when the variable is created. The 'start' and 'count' indices that this routine takes indicate where the writing starts along each dimension, and the count of values along each dimension to write. Note that the special count value "-1" means "all the values along that dimension".
If the variable in the netCDF file has a scale and/or offset attribute defined, the returned data are automatically and silently scaled and/or offset as requested.
Author(s)
David W. Pierce dpierce@ucsd.edu
References
http://dwpierce.com/software
See Also
ncvar_put.
Examples
## Not run:
# Start with the simplest example. If the file only has one variable in it,
# you can read the data as easily as this:
#
nc <- nc_open("salinity.nc")
# NOTE how not specifying varid reads the "only" var in the file
data <- ncvar_get( nc )
nc_close(nc)
# In this next example we read values from file "writevals.nc", which is created by
# the R code in the example section for function "ncvar_put". We open the
# file with readunlim=FALSE for potentially faster access, and to illustrate
# (below) how to read in the unlimited dimension values.
#
nc <- nc_open( "writevals.nc", readunlim=FALSE )
print(paste("The file has",nc$nvars,"variables"))
# This illustrates how to read all the data from a variable
v1 <- nc$var[[1]]
data1 <- ncvar_get( nc, v1 ) # by default, reads ALL the data
print(paste("Data for var ",v1$name,":",sep=""))
print(data1)
# This shows how the shape of the read data is preserved
v2 <- nc$var[[2]]
data2 <- ncvar_get( nc, v2 )
print(paste("Var 2 has name",v2$name,"and is of shape",dim(data2),
". Here are the values:"))
print(data2)
# This illustrates how to read data one timestep at a time. In this
# example we will elaborately show how to deal with a variable whose
# shape is completely unknown (i.e., how many dimensions, and what their
# sizes are). We will also, for illustration of a common case, show how
# to read in the values of the time dimension at each timestep.
v3 <- nc$var[[3]]
varsize <- v3$varsize
ndims <- v3$ndims
nt <- varsize[ndims] # Remember timelike dim is always the LAST dimension!
for( i in 1:nt ) {
# Initialize start and count to read one timestep of the variable.
start <- rep(1,ndims) # begin with start=(1,1,1,...,1)
start[ndims] <- i # change to start=(1,1,1,...,i) to read timestep i
count <- varsize # begin w/count=(nx,ny,nz,...,nt), reads entire var
count[ndims] <- 1 # change to count=(nx,ny,nz,...,1) to read 1 tstep
data3 <- ncvar_get( nc, v3, start=start, count=count )
# Now read in the value of the timelike dimension
timeval <- ncvar_get( nc, v3$dim[[ndims]]$name, start=i, count=1 )
print(paste("Data for variable",v3$name,"at timestep",i,
" (time value=",timeval,v3$dim[[ndims]]$units,"):"))
print(data3)
}
nc_close(nc)
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.