landlab.utils.jaggedarray module#

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([row0, row1, ...]) JaggedArray(values, values_per_row)[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])

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])
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