Medium-level interface

Open a file

NetCDF.open — Function

NetCDF.open(fil::AbstractString,v::AbstractString)

opens a NetCDF variable v in the NetCDF file fil and returns an NcVar handle that implements the AbstractArray interface for reading and writing. Note that it is in the user's responsibility to close the file after usage using NetCDF.close.

Keyword arguments

mode mode in which the file is opened, defaults to NC_NOWRITE, choose NC_WRITE for write access
readdimvar determines if dimension variables will be read into the file structure, default is false

source

NetCDF.open(fil::AbstractString)

opens the NetCDF file fil and returns a NcFile handle. Note that it is in the user's responsibility to close the file after usage using NetCDF.close.

Keyword arguments

mode mode in which the file is opened, defaults to NC_NOWRITE, choose NC_WRITE for write access
readdimvar determines if dimension variables will be read into the file structure, default is false

source

NetCDF.open(f::Function, args...;kwargs...)

Opens a NetCDF file, applies the function f on the resulting file or variable handle and properly closes the file after usage. This is convenient to use together with the do block syntax, for example:

data = open("myfile.nc","myvar") do v NetCDF.readvar(v,start=[1,1,1], count=[-1,-1,1]) end

source

Getting information

The NetCDF.open function returns an object of type NcFile which contains meta-Information about the file and associated variables. You can index the NcFile object nc[varname] to retrieve an NcVar object and retrieve information about it. You can run keys(nc) to get a list of available variables.

Most of the following functions of the medium-level interface will use either an NcFile or an NcVar object as their first argument.

Reading data

NetCDF.readvar — Function

NetCDF.readvar(v::NcVar;start::Vector=ones(UInt,ndims(d)),count::Vector=size(d))

Reads the values from the file associated to the NcVar object v and returns them. By default the whole variable is read

Keyword arguments

start Vector of length ndim(v) setting the starting index for each dimension
count Vector of length ndim(v) setting the count of values to be read along each dimension. The value -1 is treated as a special case to read all values from this dimension

Example

Assume v is a NetCDF variable with dimensions (3,3,10).

x = NetCDF.readvar(v, start=[1,2,1], count=[3,1,-1])

This reads all values from the first and last dimension and only the second value from the second dimension.

source

NetCDF.readvar{T,N}(v::NcVar{T,N},I::Union{Integer, UnitRange, Colon}...)

Reads data from a NetCDF file with array-style indexing. Integers and UnitRanges and Colons are valid indices for each dimension.

source

Writing data

NetCDF.putvar — Function

NetCDF.putvar(v::NcVar,vals::Array;start::Vector=ones(Int,length(size(vals))),count::Vector=[size(vals)...])

Writes the values from the array vals to a NetCDF file. v is the NcVar handle of the respective variable and vals is an array with the same dimension as the variable in the NetCDF file.

Keyword arguments

start Vector of length ndim(v) setting the starting index for each dimension
count Vector of length ndim(v) setting the count of values to be read along each dimension. The value -1 is treated as a special case to read all values from this dimension

source

NetCDF.putvar(v::NcVar, val, i...)

Writes the value(s) val to the variable v while the indices are given in in an array-style indexing manner.

source

Creating files

To create a NetCDF file you first have to define the dimensions and variables that it is supposed to hold. As representations for NetCDF dimensions and variables there are the predefined NcVar and NcDim types. An NcDim object is created by:

NcDim(dimname, dimlength, atts=Dict{Any,Any}(); values=[], unlimited=false)

here dimname is the dimension name, dimlength is the dimension length. The optional argument values is a 1D array of values that are written to the dimension variable and the optional argument atts is a Dict holding pairs of attribute names and values. Setting unlimited=true creates an unlimited dimension.

After defining the dimensions, you can create NcVar objects with

NcVar(varname , dimlist; atts=Dict{Any,Any}(), t=Float64, compress=-1)

Here varname is the name of the variable, dimlist an array of type NcDim holding the dimensions associated to the variable, atts is a Dict holding pairs of attribute names and values. t is the data type that should be used for storing the variable. You can either specify a Julia type (Int16, Int32, Int64, Float32, Float64) which will be translated to (NC_SHORT, NC_INT, NC_INT64, NC_FLOAT, NC_DOUBLE) or directly specify one of the latter list. You can also set the compression level of the variable by setting compress to a number in the range 1..9 This has only an effect in NetCDF4 files.

Having defined the variables, the NetCDF file can be created:

NetCDF.create(filename, varlist, gatts=Dict{Any,Any}(),mode=NC_NETCDF4)

Here, filename is the name of the file to be created and varlist an array of NcVar holding the variables that should appear in the file. In the optional argument gatts you can specify a Dict containing global attributes and mode is the file type you want to create (NC_NETCDF4, NC_CLASSIC_MODEL or NC_64BIT_OFFSET).

Miscellaneous

Note that as of version 0.9 there is no need to close the NetCDF files anymore. This will be done through finalizers.

If you just want to synchronize your changes to the disk, run

NetCDF.sync(nc)

where nc is a NetCDF file handle.

As an alternative, NetCDF.open and NetCDF.create provide a method accepting a function as its first argument.

Interface for creating files

NetCDF.NcDim — Type

NcDim

Represents a NetCDF dimension of name name optionally holding the dimension values.

source

NetCDF.NcVar — Type

NcVar

NcVar{T,N,M} represents a NetCDF variable. It is a subtype of AbstractArray{T,N}, so normal indexing using [] will work for reading and writing data to and from a NetCDF file. NcVar objects are returned by NetCDF.open, by indexing an NcFile object (e.g. myfile["temperature"]) or, when creating a new file, by its constructor. The type parameter M denotes the NetCDF data type of the variable, which may or may not correspond to the Julia Data Type.

source

NetCDF.create — Function

NetCDF.create(name::AbstringString,varlist::Array{NcVar};gatts::Dict=Dict{Any,Any}(),mode::UInt16=NC_NETCDF4,add_finalizer = true)

Creates a new NetCDF file. Here, name is the name of the file to be created and varlist an array of NcVar holding the variables that should appear in the file.

Keyword arguments

gatts a Dict containing global attributes of the NetCDF file
mode NetCDF file type (NC_NETCDF4, NC_CLASSIC_MODEL or NC_64BIT_OFFSET), defaults to NC_NETCDF4

source

NetCDF.create(f::Function, args...;kwargs...)

Creates a NetCDF file, applies the function f on the resulting file or variable handle and properly closes the file after usage. This is convenient to use together with the do block syntax, for example:

d = NcDim("time",1:10) v = NcVar("obs",d); NetCDF.create("newfile.nc",v) do nc nc["obs"][:] = rand(10) end

source