landlab.io package¶

Subpackages¶

Submodules¶

landlab.io.esri_ascii module¶

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: landlab.io.esri_ascii.Error

Raise this error for a bad header is line.

exception DataSizeError(size, expected_size)[source]¶

Bases: landlab.io.esri_ascii.Error

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

exception Error[source]¶

Bases: exceptions.Exception

Base class for errors in this module.

exception KeyTypeError(key, expected_type)[source]¶

Bases: landlab.io.esri_ascii.Error

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

exception KeyValueError(key, message)[source]¶

Bases: landlab.io.esri_ascii.Error

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

exception MismatchGridDataSizeError(size, expected_size)[source]¶

Bases: landlab.io.esri_ascii.Error

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

exception MissingRequiredKeyError(key)[source]¶

Bases: landlab.io.esri_ascii.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:

dict

Header as key-value pairs.

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 six import StringIO
>>> from landlab.io.esri_ascii import read_asc_header
>>> contents = StringIO('''
...     nrows 100
...     ncols 200
...     cellsize 1.5
...     xllcenter 0.5
...     yllcenter -0.5
... ''')
>>> hdr = read_asc_header(contents)
>>> 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
... ''')
>>> read_asc_header(contents) 
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
... ''')
>>> read_asc_header(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) : tuple

A newly-created RasterModel grid and the associated node data.

Raises:

DataSizeError

Data are not the same size as indicated by the header file.

MismatchGridDataSizeError

If a grid is passed, the size of the grid does not agree with the size of the data.

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

>>> grid = RasterModelGrid((4, 5), spacing=(2., 2.))
>>> _ = grid.add_field('node', 'air__temperature', np.arange(20.))
>>> with cdtemp() as _:
...     files = write_esri_ascii('test.asc', grid)
>>> files
['test.asc']

>>> _ = grid.add_field('node', 'land_surface__elevation', np.arange(20.))
>>> with cdtemp() as _:
...     files = write_esri_ascii('test.asc', grid)
>>> files.sort()
>>> files
['test_air__temperature.asc', 'test_land_surface__elevation.asc']

landlab.io.native_landlab module¶

Read data from a pickled Landlab grid file into a RasterModelGrid.

Read Landlab native¶

`load_grid`(path)	Load a grid and its fields from a Landlab “native” format.
`save_grid`(grid, path[, clobber])	Save a grid and fields to a Landlab “native” format.

load_grid(path)[source]¶

Load a grid and its fields from a Landlab “native” format.

This method uses cPickle to load a saved grid. It assumes you saved using vmg.save() or save_grid, i.e., that the pickle file is a .grid file.

Caution: Pickling can be slow, and can produce very large files. Caution 2: Future updates to Landlab could potentially render old saves unloadable.

Parameters:

path : str

Path to output file, either without suffix, or ‘.grid’

Examples

>>> from landlab import VoronoiDelaunayGrid
>>> from landlab.io.native_landlab import load_grid, save_grid
>>> import numpy as np
>>> import os
>>> x = np.random.rand(20)
>>> y = np.random.rand(20)
>>> grid_out = VoronoiDelaunayGrid(x, y)
>>> save_grid(grid_out, 'testsavedgrid.grid', clobber=True)
>>> grid_in = load_grid('testsavedgrid.grid')
>>> os.remove('testsavedgrid.grid') #to remove traces of this test

save_grid(grid, path, clobber=False)[source]¶

Save a grid and fields to a Landlab “native” format.

This method uses cPickle to save a grid as a cPickle file. All fields will be saved, along with the grid.

The recommended suffix for the save file is ‘.grid’. This will be added to your save if you don’t include it.

Caution: Pickling can be slow, and can produce very large files. Caution 2: Future updates to Landlab could potentially render old saves unloadable.

Parameters:

grid : object of subclass ModelGrid

Grid object to save

path : str

Path to output file, either without suffix, or ‘.grid’

clobber : bool (default False)

Set to True to allow overwrites of existing files

Examples

>>> from landlab import RasterModelGrid
>>> from landlab.io.native_landlab import save_grid
>>> import os
>>> grid_out = RasterModelGrid(4,5,2.)
>>> save_grid(grid_out, 'testsavedgrid.grid', clobber=True)
>>> os.remove('testsavedgrid.grid') #to remove traces of this test

Module contents¶

Modules that read/write ModelGrids from various file formats.

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) : tuple

A newly-created RasterModel grid and the associated node data.

Raises:

DataSizeError

Data are not the same size as indicated by the header file.

MismatchGridDataSizeError

If a grid is passed, the size of the grid does not agree with the size of the data.

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]

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:

dict

Header as key-value pairs.

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 six import StringIO
>>> from landlab.io.esri_ascii import read_asc_header
>>> contents = StringIO('''
...     nrows 100
...     ncols 200
...     cellsize 1.5
...     xllcenter 0.5
...     yllcenter -0.5
... ''')
>>> hdr = read_asc_header(contents)
>>> 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
... ''')
>>> read_asc_header(contents) 
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
... ''')
>>> read_asc_header(contents) 
Traceback (most recent call last):
KeyTypeError: Unable to convert nrows to <type 'int'>

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

>>> grid = RasterModelGrid((4, 5), spacing=(2., 2.))
>>> _ = grid.add_field('node', 'air__temperature', np.arange(20.))
>>> with cdtemp() as _:
...     files = write_esri_ascii('test.asc', grid)
>>> files
['test.asc']

>>> _ = grid.add_field('node', 'land_surface__elevation', np.arange(20.))
>>> with cdtemp() as _:
...     files = write_esri_ascii('test.asc', grid)
>>> files.sort()
>>> files
['test_air__temperature.asc', 'test_land_surface__elevation.asc']