Datasets

NCDataset(filename::AbstractString, mode = "r";
        format::Symbol = :netcdf4, attrib = [])

Load, create, or even overwrite a NetCDF file at filename, depending on mode:

• "r" (default) : open an existing netCDF file or OPeNDAP URL in read-only mode.
• "c" : create a new NetCDF file at filename (an existing file with the same name will be overwritten).
• "a" : open filename into append mode (i.e. existing data in the netCDF file is not overwritten and a variable can be added).

Notice that this does not close the dataset, use close on the result (or see below the do-block).

The optional parameter attrib is an iterable of attribute name and attribute value pairs, for example a Dict, DataStructures.OrderedDict or simply a vector of pairs (see example below).

Supported format values:

• :netcdf4 (default): HDF5-based NetCDF format.
• :netcdf4_classic: Only netCDF 3 compatible API features will be used.
• :netcdf3_classic: classic netCDF format supporting only files smaller than 2GB.
• :netcdf3_64bit_offset: improved netCDF format supporting files larger than 2GB.

Files can also be open and automatically closed with a do block.

NCDataset("file.nc") do ds
    data = ds["temperature"][:,:]
end

Here is an attribute example:

using DataStructures
NCDataset("file.nc", "c", attrib = OrderedDict("title" => "my first netCDF file")) do ds
   defVar(ds,"temp",[10.,20.,30.],("time",))
end;

NCDataset is an alias to NCDataset.

ds = NCDataset(var::CFVariable)
ds = NCDataset(var::Variable)

Return the NCDataset containing the variable var.

mfds = NCDataset(fnames,mode = "r"; aggdim = nothing, deferopen = true)

Opens a multi-file dataset in read-only "r" or append mode "a". fnames is a vector of file names. Variables are aggregated over the first unlimited dimension or over the dimension aggdim if specified. The append mode is only implemented when deferopen is false.

All variables containing the dimension aggdim are aggregated. The variable who do not contain the dimension aggdim are assumed constant.

If deferopen is false, all files are opened at the same time. However the operating system might limit the number of open files. In Linux, the limit can be controled with the command ulimit.

keys(ds::NCDataset)

Return a list of all variables names in NCDataset ds.

haskey(ds::NCDataset,name)
haskey(d::Dimensions,name)
haskey(ds::Attributes,name)

Return true if the NCDataset ds (or dimension/attribute list) has a variable (dimension/attribute) with the name name. For example:

ds = NCDataset("/tmp/test.nc","r")
if haskey(ds,"temperature")
    println("The file has a variable 'temperature'")
end

if haskey(ds.dim,"lon")
    println("The file has a dimension 'lon'")
end

This example checks if the file /tmp/test.nc has a variable with the name temperature and a dimension with the name lon.

v = getindex(ds::NCDataset,varname::AbstractString)

Return the NetCDF variable varname in the dataset ds as a NCDataset.CFVariable. The CF convention are honored when the variable is indexed:

• _FillValue will be returned as missing
• scale_factor and add_offset are applied
• time variables (recognized by the units attribute) are returned usually as DateTime object. Note that DateTimeAllLeap, DateTimeNoLeap and DateTime360Day cannot be converted to the proleptic gregorian calendar used in julia and are returned as such.

A call getindex(ds,varname) is usually written as ds[varname].

v = variable(ds::NCDataset,varname::String)

Return the NetCDF variable varname in the dataset ds as a NCDataset.Variable. No scaling or other transformations are applied when the variable v is indexed.

sync(ds::NCDataset)

Write all changes in NCDataset ds to the disk.

close(ds::NCDataset)

Close the NCDataset ds. All pending changes will be written to the disk.

path(ds::NCDataset)

Return the file path (or the opendap URL) of the NCDataset ds

ncgen(fname; ...)
ncgen(fname,jlname; ...)

Generate the Julia code that would produce a NetCDF file with the same metadata as the NetCDF file fname. The code is placed in the file jlname or printed to the standard output. By default the new NetCDF file is called filename.nc. This can be changed with the optional parameter newfname.

varbyattrib(ds, attname = attval)

Returns a list of variable(s) which has the attribute attname matching the value attval in the dataset ds. The list is empty if the none of the variables has the match. The output is a list of CFVariables.

Examples

Load all the data of the first variable with standard name "longitude" from the NetCDF file results.nc.

julia> ds = NCDataset("results.nc", "r");
julia> data = varbyattrib(ds, standard_name = "longitude")[1][:]

write(dest_filename::AbstractString, src::AbstractDataset; include = keys(src), exclude = [])
write(dest::NCDataset, src::AbstractDataset; include = keys(src), exclude = [])

Write the variables of src dataset into an empty dest dataset (which must be opened in mode "a" or "c"). The keywords include and exclude configure which variable of src should be included (by default all), or which should be excluded (by default none).

If the first argument is a file name, then the dataset is open in create mode (c).

This function is useful when you want to save the dataset from a multi-file dataset.

defGroup(ds::NCDataset,groupname, attrib = []))

Create the group with the name groupname in the dataset ds. attrib is a list of attribute name and attribute value pairs (see NCDataset).

group = getindex(g::NCDatasets.Groups,groupname::AbstractString)

Return the NetCDF group with the name groupname. For example:

julia> ds = NCDataset("results.nc", "r");
julia> forecast_group = ds.group["forecast"]
julia> forecast_temp = forecast_group["temperature"]

Base.keys(g::NCDatasets.Groups)

Return the names of all subgroubs of the group g.

groupname(ds::NCDataset)

Return the group name of the NCDataset ds