API

create_nc!(file::String)

Create an empty netcdf file, given

• file Path to save the netcdf dataset

create_nc!(file::String, dim_names::Vector{String}, dim_sizes::Vector)

Create an empty netcdf file with dimensions, given

• file Path to save the netcdf dataset
• dim_names Dimension names in the netcdf file
• dim_sizes Sizes of the dimensions (must be Integer or Inf), the dimension is growable if size is Integer 0

Examples

create_nc!("test.nc");
create_nc!("test1.nc", String["lon", "lat", "ind"], [36, 18, 0]);
create_nc!("test2.nc", String["lon", "lat", "ind"], [36, 18, Inf]);

add_nc_dim!(ds::Dataset, dim_name::String, dim_size::Int)
add_nc_dim!(ds::Dataset, dim_name::String, dim_size::AbstractFloat)
add_nc_dim!(file::String, dim_name::String, dim_size::Union{AbstractFloat,Int})

Add dimension information to netcdf dataset, given

• ds A NCDatasets.Dataset type dataset
• dim_name Dimension name
• dim_size Integer dimension size (0 for Inf, growable)

Examples

ds = Dataset("test.nc", "a");
add_nc_dim!(ds, "lat", 180);
add_nc_dim!(ds, "ind", 0);
add_nc_dim!(ds, "idx", Inf);
close(ds);

add_nc_dim!("test.nc", "lon", 360);
add_nc_dim!("test.nc", "idy", Inf);

append_nc!(ds::Dataset, var_name::String, var_data::Array{T,N}, var_attributes::Dict{String,String}, dim_names::Vector{String}; compress::Int = 4) where {T<:Union{AbstractFloat,Integer,String},N}
append_nc!(file::String, var_name::String, var_data::Array{T,N}, var_attributes::Dict{String,String}, dim_names::Vector{String}; compress::Int = 4) where {T<:Union{AbstractFloat,Integer,String},N}

Append data to existing netcdf dataset, given

• ds A NCDatasets.Dataset type dataset
• var_name New variable name to write to
• var_data New variable data to write, can be integer, float, and string with N dimens
• var_attributes New variable attributes
• dim_names Dimension names in the netcdf file
• compress Compression level fro NetCDF, default is 4
• file Path of the netcdf dataset

Examples

create_nc!("test.nc", String["lon", "lat", "ind"], [36, 18, 5]);

dset = Dataset("test.nc", "a");
append_nc!(dset, "str", ["A" for i in 1:18], Dict("longname" => "test strings"), ["lat"]);
append_nc!(dset, "d3d", rand(36,18,5), Dict("longname" => "a 3d dataset"), ["lon", "lat", "ind"]);
close(dset);

append_nc!("test.nc", "lat", collect(1:18), Dict("longname" => "latitude"), ["lat"]);
append_nc!("test.nc", "d2d", rand(36,18), Dict("longname" => "a 2d dataset"), ["lon", "lat"]);

grow_nc!(ds::Dataset, var_name::String, in_data::Union{AbstractFloat,Array,Integer,String}, pending::Bool)
grow_nc!(file::String, var_name::String, in_data::Union{AbstractFloat,Array,Integer,String}, pending::Bool)

Grow the netcdf dataset, given

• ds A NCDatasets.Dataset type dataset
• var_name New variable name to write to
• in_data New data to grow, can be integer, float, and string with N dimens
• pending If true, the new data is appened to the end (growth); if false, the data will replace the ones from the bottom (when dimension has already growed)
• file Path of the netcdf dataset

Note that if there are more variables to grow at the same time, set pending to true only for the first time you call this function, and set pending to false for the rest variables.

Examples

create_nc!("test.nc", String["lon", "lat", "ind"], [36, 18, 0]);
dset = Dataset("test.nc", "a");
append_nc!(dset, "lat", collect(1:18), Dict("longname" => "latitude"), ["lat"]);
append_nc!(dset, "lon", collect(1:36), Dict("longname" => "longitude"), ["lon"]; compress=4);
append_nc!(dset, "ind", collect(1:5), Dict("longname" => "index"), ["ind"]);
append_nc!(dset, "d2d", rand(36,18), Dict("longname" => "a 2d dataset"), ["lon", "lat"]);
append_nc!(dset, "d3d", rand(36,18,5), Dict("longname" => "a 3d dataset"), ["lon", "lat", "ind"]);
grow_nc!(dset, "ind", 6, true);
grow_nc!(dset, "d3d", rand(36,18), false);
grow_nc!(dset, "d3d", rand(36,18), true);
grow_nc!(dset, "ind", 7, false);
close(dset);

grow_nc!("test.nc", "ind", 8, true);
grow_nc!("test.nc", "d3d", rand(36,18), false);
grow_nc!("test.nc", "d3d", rand(36,18), true);
grow_nc!("test.nc", "ind", 9, false);

dimname_nc(file::String)

Return all the names of the dimensions, given

• file Path of the netcdf dataset

Examples

dims = dimname_nc("test.nc");

varname_nc(ds::Dataset)
varname_nc(file::String)

Return all the names of the variables (excluding the dimensions), given

• ds NCDatasets.Dataset type dataset
• file Path of the netcdf dataset

Examples

dset = Dataset("test.nc");
vars = varname_nc(dset);
close(dset);

vars = varname_nc("test.nc");

size_nc(file::String, var_name::String)

Return the dimensions and size of a NetCDF dataset, given

• file Path of the netcdf dataset
• var_name Variable name

Examples

ndims,sizes = size_nc("test.nc", "test");

find_variable(ds::Dataset, var_name::String)

Return the path to dataset if it exists, given

• ds NCDatasets.Dataset type dataset
• var_name Variable to read

read_nc(file::String, var_name::String; transform::Bool = true)
read_nc(T, file::String, var_name::String; transform::Bool = true)

Read entire data from NC file, given

• file Path of the netcdf dataset
• var_name Variable to read
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data
• T Number type

read_nc(file::String, var_name::String, indz::Int; transform::Bool = true)
read_nc(T, file::String, var_name::String, indz::Int; transform::Bool = true)

Read a subset from nc file, given

• file Path of the netcdf dataset
• var_name Variable name
• indz The 3rd index of subset data to read
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data
• T Number type

Note that the dataset must be a 1D or 3D array to use this method.

read_nc(file::String, var_name::String, indx::Int, indy::Int; transform::Bool = true)
read_nc(T, file::String, var_name::String, indx::Int, indy::Int; transform::Bool = true)

Read the subset data for a grid, given

• file Path of the netcdf dataset
• var_name Variable name
• indx The 1st index of subset data to read, typically longitude
• indy The 2nd index of subset data to read, typically latitude
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data
• T Number type

read_nc(file::String, var_name::String, indx::Int, indy::Int, indz::Int; transform::Bool = true)
read_nc(T, file::String, var_name::String, indx::Int, indy::Int, indz::Int; transform::Bool = true)

Read the data at a grid, given

• file Path of the netcdf dataset
• var_name Variable name
• indx The 1st index of subset data to read, typically longitude
• indy The 2nd index of subset data to read, typically latitude
• indz The 3rd index of subset data to read, typically time
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data
• T Number type

read_nc(file::String, selections::Vector{String} = varname_nc(file); transform::Bool = true)

Read the selected variables from a netcdf file as a DataFrame, given

• file Path of the netcdf dataset
• selections Variables to read from the file
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data

read_nc(file::String, var_name::String, dim_array::Vector; transform::Bool = true)

Read parts of the data specified in an array

• file Path of the netcdf dataset
• var_name Variable name
• dim_array Vector containing the parts of the data to read
• transform If true, transform the data using NCDatasets rules, otherwise read the raw data

Examples

# read data labeled as test from test.nc
save_nc!("test.nc", "test", rand(36,18,12), Dict("description" => "Random randoms"));
data = read_nc("test.nc", "test");
data = read_nc(Float32, "test.nc", "test");

# read 1st layer data labeled as test from test.nc
data = read_nc("test.nc", "test", 1);
data = read_nc(Float32, "test.nc", "test", 1);

# read the data (time series) at a grid
save_nc!("test1.nc", "test", rand(36,18), Dict("description" => "Random randoms"));
save_nc!("test2.nc", "test", rand(36,18,12), Dict("description" => "Random randoms"));
data1 = read_nc("test1.nc", "test", 1, 1);
data2 = read_nc("test2.nc", "test", 1, 1);
data1 = read_nc(Float32, "test1.nc", "test", 1, 1);
data2 = read_nc(Float32, "test2.nc", "test", 1, 1);

# read the data at a grid
data = read_nc("test.nc", "test", 1, 1, 1);
data = read_nc(Float32, "test.nc", "test", 1, 1, 1);

# read the data as a DataFrame
df_raw = DataFrame();
df_raw[!,"A"] = rand(5);
df_raw[!,"B"] = rand(5);
df_raw[!,"C"] = rand(5);
save_nc!("test.nc", df_raw);
df_new = read_nc("test.nc");
df_new = read_nc("test.nc", ["A", "B"]);

save_nc!(file::String,
         var_name::String,
         var_data::Array{T,N},
         var_attribute::Dict{String,String};
         var_dims::Vector{String} = N == 2 ? ["lon", "lat"] : ["lon", "lat", "ind"],
         compress::Int = 4,
         growable::Bool = false) where {T<:Union{AbstractFloat,Integer,String},N}

Save the 1D, 2D, or 3D data as netcdf file, given

• file Path to save the dataset
• var_name Variable name for the data in the NC file
• var_data Data to save
• var_attribute Variable attributes for the data, such as unit and long name
• var_dims Dimension name of each dimension of the variable data
• compress Compression level fro NetCDF, default is 4
• growable If true, make index growable, default is false

Note that this is a wrapper function of createnc and appendnc:

• If var_data is 1D, the dim is set to ind
• If vardata is 2D, and no vardims are given, the dims are set to lon and lat
• If vardata is 3D, and no vardims are given, the dims are set to lon, lat, and ind

save_nc!(file::String, df::DataFrame, var_names::Vector{String}, var_attributes::Vector{Dict{String,String}}; compress::Int = 4, growable::Bool = false)
save_nc!(file::String, df::DataFrame; compress::Int = 4, growable::Bool = false)

Save DataFrame to NetCDF, given

• file Path to save the data
• df DataFrame to save
• var_names The label of data in DataFrame to save
• var_attributes Variable attributes for the data to save
• compress Compression level fro NetCDF, default is 4
• growable If true, make index growable, default is false

Examples

# save 1D, 2D, and 3D data
data1 = rand(12) .+ 273.15;
data2 = rand(36,18) .+ 273.15;
data3 = rand(36,18,12) .+ 273.15;

save_nc!("data1.nc", "data1", data1, Dict("description" => "Random temperature", "unit" => "K"));
save_nc!("data2.nc", "data2", data2, Dict("description" => "Random temperature", "unit" => "K"));
save_nc!("data3.nc", "data3", data3, Dict("description" => "Random temperature", "unit" => "K"));

# save DataFrame
df = DataFrame();
df[!,"A"] = rand(5);
df[!,"B"] = rand(5);
df[!,"C"] = rand(5);
save_nc!("dataf.nc", df, ["A","B"], [Dict("A" => "Attribute A"), Dict("B" => "Attribute B")]);

save_nc!("test.nc", df);

switch_netcdf_lib!(; use_default::Bool = true, user_defined::String = "/home/runner/.julia/conda/3/lib/libnetcdf.so")

Switch between the default NetCDF library and a user-defined one, given

• use_default Whether to use the default libnetcdf library shipped with NCDatasets.jl
• user_defined The path to the user-defined libnetcdf library (used only when use_default is false)