Crate netcdf 

Rust bindings for Unidata’s libnetcdf

This crate allows one to store and retrieve multi-dimensional arrays from a netCDF supported format, which can be a netCDF file, a subset of hdf5 files, or from a DAP url.

netCDF files are self-contained, they contain metadata about the data contained in them. See the CF Conventions for conventions used for climate and forecast models.

To explore the documentation, see the Functions section, in particular open(), create(), and append().

For more information see:

• The official introduction to netCDF
• The NetCDF-c repository

Installing netcdf-c

This crate depends on Unidata NetCDF-c and dependencies of this library (such as hdf5). An alternative to the system libraries is to use the bundled sources of netcdf by using the static feature of this crate. This will require build utilities such as cmake, c++ compiler and more.

Examples

How to read a variable from a file:

// Open the file `simple_xy.nc`:
let file = netcdf::open("simple_xy.nc")?;

// Get the variable in this file with the name "data"
let var = &file.variable("data").expect("Could not find variable 'data'");

// Read a single datapoint from a 1D variable as a numeric type
let data_i32 = var.get_value::<i32, _>(4)?;
let data_f32 : f32 = var.get_value(5)?;

// If your variable is multi-dimensional you need to use a
// type that supports `Selection`, such as a tuple or array
let data_i32 = var.get_value::<i32, _>([40, 0, 0])?;
let data_i32 = var.get_value::<i32, _>((40, 0, 0))?;

// You can use `values_arr()` to get all the data from the variable.
// This requires the `ndarray` feature
// Passing `..` will give you the entire slice
let data = var.get::<i32, _>(..)?;

// A subset can also be selected, the following will extract the slice at
// `(40, 0, 0)` and get a dataset of size `100, 100` from this
let data = var.get::<i32, _>(([40, 0 ,0], [1, 100, 100]))?;
let data = var.get::<i32, _>((40, ..100, ..100))?;

// You can read into an ndarray to reuse an allocation
let mut data = ndarray::Array::<f32, _>::zeros((100, 100));
var.get_into(data.view_mut(), (0, .., ..))?;

How to create a new file and write to it:

// Create a new file with default settings
let mut file = netcdf::create("crabs.nc")?;

// We must create a dimension which corresponds to our data
file.add_dimension("ncrabs", 10)?;
// These dimensions can also be unlimited and will be resized when writing
file.add_unlimited_dimension("time")?;

// A variable can now be declared, and must be created from the dimension names.
let mut var = file.add_variable::<i32>(
            "crab_coolness_level",
            &["time", "ncrabs"],
)?;
// Metadata can be added to the variable, but will not be used when
// writing or reading data
var.put_attribute("units", "Kelvin")?;
var.put_attribute("add_offset", 273.15_f32)?;

// Data can then be created and added to the variable
let data : Vec<i32> = vec![42; 10];
var.put_values(&data, (0, ..))?;

// Values can be added along the unlimited dimension, which
// resizes along the `time` axis
var.put_values(&data, (11, ..))?;

// Using the ndarray feature you can also use
let values = ndarray::Array::from_shape_fn((5, 10), |(j, i)| (j * 10 + i) as f32);
var.put(values.view(), (11.., ..))?;

How to derive NcTypeDescriptor for a custom type (requires derive feature flag). See NcTypeDescriptor for additional examples.

#[repr(C)]
#[derive(netcdf::NcType)]
struct Foo {
  bar: f64,
  baz: i64,
}
let mut file = netcdf::create("custom.nc")?;
file.add_type::<Foo>()?;
let mut var = file.add_variable::<Foo>("variable", &[])?;
var.put_value(Foo { bar: 1.0, baz: 2 }, ())?;

Modules

rc4.9.2

Set and get configuration variables

types

Types found in netCDF files

Structs

Attribute

Extra properties of a variable or a group can be represented with attributes. Primarily added with add_attribute on the variable and group

Dimension

Represents a netcdf dimension

DimensionIdentifier

Unique identifier for a dimension in a file. Used when names can not be used directly, for example when dealing with nested groups

File

Read only accessible file

FileMemhas-mmap

The memory mapped file is kept in this structure to extend the lifetime of the buffer.

FileMut

Mutable access to file.

Group

Main component of the netcdf format. Holds all variables, attributes, and dimensions. A group can always see the parent’s items, but a parent can not access the children’s items.

GroupMut

Mutable access to a group.

Options

Options for opening, creating, and appending files

Variable

This struct defines a netCDF variable.

VariableMut

Mutable access to a variable.

Enums

AttributeValue

Holds the attribute value which can be inserted and returned from the file

Endianness

Enum for variables endianness

Error

Various error types that can occur in this crate

Extent

An extent of a dimension

Extents

A selector for putting and getting data along a dataset

Traits

NcTypeDescriptor

This trait allows reading and writing basic and user defined types.

Functions

append

Open a netCDF file in append mode

append_with

Open a netCDF file in append mode with the given options

create

Open a netcdf file in create mode

create_with

Open a netCDF file in create mode with the given options

open

Open a netCDF file in read mode

open_memhas-mmap

Open a netCDF file from a buffer

open_with

Open a netCDF file in read mode with the given options

Type Aliases

Result

Result type used in this crate

Derive Macros

NcTypederive

Derives NcTypeDescriptor for user defined types.