landlab

Read and Write netCDF Files

Reading

Read data from a NetCDF file into a RasterModelGrid.

Read netcdf

read_netcdf(nc_file[, just_grid]) Create a RasterModelGrid from a netcdf file.
read_netcdf(nc_file, just_grid=False)[source]

Create a RasterModelGrid from a netcdf file.

Create a new RasterModelGrid from the netcdf file, nc_file. If the netcdf file also contains data, add that data to the grid’s fields. To create a new grid without any associated data from the netcdf file, set the just_grid keyword to True.

Parameters:

nc_file : str

Name of a netcdf file.

just_grid : boolean, optional

Create a new grid but don’t add value data.

Returns:

RasterModelGrid

A newly-created RasterModelGrid.

Examples

Import read_netcdf() and the path to an example netcdf file included with landlab.

>>> from landlab.io.netcdf import read_netcdf
>>> from landlab.io.netcdf import NETCDF4_EXAMPLE_FILE

Create a new grid from the netcdf file. The example grid is a uniform rectilinear grid with 4 rows and 3 columns of nodes with unit spacing. The data file also contains data defined at the nodes for the grid for a variable called, surface__elevation.

>>> grid = read_netcdf(NETCDF4_EXAMPLE_FILE)
>>> grid.shape == (4, 3)
True
>>> grid.dy, grid.dx
(1.0, 1.0)
>>> [str(k) for k in grid.at_node.keys()]
['surface__elevation']
>>> grid.at_node['surface__elevation']
array([  0.,   1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.,
        11.])

read_netcdf() will try to determine the format of the netcdf file. For example, the same call will also work for netcdf3-formatted files.

>>> from landlab.io.netcdf import NETCDF3_64BIT_EXAMPLE_FILE
>>> grid = read_netcdf(NETCDF3_64BIT_EXAMPLE_FILE)
>>> grid.shape == (4, 3)
True
>>> grid.dy, grid.dx
(1.0, 1.0)

Writing

Write structured grids to NetCDF files.

Write netcdf

write_netcdf(path, fields[, attrs, append, ...]) Write landlab fields to netcdf.
write_netcdf(path, fields, attrs=None, append=False, format='NETCDF3_64BIT', names=None, at=None)[source]

Write landlab fields to netcdf.

Write the data and grid information for fields to path as NetCDF. If the append keyword argument in True, append the data to an existing file, if it exists. Otherwise, clobber an existing files.

Parameters:

path : str

Path to output file.

fields : field-like

Landlab field object that holds a grid and associated values.

append : boolean, optional

Append data to an existing file, otherwise clobber the file.

format : {‘NETCDF3_CLASSIC’, ‘NETCDF3_64BIT’, ‘NETCDF4_CLASSIC’, ‘NETCDF4’}

Format of output netcdf file.

attrs : dict

Attributes to add to netcdf file.

names : iterable of str, optional

Names of the fields to include in the netcdf file. If not provided, write all fields.

at : {‘node’, ‘cell’}, optional

The location where values are defined.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.io.netcdf import write_netcdf

Create a uniform rectilinear grid with four rows and 3 columns, and add some data fields to it.

>>> rmg = RasterModelGrid(4, 3)
>>> _ = rmg.add_field('node', 'topographic__elevation', np.arange(12.))
>>> _ = rmg.add_field('node', 'uplift_rate', 2. * np.arange(12.))

Create a temporary directory to write the netcdf file into.

>>> import tempfile, os
>>> temp_dir = tempfile.mkdtemp()
>>> os.chdir(temp_dir)

Write the grid to a netcdf3 file but only include the uplift_rate data in the file.

>>> write_netcdf('test.nc', rmg, format='NETCDF3_64BIT',
...     names='uplift_rate')

Read the file back in and check its contents.

>>> from scipy.io import netcdf
>>> fp = netcdf.netcdf_file('test.nc', 'r')
>>> 'uplift_rate' in fp.variables
True
>>> 'topographic__elevation' in fp.variables
False
>>> fp.variables['uplift_rate'][:].flatten()
array([  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.,  20.,
        22.])
>>> _ = rmg.add_field('cell', 'air__temperature', np.arange(2.))
>>> write_netcdf('test-cell.nc', rmg, format='NETCDF3_64BIT',
...     names='air__temperature', at='cell')
write_raster_netcdf(path, fields, attrs=None, append=False, format='NETCDF4', names=None, at=None)[source]

Write Raster Model Grid landlab fields to netcdf.

Write the data and grid information for fields to path as NetCDF.

This method is for Raster Grids only and takes advantage of regular x and y spacing to save memory.

If the append keyword argument in True, append the data to an existing file, if it exists. Otherwise, clobber an existing files.

Parameters:

path : str

Path to output file.

fields : field-like

Landlab field object that holds a grid and associated values. This must be a Raster type.

append : boolean, optional

Append data to an existing file, otherwise clobber the file.

format : {‘NETCDF4’}

Format of output netcdf file.

attrs : dict

Attributes to add to netcdf file.

names : iterable of str, optional

Names of the fields to include in the netcdf file. If not provided, write all fields.

at : {‘node’}, optional

The location where values are defined. Presently only implemented for type ‘node’.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.io.netcdf import write_raster_netcdf

Create a uniform rectilinear grid with four rows and 3 columns, and add some data fields to it.

>>> rmg = RasterModelGrid(4, 3)
>>> _ = rmg.add_field('node', 'topographic__elevation', np.arange(12.))
>>> _ = rmg.add_field('node', 'uplift_rate', 2. * np.arange(12.))

Create a temporary directory to write the netcdf file into.

>>> import tempfile, os
>>> temp_dir = tempfile.mkdtemp()
>>> os.chdir(temp_dir)

Write the grid to a netcdf4 file but only include the uplift_rate data in the file.

>>> write_raster_netcdf('test.nc', rmg, format='NETCDF3_64BIT',
...     names='uplift_rate')

Read the file back in and check its contents.

>>> from scipy.io import netcdf
>>> fp = netcdf.netcdf_file('test.nc', 'r')
>>> 'uplift_rate' in fp.variables
True
>>> 'topographic__elevation' in fp.variables
False
>>> fp.variables['uplift_rate'][:].flatten()
array([  0.,   2.,   4.,   6.,   8.,  10.,  12.,  14.,  16.,  18.,  20.,
        22.])

Error Handling

Exceptions to raise for the netcdf module.

exception Error[source]

Bases: exceptions.Exception

Base class for errors in this package.

exception NotRasterGridError[source]

Bases: landlab.io.netcdf.errors.Error

Raise if grid is not uniform rectilinear.

Raise this error if the grid defined in the netcdf file is not uniform rectilinear with constant spacing in all dimensions.