# 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]

exception DataSizeError(size, expected_size)[source]

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]

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

exception KeyValueError(key, message)[source]

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

exception MismatchGridDataSizeError(size, expected_size)[source]

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

exception MismatchGridXYLowerLeft(llc, expected_llc)[source]

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

exception MismatchGridXYSpacing(dx, expected_dx)[source]

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

exception MissingRequiredKeyError(key)[source]

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

read_asc_header(asc_file)[source]

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. Header as key-value pairs. dict 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
>>> contents = StringIO('''
...     nrows 100
...     ncols 200
...     cellsize 1.5
...     xllcenter 0.5
...     yllcenter -0.5
... ''')
>>> hdr['nrows'], hdr['ncols']
(100, 200)
>>> hdr['cellsize']
1.5
>>> hdr['xllcenter'], hdr['yllcenter']
(0.5, -0.5)


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

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


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

>>> contents = StringIO('''
...     nrows 100.5
...     ncols 200
...     cellsize 1.5
...     xllcenter 0.5
...     yllcenter -0.5
... ''')
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. (grid, data) – A newly-created RasterModel grid and the associated node data. tuple 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 grid dx and dy. MismatchGridXYLowerLeft – If a grid is passed and the xllcorner and yllcorner do not match that of the grid.

Examples

Assume that fop is the name of a file that contains text below (make sure you have your path correct): ncols 3 nrows 4 xllcorner 1. yllcorner 2. cellsize 10. NODATA_value -9999 0. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. ——– >>> from landlab.io import read_esri_ascii >>> (grid, data) = read_esri_ascii(‘fop’) # doctest: +SKIP >>> #grid is an object of type RasterModelGrid with 4 rows and 3 cols >>> #data contains an array of length 4*3 that is equal to >>> # [9., 10., 11., 6., 7., 8., 3., 4., 5., 0., 1., 2.] >>> (grid, data) = read_esri_ascii(‘fop’, halo=1) # doctest: +SKIP >>> #now the data has a nodata_value ring of -9999 around it. So array is >>> # [-9999, -9999, -9999, -9999, -9999, -9999, >>> # -9999, 9., 10., 11., -9999, >>> # -9999, 6., 7., 8., -9999, >>> # -9999, 3., 4., 5., -9999, >>> # -9999, 0., 1., 2. -9999, >>> # -9999, -9999, -9999, -9999, -9999, -9999]

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
>>> import tempfile
>>> from landlab import RasterModelGrid
>>> from landlab.io.esri_ascii import write_esri_ascii

>>> grid = RasterModelGrid((4, 5), xy_spacing=(2., 2.))
>>> _ = grid.add_field("air__temperature", np.arange(20.), at="node")
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     fname = os.path.join(tmpdirname, 'test.asc')
...     files = write_esri_ascii(fname, grid)
>>> for file in files:
...     print(os.path.basename(file))
test.asc

>>> _ = grid.add_field("land_surface__elevation", np.arange(20.), at="node")
>>> with tempfile.TemporaryDirectory() as tmpdirname:
...     fname = os.path.join(tmpdirname, 'test.asc')
...     files = write_esri_ascii(fname, grid)
>>> files.sort()
>>> for file in files:
...     print(os.path.basename(file))
test_air__temperature.asc
test_land_surface__elevation.asc