landlab.io.esri_ascii¶

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

ESRI ASCII functions¶

`dump`(grid[, stream, at, name])	Dump a grid field to ESRII ASCII format.
`lazy_load`()	Parse a RasterModelGrid from a ESRI ASCII format stream.
`lazy_loads`()	Parse a ESRI ASCII formatted string.
`load`(stream[, at, name, out])	Parse a RasterModelGrid from a ESRI ASCII format stream.
`loads`(s[, at, name, out])	Parse a RasterModelGrid from a ESRI ASCII formatted string.
`parse`()	Parse a ESRI ASCII formatted string.

exception BadHeaderError[source]¶

Bases: EsriAsciiError

__init__(msg)[source]¶

Parameters:: msg (str)
Return type:: None

__new__(**kwargs)¶

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception EsriAsciiError[source]¶

Bases: Exception

__init__(*args, **kwargs)¶

__new__(**kwargs)¶

add_note()¶: Exception.add_note(note) – add a note to the exception

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class RasterGridArgs[source]¶

Bases: NamedTuple

RasterGridArgs(shape, xy_spacing, xy_of_lower_left)

Create new instance of RasterGridArgs(shape, xy_spacing, xy_of_lower_left)

__init__()¶

static __new__(_cls, shape, xy_spacing, xy_of_lower_left)¶

Create new instance of RasterGridArgs(shape, xy_spacing, xy_of_lower_left)

Parameters:

shape (tuple[int, int])
xy_spacing (tuple[float, float])
xy_of_lower_left (tuple[float, float])

count(value, /)¶: Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)¶

Return first index of value.

Raises ValueError if the value is not present.

shape: tuple[int, int]¶: Alias for field number 0

xy_of_lower_left: tuple[float, float]¶: Alias for field number 2

xy_spacing: tuple[float, float]¶: Alias for field number 1

dump(grid, stream=None, at='node', name=None)[source]¶

Dump a grid field to ESRII ASCII format.

Parameters:

grid (RasterModelGrid) – A Landlab grid.
stream (TextIO | None) – A file_like object to write to. If None, return a string containing the serialized grid.
at (Literal['node', 'patch', 'corner', 'cell']) – Where the field to be written is located on the grid.
name (str | None) – The name of the field to be written. If None, only the header information will be written.

Returns:

The grid field in ESRI ASCII format or None if a file_like object was provided.

Return type:

str | None

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.io import esri_ascii

>>> grid = RasterModelGrid((3, 4), xy_spacing=2.0)
>>> print(esri_ascii.dump(grid, at="node"))
NROWS 3
NCOLS 4
CELLSIZE 2.0
XLLCENTER 0.0
YLLCENTER 0.0
NODATA_VALUE -9999

>>> print(esri_ascii.dump(grid, at="cell"))
NROWS 1
NCOLS 2
CELLSIZE 2.0
XLLCENTER 2.0
YLLCENTER 2.0
NODATA_VALUE -9999

lazy_load(stream: TextIO, at: str = 'node', name: None = None) → RasterGridArgs[source]¶

lazy_load(stream: TextIO, at: str = 'node', name: str = None) → tuple[RasterGridArgs, ndarray[Any, dtype[_ScalarType_co]]]

Parse a RasterModelGrid from a ESRI ASCII format stream.

Parameters:

stream (file_like) – A text stream in ESRI ASCII format.
at ({'node', 'patch', 'corner', 'cell'}, optional) – Location on the grid where data are placed.
name (str, optional) – Name of the newly-created field. If name is not provided, the grid will be created but the data not added as a field.

Returns:

RasterGridArgs – The header metadata
NDArray, optional – The data as a numpy array.

lazy_loads(s: str, at: str = 'node', name: None = None) → RasterGridArgs[source]¶

lazy_loads(s: str, at: str = 'node', name: str = None) → tuple[RasterGridArgs, ndarray[Any, dtype[_ScalarType_co]]]

Parse a ESRI ASCII formatted string.

Parameters:

s (str) – A string in ESRI ASCII format.
at ({'node', 'patch', 'corner', 'cell'}, optional) – Location on the grid where data are placed.
name (str, optional) – Name of the newly-created field. If name is not provided, the grid will be created but the data not added to the grid as a field.
out (RasterModelGrid, optional) – Place the data from the file onto an existing grid. If not provided, create a new grid.

Returns:

RasterGridArgs – The header metadata
NDArray, optional – The data as a numpy array.

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.io import esri_ascii

>>> contents = '''
... NROWS 1
... NCOLS 2
... XLLCORNER -2.0
... YLLCORNER 4.0
... CELLSIZE 2.0
... NODATA_VALUE -9999
... 10 20
... '''.lstrip()
>>> args, data = esri_ascii.lazy_loads(contents, at="cell", name="foo")
>>> args
RasterGridArgs(shape=(3, 4), xy_spacing=(2.0, 2.0), xy_of_lower_left=(-3.0, 3.0))
>>> data
array([10., 20.])

>>> grid = RasterModelGrid(*args)
>>> grid.at_cell["foo"] = data

>>> contents = '''
... NROWS 3
... NCOLS 4
... XLLCORNER -3.0
... YLLCORNER 3.0
... CELLSIZE 2.0
... NODATA_VALUE -9999
... 1 2 3 4
... 5 6 7 8
... 9 10 11 12
... '''.lstrip()
>>> args, data = esri_ascii.lazy_loads(contents, at="node", name="foo", out=grid)
>>> args
RasterGridArgs(shape=(3, 4), xy_spacing=(2.0, 2.0), xy_of_lower_left=(-3.0, 3.0))
>>> data
array([ 9., 10., 11., 12.,  5.,  6.,  7.,  8.,  1.,  2.,  3.,  4.])

>>> grid.at_cell["foo"]
array([10., 20.])
>>> grid.at_node["foo"]
array([ 9., 10., 11., 12.,  5.,  6.,  7.,  8.,  1.,  2.,  3.,  4.])

load(stream, at='node', name=None, out=None)[source]¶

Parse a RasterModelGrid from a ESRI ASCII format stream.

Parameters:

stream (file_like) – A text stream in ESRI ASCII format.
at ({'node', 'patch', 'corner', 'cell'}, optional) – Location on the grid where data are placed.
name (str, optional) – Name of the newly-created field. If name is not provided, the grid will be created but the data not added as a field.
out (RasterModelGrid, optional) – Place the data from the file onto an existing grid. If not provided, create a new grid.

Returns:

A newly-created RasterModelGrid with, optionaly, the data added as a field (if name was provided).

Return type:

RasterModelGrid

loads(s, at='node', name=None, out=None)[source]¶

Parse a RasterModelGrid from a ESRI ASCII formatted string.

Parameters:

s (str) – A string in ESRI ASCII format.
at ({'node', 'patch', 'corner', 'cell'}, optional) – Location on the grid where data are placed.
name (str, optional) – Name of the newly-created field. If name is not provided, the grid will be created but the data not added to the grid as a field.
out (RasterModelGrid, optional) – Place the data from the file onto an existing grid. If not provided, create a new grid.

Returns:

A newly-created RasterModelGrid with, optionaly, the data added as a field (if name was provided).

Return type:

RasterModelGrid

Examples

>>> from landlab.io import esri_ascii

>>> contents = '''
... NROWS 1
... NCOLS 2
... XLLCORNER -2.0
... YLLCORNER 4.0
... CELLSIZE 2.0
... NODATA_VALUE -9999
... '''.lstrip()
>>> grid = esri_ascii.loads(contents, at="cell")
>>> grid.shape
(3, 4)
>>> grid.xy_of_lower_left
(-3.0, 3.0)
>>> grid.spacing
(2.0, 2.0)

>>> contents = '''
... NROWS 1
... NCOLS 2
... XLLCENTER -2.0
... YLLCENTER 4.0
... CELLSIZE 2.0
... NODATA_VALUE -9999
... 10 11
... '''.lstrip()
>>> grid = esri_ascii.loads(contents, at="cell", name="foo")
>>> grid.shape
(3, 4)
>>> grid.xy_of_lower_left
(-4.0, 2.0)
>>> grid.spacing
(2.0, 2.0)
>>> grid.at_cell["foo"]
array([10., 11.])

>>> contents = '''
... NROWS 3
... NCOLS 4
... XLLCENTER 0.0
... YLLCENTER 0.0
... CELLSIZE 1.0
... NODATA_VALUE -9999
... 1 2 3 4
... 5 6 7 8
... 9 10 11 12
... '''.lstrip()
>>> grid = esri_ascii.loads(contents, at="node", name="foo")
>>> contents = '''
... NROWS 1
... NCOLS 2
... XLLCENTER 1.0
... YLLCENTER 1.0
... CELLSIZE 1.0
... NODATA_VALUE -9999
... 10 20
... '''.lstrip()
>>> grid = esri_ascii.loads(contents, at="cell", name="foo", out=grid)
>>> grid.at_node["foo"].reshape(grid.shape)
array([[ 9., 10., 11., 12.],
       [ 5.,  6.,  7.,  8.],
       [ 1.,  2.,  3.,  4.]])
>>> grid.at_cell["foo"]
array([10., 20.])

parse(s: str, with_data: Literal[False] = False) → dict[str, int | float][source]¶

parse(s: str, with_data: Literal[True] = False) → tuple[dict[str, int | float], ndarray[Any, dtype[_ScalarType_co]]]

Parse a ESRI ASCII formatted string.

Parameters:

s (str) – String to parse.
with_data (bool, optional) – Return the data as a numpy array, otherwise, just return the header.

Returns:

The header metadata and, optionally, the data.

Return type:

dict or tuple of (dict, ndarray)

Examples

>>> from landlab.io import esri_ascii

>>> contents = '''
... NROWS 2
... NCOLS 3
... XLLCORNER -2.0
... YLLCORNER 4.0
... CELLSIZE 2.0
... NODATA_VALUE -9999
... 10 20 30
... 40 50 60
... '''.lstrip()
>>> list(esri_ascii.parse(contents).items())
[('nrows', 2),
 ('ncols', 3),
 ('xllcorner', -2.0),
 ('yllcorner', 4.0),
 ('cellsize', 2.0),
 ('nodata_value', -9999.0)]

>>> info, data = esri_ascii.parse(contents, with_data=True)
>>> data
array([40., 50., 60., 10., 20., 30.])