landlab

landlab.plot package

Submodules

landlab.plot.imshow module

Methods to plot data defined on Landlab grids.

Plotting functions

imshow_grid(grid, values[, plot_name, …]) Prepare a map view of data over all nodes or cells in the grid.
imshow_grid_at_cell(grid, values[, …]) Map view of grid data over all grid cells.
imshow_grid_at_node(grid, values[, …]) Prepare a map view of data over all nodes in the grid.
imshow_cell_grid(*args, **kwargs)[source]

Note

This method is deprecated as of Landlab version 0.5.

Use imshow_grid_at_cell() instead.

imshow_grid(grid, values, plot_name=None, var_name=None, var_units=None, grid_units=None, symmetric_cbar=False, cmap='pink', limits=(values.min(), values.max()), vmin=values.min(), vmax=values.max(), allow_colorbar=True, colorbar_label=None, norm=[linear], shrink=1., color_for_closed='black', color_for_background=None, show_elements=False)[source]

Prepare a map view of data over all nodes or cells in the grid.

Data is plotted as colored cells. If at=’node’, the surrounding cell is shaded with the value at the node at its center. If at=’cell’, the cell is shaded with its own value. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (default black, overridden with kwd ‘color_for_closed’); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries will be treated as if they were Landlab CLOSED_BOUNDARYs. Used together with the color_for_closed=None keyword (i.e., “transparent”), this can allow for construction of overlay layers in a figure (e.g., only defining values in a river network, and overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshow_grid(), as desired.

This function happily works with both regular and irregular grids.

Parameters:

grid : ModelGrid

Grid containing the field to plot, or describing the geometry of the provided array.

values : array_like, masked_array, or str

Node or cell values, or a field name as a string from which to draw the data.

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

Tells plotter where values are defined.

plot_name : str, optional

String to put as the plot title.

var_name : str, optional

Variable name, to use as a colorbar label.

var_units : str, optional

Units for the variable being plotted, for the colorbar.

grid_units : tuple of str, optional

Units for y, and x dimensions. If None, component will look to the gri property axis_units for this information. If no units are specified there, no entry is made.

symmetric_cbar : bool

Make the colormap symetric about 0.

cmap : str

Name of a colormap

limits : tuple of float

Minimum and maximum of the colorbar.

vmin, vmax: floats

Alternatives to limits.

allow_colorbar : bool

If True, include the colorbar.

colorbar_label : str or None

The string with which to label the colorbar.

norm : matplotlib.colors.Normalize

The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

shrink : float

Fraction by which to shrink the colorbar.

color_for_closed : str or None

Color to use for closed elements (default ‘black’). If None, closed (or masked) elements will be transparent.

color_for_background : color str or other color declaration, or None

Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

show_elements : bool

If True, and grid is a Voronoi, the faces will be plotted in black along with just the colour of the cell, defining the cell outlines (defaults False).

output : None, string, or bool

If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a string, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

imshow_grid_at_cell(grid, values, plot_name=None, var_name=None, var_units=None, grid_units=None, symmetric_cbar=False, cmap='pink', limits=(values.min(), values.max()), vmin=values.min(), vmax=values.max(), allow_colorbar=True, colorbar_label=None, norm=[linear], shrink=1., color_for_closed='black', color_for_background=None, show_elements=False, output=None)[source]

Map view of grid data over all grid cells.

Prepares a map view of data over all cells in the grid. Method can take any of the same **kwds as imshow_grid_at_node().

Parameters:

grid : ModelGrid

Grid containing the field to plot, or describing the geometry of the provided array.

values : array_like, masked_array, or str

Values at the cells on the grid. Alternatively, can be a field name (string) from which to draw the data from the grid.

plot_name : str, optional

String to put as the plot title.

var_name : str, optional

Variable name, to use as a colorbar label.

var_units : str, optional

Units for the variable being plotted, for the colorbar.

grid_units : tuple of str, optional

Units for y, and x dimensions. If None, component will look to the gri property axis_units for this information. If no units are specified there, no entry is made.

symmetric_cbar : bool

Make the colormap symetric about 0.

cmap : str

Name of a colormap

limits : tuple of float

Minimum and maximum of the colorbar.

vmin, vmax: floats

Alternatives to limits.

allow_colorbar : bool

If True, include the colorbar.

colorbar_label : str or None

The string with which to label the colorbar.

norm : matplotlib.colors.Normalize

The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

shrink : float

Fraction by which to shrink the colorbar.

color_for_closed : str or None

Color to use for closed elements (default ‘black’). If None, closed (or masked) elements will be transparent.

color_for_background : color str or other color declaration, or None

Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

show_elements : bool

If True, and grid is a Voronoi, the faces will be plotted in black along with just the colour of the cell, defining the cell outlines (defaults False).

output : None, string, or bool

If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a string, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

Raises:

ValueError

If input grid is not uniform rectilinear.

imshow_grid_at_node(grid, values, plot_name=None, var_name=None, var_units=None, grid_units=None, symmetric_cbar=False, cmap='pink', limits=(values.min(), values.max()), vmin=values.min(), vmax=values.max(), allow_colorbar=True, norm=[linear], shrink=1., color_for_closed='black', color_for_background=None, show_elements=False, output=None)[source]

Prepare a map view of data over all nodes in the grid.

Data is plotted as cells shaded with the value at the node at its center. Outer edges of perimeter cells are extrapolated. Closed elements are colored uniformly (default black, overridden with kwd ‘color_for_closed’); other open boundary nodes get their actual values.

values can be a field name, a regular array, or a masked array. If a masked array is provided, masked entries will be treated as if they were Landlab CLOSED_BOUNDARYs. Used together with the color_at_closed=None keyword (i.e., “transparent”), this can allow for construction of overlay layers in a figure (e.g., only defining values in a river network, and overlaying it on another landscape).

Use matplotlib functions like xlim, ylim to modify your plot after calling imshow_grid(), as desired.

Node coordinates are printed when a mouse button is pressed on a cell in the plot.

This function happily works with both regular and irregular grids.

Parameters:

grid : ModelGrid

Grid containing the field to plot, or describing the geometry of the provided array.

values : array_like, masked_array, or str

Node values, or a field name as a string from which to draw the data.

plot_name : str, optional

String to put as the plot title.

var_name : str, optional

Variable name, to use as a colorbar label.

var_units : str, optional

Units for the variable being plotted, for the colorbar.

grid_units : tuple of str, optional

Units for y, and x dimensions. If None, component will look to the gri property axis_units for this information. If no units are specified there, no entry is made.

symmetric_cbar : bool

Make the colormap symetric about 0.

cmap : str

Name of a colormap

limits : tuple of float

Minimum and maximum of the colorbar.

vmin, vmax: floats

Alternatives to limits.

allow_colorbar : bool

If True, include the colorbar.

colorbar_label : str or None

The string with which to label the colorbar.

norm : matplotlib.colors.Normalize

The normalizing object which scales data, typically into the interval [0, 1]. Ignore in most cases.

shrink : float

Fraction by which to shrink the colorbar.

color_for_closed : str or None

Color to use for closed nodes (default ‘black’). If None, closed (or masked) nodes will be transparent.

color_for_background : color str or other color declaration, or None

Color to use for closed elements (default None). If None, the background will be transparent, and appear white.

show_elements : bool

If True, and grid is a Voronoi, the faces will be plotted in black along with just the colour of the cell, defining the cell outlines (defaults False).

output : None, string, or bool

If None (or False), the image is sent to the imaging buffer to await an explicit call to show() or savefig() from outside this function. If a string, the string should be the path to a save location, and the filename (with file extension). The function will then call plt.savefig([string]) itself. If True, the function will call plt.show() itself once plotting is complete.

imshow_node_grid(*args, **kwargs)[source]

Note

This method is deprecated as of Landlab version 0.5.

Use imshow_grid_at_node() instead.

landlab.plot.channel_profile module

Extract and plot channel long profiles.

Plotting functions to extract and plot channel long profiles.

Two options for use are available. For an integrated single-line call, use analyze_channel_network_and_plot(). This function wraps the other three functions and allows a single-line call to plot long profiles. First it uses channel_nodes to get the nodes belonging to the channels. Then it uses get_distances_upstream to get distances upstream. Finally it uses plot_profiles to make a plot.

You can specify how many differents stream networks it handles using the number_of_channels parameter in the channel_nodes function (default is 1). The specific node ids for the beginning of the chanel can be passed with the keyword argument starting_nodes. If it is not specified, then the stream networks(s) will be chosed based on largest terminal drainage area.

Two options exist for controlling which channels within a given stream network are plotted. Set main_channel_only = True (default) to plot only the largest drainage leading that network’s outlet node. main_channel_only = False will plot all channels within each network with drainage below the threshold value (default = 2 * grid cell area).

The functions will return the profile datastructure profile_structure and the distance upstream datastructure distances_upstream. rofile structure is a list of length number_of_channels. Each element of profile_structure is itself a list of length number of stream segments that drain to each of the starting nodes. Each stream segment list contains the node ids of a stream segment from downstream to upstream. distances_upstream provides the equivalent structure but provides the distance upstream rather than the node id.

Examples

Start by importing necessary modules

>>> import numpy as np
>>> np.random.seed(42)
>>> from landlab import RasterModelGrid
>>> from landlab.components import FlowAccumulator, FastscapeEroder
>>> from landlab.plot import analyze_channel_network_and_plot

Construct a grid and evolve some topography

>>> mg = RasterModelGrid(40, 60)
>>> z = mg.add_zeros('topographic__elevation', at='node')
>>> z += 200 + mg.x_of_node + mg.y_of_node
>>> mg.set_closed_boundaries_at_grid_edges(bottom_is_closed=True, left_is_closed=True, right_is_closed=True, top_is_closed=True)
>>> mg.set_watershed_boundary_condition_outlet_id(0, z, -9999)
>>> fa = FlowAccumulator(mg, flow_director='D8')
>>> sp = FastscapeEroder(mg, K_sp=.0001, m_sp=.5, n_sp=1)

Now run a simple landscape evolution model to develop a channel network.

>>> dt = 100
>>> for i in range(200):
...     fa.run_one_step()
...     sp.run_one_step(dt=dt)
...     mg.at_node['topographic__elevation'][0] -= 0.001

Now call analyze_channel_network_and_plot in order to plot the network. Note in general, we’d leave create_plot in its default value of create_plot=True, but we can’t plot in the docstring

>>> profile_structure, distances_upstream = analyze_channel_network_and_plot(mg,
...                                                                          create_plot=False)

This creates the profile structure and distances upstream structure. Since we used the default values this will make only one profile, the biggest channel in the biggest stream network in the catchemnt.

profile_structure will be a length 1 array and will contain one array that is the length in number of nodes of the single longest channel

>>> len(profile_structure) == 1
True
>>> len(profile_structure[0][0])
58

We can change the default values to get additional channels or to plot all of the channels in a network.

For the next example, lets use a hexagonal grid.

>>> from landlab import HexModelGrid
>>> from landlab.components import DepressionFinderAndRouter, LinearDiffuser
>>> mg = HexModelGrid(40, 20)
>>> z = mg.add_zeros('topographic__elevation', at='node')
>>> z += 200 + mg.x_of_node + mg.y_of_node + np.random.randn(mg.size('node'))
>>> fa = FlowAccumulator(mg, depression_finder=DepressionFinderAndRouter)
>>> sp = FastscapeEroder(mg, K_sp=.0001, m_sp=.5, n_sp=1)
>>> ld = LinearDiffuser(mg, linear_diffusivity=0.0001)

Now run a simple landscape evolution model to develop a channel network.

>>> dt = 100
>>> for i in range(200):
...     fa.run_one_step()
...     flooded = np.where(fa.depression_finder.flood_status==3)[0]
...     sp.run_one_step(dt=dt,  flooded_nodes=flooded)
...     ld.run_one_step(dt=dt)
...     mg.at_node['topographic__elevation'][0] -= 0.001

This time we will use some non-default values. Providing the threshold in units of area indicates where the channel network will end. main_channel_only = False indicates that all parts of the stream network >>> profile_structure, distances_upstream = analyze_channel_network_and_plot(mg, … threshold = 100, … main_channel_only=False, … number_of_channels=3)

This will create four channel networks. The datastructures profile_structure and distances_upstream will both be length 3

>>> len(profile_structure) == len(distances_upstream) == 3
True

We can also specify exactly which node is the outlet for the channel.

>>> profile_structure, distances_upstream = analyze_channel_network_and_plot(mg,
...                                                                          threshold = 100,
...                                                                          starting_nodes = [0],
...                                                                          number_of_channels=1)

It is important that the length of starting nodes is the same as the value of number_of_channels. If this is not the case, then an error will occur.

analyze_channel_network_and_plot(grid, field='topographic__elevation', drainage_area='drainage_area', flow_receiver='flow__receiver_node', links_to_flow_receiver='flow__link_to_receiver_node', number_of_channels=1, main_channel_only=True, starting_nodes=None, threshold=None, create_plot=True)[source]

Main function to analyse the channel network and make an distance upstream vs the quantity stored at the model grid field give by the keyword argument field.

This function wraps the other three present here, and allows a single-line call to plot long profiles. First it uses channel_nodes to get the nodes belonging to the channels. Then it uses get_distances_upstream to get distances upstream. Finally it uses plot_profiles to make a plot.

Parameters:

grid : Landlab Model Grid instance, required

field : string or length nnode array, optional

Field name or array of the quantity to plot against distance upstream. Default value is ‘topographic__elevation’.

drainage_area : string or length nnode array, optional

Field name or array of the drainage area of the model grid. This field is used to identify the boundary nodes with the largest terminal drainage area and to identify the end of channels using the threshold parameter. Default value is ‘drainage_area’ which will be created by Landlab’s FlowAccumulator or FlowRouter.

flow_receiver : string or length nnode array, optional

Field name or array of the flow_links to reciever node of the model grid. Default value is ‘flow__receiver_node’ which will be created by Landlab’s FlowAccumulator or FlowRouter.

links_to_flow_receiver : string or length nnode array, optional

Field name or array of the flow_links to reciever node of the model grid. Default value is ‘flow__link_to_receiver_node’ which will be created by Landlab’s FlowAccumulator or FlowRouter.

number_of_channels : int, optional

Total number of channels to plot. Default value is 1. If value is greater than 1 and starting_nodes is not specified, then the number_of_channels largest channels based on terminal drainage area will be used.

main_channel_only : Boolean, optional

Flag to determine if only the main channel should be plotted, or if all stream segments with drainage area less than threshold should be plotted. Default value is True.

starting_nodes : length number_of_channels itterable, optional

Length number_of_channels itterable containing the node IDs of nodes to start the channel profiles from. If not provided, the default is the number_of_channels node IDs on the model grid boundary with the largest terminal drainage area

threshold : float, optional

Value to use for the minimum drainage area associated with a plotted channel segment. Default values is 2.0 x minimum grid cell area.

create_plot : boolean, optional

Flag to indicate if a distance-upstream vs plotted quantity plot should be created. Default is True.

Returns:

tuple, containing:

profile_structure, the channel segment datastructure.

profile structure is a list of length number_of_channels. Each element of profile_structure is itself a list of length number of stream segments that drain to each of the starting nodes. Each stream segment list contains the node ids of a stream segment from downstream to upstream.

distances_upstream, the channel segment datastructure.

A datastructure that parallels profile_structure but holds distances upstream instead of node IDs.

Both lists are number_of_channels long.

channel_nodes(grid, starting_nodes, drainage_area, flow_receiver, number_of_channels=1, threshold=None, main_channel_only=True)[source]

Create the profile_IDs data structure for channel network.

Parameters:

grid : Landlab Model Grid instance, required

starting_nodes : length number_of_channels itterable, optional

Length number_of_channels itterable containing the node IDs of nodes to start the channel profiles from. If not provided, the default is the number_of_channels node IDs on the model grid boundary with the largest terminal drainage area

drainage_area : nnode array, required

Node id array of drainage area at node

flow_receiver : nnode array, required

Node id array of flow recievers at node.

number_of_channels : int, optional

Total number of channels to plot. Default value is 1. If value is greater than 1 and starting_nodes is not specified, then the number_of_channels largest channels based on terminal drainage area will be used.

threshold : float, optional

Value to use for the minimum drainage area associated with a plotted channel segment. Default values is 2.0 x minimum grid cell area.

main_channel_only : Boolean, optional

Flag to determine if only the main channel should be plotted, or if all stream segments with drainage area less than threshold should be plotted. Default value is True.

Returns:

profile_structure, the channel segment datastructure.

profile structure is a list of length number_of_channels. Each element of profile_structure is itself a list of length number of stream segments that drain to each of the starting nodes. Each stream segment list contains the node ids of a stream segment from downstream to upstream.

get_distances_upstream(grid, profile_structure, links_to_flow_receiver)[source]

Get distances upstream for the profile_IDs datastructure.

Parameters:

grid : model grid instance, required

length of node arrays

profile_structure: profile_structure datastructure

links_to_flow_receiver: nnode array, link id of the flow link to reciever

node.

Returns:

distances_upstream, datastruture that mirrors profile IDs but provides the

distance upstream.

plot_channels_in_map_view(grid, profile_structure, field='topographic__elevation', **kwargs)[source]

Plot channel locations in map view on a frame.

Parameters:

grid, model grid instance.

field, name or nnode long array to plot with imshow_grid

profile_IDs: profile_IDs datastructure

**kwargs: additional parameters to pass to imshow_grid

plot_profiles(distances_upstream, profile_structure, quantity)[source]

Plot distance-upstream vs arbitrary quantity, default when calling through analyze_channel_network_and_plot is topographic_elevation.

Parameters:

distances_upstream : datastructure, required

The distances upstream datastructure created by get_distances_upstream

profile_structure : datastructure, required

profile_structure datastructure created by channel_nodes

quantity : nnode array, required

Array of the at-node-quantity to plot against distance upstream.

landlab.plot.colors module

colors.py

Created on Mon Jan 18 13:28:17 2016

@author: gtucker

colormap(name)[source]

Return named Landlab colormap as a matplotlib colormap.

Parameters:

name : str

Name of colormap

Currently available maps are:

‘water’: black to light blue ‘earth’: dark olive to light sand color

earth_colormap()[source]

Return matplotlib colormap with ‘earth’ theme.

water_colormap()[source]

Return matplotlib colormap with ‘water’ theme.

Module contents