landlab.components.profiler.profiler¶

profiler.py component to create profiles with user-defined endpoints.

class Profiler[source]¶

Bases: _BaseProfiler

Extract and plot profiles set up using points within a grid.

The profile is constructed from the first to final point in endpoints. Endpoints are located at grid nodes. Two successive endpoints bound a profile segment. A profile with one segment is a straight line. The segments of a profile with multiple segments meet at endpoints. The grid nodes along the profile are sampled, including the segment endpoints. The extracted quantity of the node is retained. No interpolation is conducted even for profile traces that reside between nodes.

The structure of the profile in a model grid is diagrammed below. The grid contains nine columns and nine rows. The profile is constructed from three endpoints that bound two segments. Here, o indicates a segment endpoint, . and * are sample nodes of the first and second segment, respectively. X are nodes not included in the profile. The first segment begins in the lower-left and continues horizontally and almost reaches the right boundary. The second segment is joined to the first in the lower-right of the grid and it continues diagonally to the upper-left. Segments have seven sample points each (nodes at endpoints are also sampled). The segments share the second endpoint. Segment and sample ordering is dictated by the ordering of endpoints. If the horizontal segment is the first segment, the endpoints used to construct this profile must be ordered: lower-left, lower-right, and then upper-left.:

X X X X X X X X X
X o X X X X X X X
X X * X X X X X X
X X X * X X X X X
X X X X * X X X X
X X X X X * X X X
X X X X X X * X X
X o . . . . . o X
X X X X X X X X X

The node IDs and distances along the profile are stored in a data structure called data_structure. It is a dictionary with keys indicating the segment IDs that are enumerated along the profile.

By default, a unique color will be assigned to each segment. To change the color, a user can change values stored in data_structure. Additionally, a cmap keyword argument can provide some user control over the color at the instantiation of the component.

The data structure of the example above will look as follows:

{
    0: {
        "ids": [10, 11, 12, 13, 14, 15, 16],
        "distances": [0, 1, 2, 3, 4, 5, 6],
        "color": (0.27, 0, 0.33, 1),
    },
    1: {
        "ids": [16, 24, 32, 40, 48, 56, 64],
        "distances": [6, 7.41, 8.83, 10.24, 11.66, 13.07, 14.49],
        "color": (0.13, 0.57, 0.55, 1),
    },
}

Examples

Create a model grid with the same dimensions as the diagram above.

>>> from landlab import RasterModelGrid
>>> from landlab.components import Profiler
>>> import numpy as np
>>> mg = RasterModelGrid((10, 10), 10)
>>> mg.at_node["topographic__elevation"] = mg.node_x * mg.node_y

Create a profile with three endpoints. This profile is laid out the same as the diagram above.

>>> endpoints = [10, 16, 64]
>>> profiler = Profiler(mg, endpoints)
>>> profiler.run_one_step()

The keys of the data structure are the segment ids.

>>> profiler.data_structure.keys()
odict_keys([0, 1])

The data structure contains data of segment samples. Below is the first segment.

>>> profiler.data_structure[0]["ids"]
array([10, 11, 12, 13, 14, 15, 16])
>>> profiler.data_structure[0]["distances"]
array([ 0., 10., 20., 30., 40., 50., 60.])
>>> np.round(profiler.data_structure[0]["color"], decimals=2)
array([0.27, 0.  , 0.33, 1.  ])

Note that the first node of the second segment is the same as the final node of the first segment.

>>> profiler.data_structure[1]["ids"]
array([16, 26, 35, 45, 54, 64])

Alternative to nodes, profiles can be instantiated with coordinates.

>>> profiler = Profiler(mg, [(10, 10), (70, 10), (10, 70)])

Endpoints can also be set with a combination of coordinates and nodes.

>>> profiler = Profiler(mg, [(10, 10), 16, (10, 70)])

References

Required Software Citation(s) Specific to this Component

None Listed

Additional References

None Listed

Instantiate Profiler.

Parameters:

grid (RasterModelGrid) – A landlab RasterModelGrid.
endpoints (list of node id integers or coordinate tuples) – The endpoints that bound segments of the profile. Endpoints can be node ids and/or tuples of coordinates (x, y, where these coordinates are the measurement from the grid lower-left). The list can be a mix of node ids and coordinate tuples. The profile begins with the first element of endpoints and continues in the order of this list.
cmap (str) – A valid matplotlib cmap string. Default is “viridis”.

__init__(grid, endpoints, cmap='viridis')[source]¶

Instantiate Profiler.

Parameters:

grid (RasterModelGrid) – A landlab RasterModelGrid.
endpoints (list of node id integers or coordinate tuples) – The endpoints that bound segments of the profile. Endpoints can be node ids and/or tuples of coordinates (x, y, where these coordinates are the measurement from the grid lower-left). The list can be a mix of node ids and coordinate tuples. The profile begins with the first element of endpoints and continues in the order of this list.
cmap (str) – A valid matplotlib cmap string. Default is “viridis”.

static __new__(cls, *args, **kwds)¶

cite_as = ''¶

property colors¶

List of colors for each segment.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import (
...     FastscapeEroder,
...     FlowAccumulator,
...     ChannelProfiler,
... )
>>> mg = RasterModelGrid((10, 10), xy_spacing=10)
>>> np.random.seed(42)
>>> z = mg.add_zeros("topographic__elevation", at="node")
>>> z[mg.core_nodes] += np.random.randn(mg.core_nodes.size)
>>> fa = FlowAccumulator(mg)
>>> sp = FastscapeEroder(mg, K_sp=0.0001)
>>> dt = 1000
>>> for i in range(200):
...     fa.run_one_step()
...     sp.run_one_step(dt=dt)
...     z[mg.core_nodes] += 0.001 * dt
...
>>> profiler = ChannelProfiler(mg)
>>> profiler.run_one_step()
>>> np.round(profiler.colors, decimals=2)
array([[0.27, 0.  , 0.33, 1.  ]])

property coords¶: Return the coordinates of nodes on grid attached to the component.

property current_time¶

Current time.

Some components may keep track of the current time. In this case, the current_time attribute is incremented. Otherwise it is set to None.

Return type:: current_time

property data_structure¶

OrderedDict defining the profile.

The node IDs and distances along the profile are stored in data_structure. It is a dictionary with keys of the segment ID. The value of each key is itself a dictionary of the segment attributes. First, ‘ids’ contains a list of the node IDs of segment samples ordered from the start to the end of the segment. It includes the endpoints. Second, ‘distances’ contains a list of along-profile distances that mirrors the list in ‘ids’. Finally, ‘color’ is an RGBA tuple indicating the color for the segment.

definitions = ()¶

property distance_along_profile¶

List of distances along profile for each segment.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import (
...     FastscapeEroder,
...     FlowAccumulator,
...     ChannelProfiler,
... )
>>> mg = RasterModelGrid((10, 10), xy_spacing=10)
>>> np.random.seed(42)
>>> z = mg.add_zeros("topographic__elevation", at="node")
>>> z[mg.core_nodes] += np.random.randn(mg.core_nodes.size)
>>> fa = FlowAccumulator(mg)
>>> sp = FastscapeEroder(mg, K_sp=0.0001)
>>> dt = 1000
>>> for i in range(200):
...     fa.run_one_step()
...     sp.run_one_step(dt=dt)
...     z[mg.core_nodes] += 0.001 * dt
...
>>> profiler = ChannelProfiler(mg)
>>> profiler.run_one_step()
>>> profiler.distance_along_profile
[array([  0.,  10.,  20.,  30.,  40.,  50.])]

classmethod from_path(grid, path)¶

Create a component from an input file.

Parameters:

grid (ModelGrid) – A landlab grid.
path (str or file_like) – Path to a parameter file, contents of a parameter file, or a file-like object.

Returns:

A newly-created component.

Return type:

Component

property grid¶: Return the grid attached to the component.

initialize_optional_output_fields()¶

Create fields for a component based on its optional field outputs, if declared in _optional_var_names.

This method will create new fields (without overwrite) for any fields output by the component as optional. New fields are initialized to zero. New fields are created as arrays of floats, unless the component also contains the specifying property _var_type.

initialize_output_fields(values_per_element=None)¶

Create fields for a component based on its input and output var names.

This method will create new fields (without overwrite) for any fields output by, but not supplied to, the component. New fields are initialized to zero. Ignores optional fields. New fields are created as arrays of floats, unless the component specifies the variable type.

Parameters:: values_per_element (int (optional)) – On occasion, it is necessary to create a field that is of size (n_grid_elements, values_per_element) instead of the default size (n_grid_elements,). Use this keyword argument to acomplish this task.

input_var_names = ()¶

name = 'Profiler'¶

property nodes¶

List of node ids for each segment.

Examples

>>> import numpy as np
>>> from landlab import RasterModelGrid
>>> from landlab.components import (
...     FastscapeEroder,
...     FlowAccumulator,
...     ChannelProfiler,
... )
>>> mg = RasterModelGrid((10, 10), xy_spacing=10)
>>> np.random.seed(42)
>>> z = mg.add_zeros("topographic__elevation", at="node")
>>> z[mg.core_nodes] += np.random.randn(mg.core_nodes.size)
>>> fa = FlowAccumulator(mg)
>>> sp = FastscapeEroder(mg, K_sp=0.0001)
>>> dt = 1000
>>> for i in range(200):
...     fa.run_one_step()
...     sp.run_one_step(dt=dt)
...     z[mg.core_nodes] += 0.001 * dt
...
>>> profiler = ChannelProfiler(mg)
>>> profiler.run_one_step()
>>> profiler.nodes
[array([59, 58, 57, 56, 46, 45])]

optional_var_names = ()¶

output_var_names = ()¶

plot_profiles(field='topographic__elevation', xlabel='Distance Along Profile', ylabel='Plotted Quantity', title='Extracted Profiles', color=None)¶

Plot distance-upstream vs at at-node or size (nnodes,) quantity.

Parameters:

field (field name or nnode array) – Array of the at-node-field to plot against distance upstream. Default value is the at-node field ‘topographic__elevation’.
xlabel (str, optional) – X-axis label, default is “Distance Along Profile”.
ylabel (str, optional) – Y-axis label, default value is “Plotted Quantity”.
title (str, optional) – Plot title, default value is “Extracted Profiles”.
color (RGBA tuple or color string) – Color to use in order to plot all profiles the same color. Default is None, and the colors assigned to each profile are used.

plot_profiles_in_map_view(field='topographic__elevation', endpoints_only=True, **kwds)[source]¶

Plot profile locations in map view.

This method overrides the method in _BaseProfiler to set the default of endpoints_only to True.

Parameters:

field (field name or nnode array) – Array of the at-node-field to plot as the 2D map values. Default value is the at-node field ‘topographic__elevation’.
endpoints_only (boolean) – Boolean where False indicates every node along the profile is plotted, or True (default) indicating only segment endpoints are plotted.
**kwds (dictionary) – Keyword arguments to pass to imshow_grid.

run_one_step()¶: Calculate the profile data structure and distances along it.

property shape¶: Return the grid shape attached to the component, if defined.

unit_agnostic = True¶

units = ()¶

classmethod var_definition(name)¶

Get a description of a particular field.

Parameters:: name (str) – A field name.
Returns:: A description of each field.
Return type:: tuple of (name, *description*)

classmethod var_help(name)¶

Print a help message for a particular field.

Parameters:: name (str) – A field name.

classmethod var_loc(name)¶

Location where a particular variable is defined.

Parameters:: name (str) – A field name.
Returns:: The location (‘node’, ‘link’, etc.) where a variable is defined.
Return type:: str

var_mapping = ()¶

classmethod var_type(name)¶

Returns the dtype of a field (float, int, bool, str…).

Parameters:: name (str) – A field name.
Returns:: The dtype of the field.
Return type:: dtype

classmethod var_units(name)¶

Get the units of a particular field.

Parameters:: name (str) – A field name.
Returns:: Units for the given field.
Return type:: str