landlab.utils.jaggedarray¶

The JaggedArray class to store arrays of variable-length arrays.

Examples

Create a JaggedArray that stores link IDs for the links attached to the nodes of a 3x3 grid.

>>> from landlab.utils.jaggedarray import JaggedArray
>>> links_at_node = JaggedArray(
...     [
...         [0, 6],
...         [1, 7, 0],
...         [8, 1],
...         [2, 9, 6],
...         [3, 10, 2, 7],
...         [11, 3, 8],
...         [4, 7],
...         [5, 10, 4],
...         [5, 11],
...     ]
... )

Make up some data that provides values at each of the links.

>>> value_at_link = np.arange(12, dtype=float)

Create another JaggedArray. Here we store the values at each of the links attached to nodes of the grid.

>>> values_at_node = JaggedArray.empty_like(links_at_node, dtype=float)
>>> values_at_node.array[:] = value_at_link[links_at_node.array]

Now operate on the link values for each node.

>>> values_at_node.foreach_row(sum)
array([  6.,   8.,   9.,  17.,  22.,  22.,  11.,  19.,  16.])
>>> values_at_node.foreach_row(min)
array([0.,  0.,  1.,  2.,  2.,  3.,  4.,  4.,  5.])
>>> values_at_node.foreach_row(np.ptp)
array([6.,  7.,  7.,  7.,  8.,  8.,  3.,  6.,  6.])

class JaggedArray[source]¶

Bases: object

A container for an array of variable-length arrays.

JaggedArray([row0, row1, …]) JaggedArray(values, values_per_row)

Examples

Create a JaggedArray with an array of arrays.

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.array
array([0, 1, 2, 3, 4])

Create a JaggedArray as a 1D array and a list or row lengths.

>>> x = JaggedArray([0, 1, 2, 3, 4], (3, 2))
>>> x.array
array([0, 1, 2, 3, 4])

JaggedArray([row0, row1, …]) JaggedArray(values, values_per_row)

Examples

Create a JaggedArray with an array of arrays.

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.array
array([0, 1, 2, 3, 4])

>>> x = JaggedArray([[0, 1, 2]])
>>> x.array
array([0, 1, 2])
>>> x.offset
array([0, 3])

Create a JaggedArray as a 1D array and a list or row lengths.

>>> x = JaggedArray([0, 1, 2, 3, 4], (3, 2))
>>> x.array
array([0, 1, 2, 3, 4])

__init__(*args)[source]¶

JaggedArray([row0, row1, …]) JaggedArray(values, values_per_row)

Examples

Create a JaggedArray with an array of arrays.

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.array
array([0, 1, 2, 3, 4])

>>> x = JaggedArray([[0, 1, 2]])
>>> x.array
array([0, 1, 2])
>>> x.offset
array([0, 3])

Create a JaggedArray as a 1D array and a list or row lengths.

>>> x = JaggedArray([0, 1, 2, 3, 4], (3, 2))
>>> x.array
array([0, 1, 2, 3, 4])

__iter__()[source]¶

Iterate over the rows of the array.

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> for row in x:
...     row
...
array([0, 1, 2])
array([3, 4])

__new__(**kwargs)¶

property array¶

The jagged array as a 1D array.

Returns:: A view of the underlying 1D array.
Return type:: array

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.array
array([0, 1, 2, 3, 4])

>>> x.array[0] = 1
>>> x.array
array([1, 1, 2, 3, 4])

static empty_like(jagged, dtype=None)[source]¶

Create a new JaggedArray that is like another one.

Parameters:

jagged (JaggedArray) – A JaggedArray to copy.
dtype (np.dtype) – The data type of the new JaggedArray.

Returns:

A new JaggedArray.

Return type:

JaggedArray

foreach_row(func, out=None)[source]¶

Apply an operator row-by-row.

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.foreach_row(sum)
array([3, 7])

>>> out = np.empty(2, dtype=int)
>>> x.foreach_row(sum, out=out) is out
True
>>> out
array([3, 7])

length_of_row(row)[source]¶

Number of values in a given row.

Parameters:: row (int) – Index to a row.
Returns:: Number of values in the row.
Return type:: int

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.length_of_row(0)
3
>>> x.length_of_row(1)
2

property number_of_rows¶

Number of array rows.

Returns:: Number of rows in the array.
Return type:: int

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.number_of_rows
2

property offset¶

The offsets to rows of a 1D array.

Returns:: Offsets into the underlying 1D array.
Return type:: array

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.offset
array([0, 3, 5])

From the offsets you can get values for rows of the jagged array.

>>> x.array[x.offset[0] : x.offset[1]]
array([0, 1, 2])

Once the array is created, you can’t change the offsets.

>>> x.offset[0] = 1
Traceback (most recent call last):
ValueError: assignment destination is read-only

row(row)[source]¶

Get the values of a row as an array.

Parameters:: row (int) – Index to a row.
Returns:: Values in the row as a slice of the underlying array.
Return type:: array

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.row(0)
array([0, 1, 2])
>>> x.row(1)
array([3, 4])

>>> y = x.row(0)
>>> y[0] = 1
>>> x.row(0)
array([1, 1, 2])

property size¶

Number of array elements.

Returns:: Number of values in the array.
Return type:: int

Examples

>>> from landlab.utils.jaggedarray import JaggedArray
>>> x = JaggedArray([[0, 1, 2], [3, 4]])
>>> x.size
5

flatten_jagged_array(jagged, dtype=None)[source]¶

Flatten a list of lists.

Parameters:: jagged (array_like of array_like) – An array of arrays of unequal length.
Returns:: (data, offset) – A tuple the data, as a flat numpy array, and offsets into that array for every item of the original list.
Return type:: (ndarray, ndarray of int)

Examples

>>> from landlab.utils.jaggedarray import flatten_jagged_array
>>> data, offset = flatten_jagged_array([[1, 2], [], [3, 4, 5]], dtype=int)
>>> data
array([1, 2, 3, 4, 5])
>>> offset
array([0, 2, 2, 5])

unravel(data, offset, out=None, pad=None)[source]¶

Unravel a jagged array.

Parameters:

data (ndarray) – Flattened-array of the data.
offset (ndarray of int) – Offsets to the start of rows of the jagged array.
out (ndarray) – Buffer into which to place the unravelled data.
pad (number) – Value to use to pad rows of the jagged array.

Returns:

Matrix that holds the unravelled jagged array.

Return type:

ndarray