Excdf

Elixir NIF bindings for the netCDF C library. Read and write netCDF files — the standard format for array-oriented scientific data (climate, ocean, atmospheric, geospatial, and more).

Prerequisites

The netCDF C library must be installed on your system:

# macOS
brew install netcdf

# Ubuntu / Debian
sudo apt-get install libnetcdf-dev

# Fedora / RHEL
sudo dnf install netcdf-devel

The nc-config tool (installed alongside libnetcdf) is used at compile time to locate headers and libraries automatically.

Installation

Add excdf to your list of dependencies in mix.exs:

def deps do
  [
    {:excdf, "~> 0.1.0"}
  ]
end

Quick start

Writing a netCDF file

# Create a new netCDF-4 file
{:ok, nc} = Excdf.create("weather.nc", :netcdf4)

# Define dimensions
{:ok, x_dim} = Excdf.def_dim(nc, "x", 10)
{:ok, y_dim} = Excdf.def_dim(nc, "y", 20)
{:ok, time_dim} = Excdf.def_dim(nc, "time", :unlimited)

# Define a variable with its dimensions
{:ok, temp_var} = Excdf.def_var(nc, "temperature", :double, [time_dim, y_dim, x_dim])

# Add metadata as attributes
:ok = Excdf.put_att(nc, temp_var, "units", "kelvin")
:ok = Excdf.put_att(nc, temp_var, "long_name", "Surface Temperature")
:ok = Excdf.put_att_global(nc, "title", "Example weather dataset")

# Switch to data mode and write values
:ok = Excdf.enddef(nc)
:ok = Excdf.put_var(nc, temp_var, :double, List.duplicate(293.15, 10 * 20))

:ok = Excdf.close(nc)

Reading a netCDF file

{:ok, nc} = Excdf.open("weather.nc")

# Get a summary of everything in the file
{:ok, info} = Excdf.info(nc)
# => %{
#   dimensions: %{"x" => 10, "y" => 20, "time" => 1},
#   variables: [%{name: "temperature", type: :double, ...}],
#   global_attributes: %{"title" => "Example weather dataset"}
# }

# Read variable data by name or ID
{:ok, {:double, shape, data}} = Excdf.get_var(nc, "temperature")

# Read a slice (hyperslab)
{:ok, {:double, slice}} = Excdf.get_vara(nc, 0, [0, 0, 0], [1, 5, 5])

# Read attributes
{:ok, "kelvin"} = Excdf.get_att(nc, 0, "units")
{:ok, "Example weather dataset"} = Excdf.get_att_global(nc, "title")

:ok = Excdf.close(nc)

Supported data types

Supported file formats

API reference

See the full API documentation on HexDocs.

License

MIT License. See LICENSE for details.