R: Open a netCDF File

nc_open {ncdf4} | R Documentation

## Open a netCDF File

### Description

Opens an existing netCDF file for reading (or, optionally, writing).

### Usage

     nc_open( filename, write=FALSE, readunlim=TRUE, verbose=FALSE,
     	auto_GMT=TRUE, suppress_dimvals=FALSE )

### Arguments

`filename` | Name of the existing netCDF file to be opened.
`write` | If FALSE (default), then the file is opened read-only. If TRUE, then writing to the file is allowed.
`readunlim` | When invoked, this function reads in the values of all dimensions from the associated variables. This can be slow for a large file with a long unlimited dimension. If set to FALSE, the values for the unlimited dimension are not automatically read in (they can be read in later, manually, using `ncvar_get()`).
`verbose` | If TRUE, then messages are printed out during execution of this function.
`auto_GMT` | If TRUE, then GMT files are automatically detected. Does not yet do anything.
`suppress_dimvals` | If TRUE, then NO dimensional values are automatically read in from the file. (Use this if there are so many dimensional values that a out-of-memory error is generated).

### Details

This routine opens an existing netCDF file for reading (or, if write=TRUE, for writing). To create a new netCDF file, use `nc_create` instead.

In addition to simply opening the file, information about the file and its contents is read in and stored in the returned object, which is of class `ncdf4`. This class has the following user-accessible fields, all of which are read-only: 1) filename, which is a character string holding the name of the file; 2) ndims, which is an integer holding the number of dimensions in the file; 3) nvars, which is an integer holding the number of the variables in the file that are NOT coordinate variables (aka dimensional variables); 4) natts, which is an integer holding the number of global attributes; 5) unlimdimid, which is an integer holding the dimension id of the unlimited dimension, or -1 if there is none; 6) dim, which is a list of objects of class `ncdim4`; 7) var, which is a list of objects of class `ncvar4`; 8) writable, which is TRUE or FALSE, depending on whether the file was opened with write=TRUE or write=FALSE.

The concept behind the R interface to a netCDF file is that the `ncdf4` object returned by this function, as well as the list of `ncdim4` objects contained in the ncdf object's "dim" list and the `ncvar4` objects contained in the ncdf object's "var" list, completely describe the netCDF file. I.e., they hold the entire contents of the file's metadata. Therefore, there are no R interfaces to the explicit netCDF query functions, such as "nc_inq_nvars" or "nc_inq_natts". The upshot is, look in the ncdf4 object or its children to get information about the netCDF file. (Note: the `ncdim4` object is described in the help file for `ncdim_def`; the `ncvar4` object is described in the help file for `ncvar_def`).

Missing values: R uses "NA" as a missing value. Netcdf files have various standards for indicating a missing value. The most common is that a variable will have an attribute named "_FillValue" indicating the value that should be interpreted as a missing value. (For example, the _FillValue attribute might have the value of 1.e30, indicating that any data in the netcdf file with a value of 1.e30 should be interpreted as a missing value.) If the "_FillValue" attribute is found, then the ncdf4 package transparently maps all the netcdf file's missing values to NA's; this is the most common case. (The attribute "missing_value" is also recognized if there is no "_FillValue attribute.) If the netcdf file does not have a missing value, then the ncdf4 package assigns a default missing value of 1.e30 to the netcdcf file so that R NA's, which are always possible in the R environment, can be sensibly handled in the netcdf file. On rare occasions this can cause problems with non-compliant or incorrect netcdf files that implicitly use some particular value, for example 9.96921e+36, to indicate a missing value but without setting a proper _FillValue attribute. The best way to fix such netcdf files is to explicitly put in the correct _FillValue attribute using an `ncatt_put` call.

### Value

An object of class `ncdf4` that has the fields described above.

### Author(s)

David W. Pierce dpierce@ucsd.edu

### References

http://dwpierce.com/software

### See Also

`ncdim_def`, `ncvar_def`, `ncatt_put`.

### Examples

    # Define an integer dimension
    dimState <- ncdim_def( "StateNo", "count", 1:50 )

    # Make an integer variable.  Note that an integer variable can have
    # a double precision dimension, or vice versa; there is no fixed
    # relationship between the precision of the dimension and that of the
    # associated variable.  We just make an integer variable here for
    # illustration purposes.
    varPop <- ncvar_def("Pop", "count", dimState, -1,
    	longname="Population", prec="integer")

    # Create a netCDF file with this variable
    ncnew <- nc_create( "states_population.nc", varPop )

    # Write some values to this variable on disk.
    popAlabama <- 4447100
    ncvar_put( ncnew, varPop, popAlabama, start=1, count=1 )

    # Add source info metadata to file
    ncatt_put( ncnew, 0, "source", "Census 2000 from census bureau web site")

    nc_close(ncnew)

    # Now open the file and read its data
    ncold <- nc_open("states_population.nc")
    data <- ncvar_get(ncold)
    print("here is the data in the file:")
    print(data)
    nc_close( ncold )

    # Clean up example
    file.remove( "states_population.nc" )

[Package ncdf4 version 1.17 Index]