Input and output of Landlab raster-grid data in ESRI Ascii Raster format#

Read/write data from an ESRI ASCII file into a RasterModelGrid.

ESRI ASCII functions#

`read_asc_header`(asc_file)	Read header information from an ESRI ASCII raster file.
`read_esri_ascii`(asc_file[, grid, reshape, ...])	Read `RasterModelGrid` from an ESRI ASCII file.
`write_esri_ascii`(path, fields[, names, clobber])	Write landlab fields to ESRI ASCII.

exception BadHeaderLineError(line)[source]#

Bases: Error

Raise this error for a bad header is line.

exception DataSizeError(size, expected_size)[source]#

Bases: Error

Raise this error if the size of data does not match the header.

exception Error[source]#

Bases: Exception

Base class for errors in this module.

exception KeyTypeError(key, expected_type)[source]#

Bases: Error

Raise this error when a header’s key value is of the wrong type.

exception KeyValueError(key, message)[source]#

Bases: Error

Raise this error when a header’s key value has a bad value.

exception MismatchGridDataSizeError(size, expected_size)[source]#

Bases: Error

Raise this error if the data size does not match the grid size.

exception MismatchGridXYLowerLeft(llc, expected_llc)[source]#

Bases: Error

Raise this error if the file lower left does not match the grid.

exception MismatchGridXYSpacing(dx, expected_dx)[source]#

Bases: Error

Raise this error if the file cell size does not match the grid dx.

exception MissingRequiredKeyError(key)[source]#

Bases: Error

Raise this error when a header is missing a required key.

read_asc_header(asc_file)[source]#

Read header information from an ESRI ASCII raster file.

The header contains the following variables,

ncols: Number of cell columns
nrows: Number of cell rows
xllcenter or xllcorner: X (column) coordinate of lower-left
coordinate of grid (by center or lower-left corner of the cell)
yllcenter, yllcorner: Y (row) coordinate of lower-left
coordinate of grid (by center or lower-left corner of the cell)
cellsize: Grid spacing between rows and columns
nodata_value: No-data value (optional)

Parameters:

asc_file (file_like) – File-like object from which to read header.

Returns:

Header as key-value pairs.

Return type:

dict

Raises:

MissingRequiredKeyError – The header is missing a required key.
KeyTypeError – The header has the key but its values is of the wrong type.

Examples

>>> from io import StringIO
>>> from landlab.io.esri_ascii import read_asc_header

>>> contents = '''
... nrows 100
... ncols 200
... cellsize 1.5
... xllcenter 0.5
... yllcenter -0.5
... '''

>>> hdr = read_asc_header(StringIO(contents))
>>> hdr["nrows"], hdr["ncols"]
(100, 200)
>>> hdr["cellsize"]
1.5
>>> hdr["xllcenter"], hdr["yllcenter"]
(0.5, -0.5)

MissingRequiredKeyError is raised if the header does not contain all of the necessary keys.

>>> contents = '''
... ncols 200
... cellsize 1.5
... xllcenter 0.5
... yllcenter -0.5
... '''
>>> read_asc_header(StringIO(contents)) 
Traceback (most recent call last):
MissingRequiredKeyError: nrows

KeyTypeError is raised if a value is of the wrong type. For instance, nrows and ncols must be int.

>>> contents = '''
... nrows 100.5
... ncols 200
... cellsize 1.5
... xllcenter 0.5
... yllcenter -0.5
... '''
>>> read_asc_header(StringIO(contents)) 
Traceback (most recent call last):
KeyTypeError: Unable to convert nrows to <type 'int'>

read_esri_ascii(asc_file, grid=None, reshape=False, name=None, halo=0)[source]#

Read RasterModelGrid from an ESRI ASCII file.

Read data from asc_file, an ESRI ASCII file, into a RasterModelGrid. asc_file is either the name of the data file or is a file-like object.

The grid and data read from the file are returned as a tuple (grid, data) where grid is an instance of RasterModelGrid and data is a numpy array of doubles with that has been reshaped to have the number of rows and columns given in the header.

Parameters:

asc_file (str of file-like) – Data file to read.
reshape (boolean, optional) – Reshape the returned array, otherwise return a flattened array.
name (str, optional) – Add data to the grid as a named field.
grid (grid , optional) – Adds data to an existing grid instead of creating a new one.
halo (integer, optional) – Adds outer border of depth halo to the grid.

Returns:

(grid, data) – A newly-created RasterModelGrid and the associated node data.

Return type:

tuple

Raises:

DataSizeError – Data are not the same size as indicated by the header file.
MismatchGridDataSizeError – If a grid is passed, and the size of the grid does not agree with the size of the data.
MismatchGridXYSpacing – If a grid is passed, and the cellsize listed in the heading does not match the node spacing of the grid.
MismatchGridXYLowerLeft – If a grid is passed and the xllcorner and yllcorner do not match that of the grid.

Examples

>>> from landlab.io import read_esri_ascii
>>> from io import StringIO

>>> contents = '''
... ncols         3
... nrows         4
... xllcorner     1.
... yllcorner     2.
... cellsize      10.
... NODATA_value  -1
... 0. 1. 2.
... 3. 4. 5.
... 6. 7. 8.
... 9. 10. 11.
... '''

>>> (grid, data) = read_esri_ascii(StringIO(contents))

The returned grid is a RasterModelGrid with 4 rows and 3 columns.

>>> grid
RasterModelGrid((4, 3), xy_spacing=(10.0, 10.0), xy_of_lower_left=(1.0, 2.0))

Note that the first row of values is the bottom-most of the data file.

>>> data.reshape(grid.shape)
array([[  9.,  10.,  11.],
       [  6.,   7.,   8.],
       [  3.,   4.,   5.],
       [  0.,   1.,   2.]])

>>> (grid, data) = read_esri_ascii(StringIO(contents), halo=1)

Because of the halo, the returned grid now has two more rows and columns than before.

>>> grid
RasterModelGrid((6, 5), xy_spacing=(10.0, 10.0), xy_of_lower_left=(-9.0, -8.0))
>>> data.reshape(grid.shape)
array([[ -1.,  -1.,  -1.,  -1.,  -1.],
       [ -1.,   9.,  10.,  11.,  -1.],
       [ -1.,   6.,   7.,   8.,  -1.],
       [ -1.,   3.,   4.,   5.,  -1.],
       [ -1.,   0.,   1.,   2.,  -1.],
       [ -1.,  -1.,  -1.,  -1.,  -1.]])

write_esri_ascii(path, fields, names=None, clobber=False)[source]#

Write landlab fields to ESRI ASCII.

Write the data and grid information for fields to path in the ESRI ASCII format.

Parameters:

path (str) – Path to output file.
fields (field-like) – Landlab field object that holds a grid and associated values.
names (iterable of str, optional) – Names of the fields to include in the output file. If not provided, write all fields.
clobber (boolean) – If path exists, clobber the existing file, otherwise raise an exception.

Examples

>>> import numpy as np
>>> import os
>>> from landlab import RasterModelGrid
>>> from landlab.io.esri_ascii import write_esri_ascii

>>> grid = RasterModelGrid((4, 5), xy_spacing=(2., 2.))
>>> grid.at_node["air__temperature"] = np.arange(20.0)
>>> files = write_esri_ascii("test.asc", grid)  
>>> [os.path.basename(name) for name in sorted(files)])  
['test.asc']

>>> _ = grid.add_field("land_surface__elevation", np.arange(20.), at="node")
>>> grid.at_node["land_surface__elevation"] = np.arange(20.0)
>>> files = write_esri_ascii("test.asc", grid))  
>>> [os.path.basename(name) for name in sorted(files)])  
['test_air__temperature.asc', 'test_land_surface__elevation.asc']