sorted_array_utils module

Array utilities.

append_one_sample(x: ndarray | List, y: ndarray | List, make_periodic=False)

Add one sample to the end of time series.

Add one sample to x and y array. Newly added point x_i point is distant from the last point of x same as the last from the one before the last point. If make_periodic is False, newly added y_i point is the same as the last point of y. If make_periodic is True, newly added point is the same as the first point of y.

Parameters:

• x (1-D array-like of size n) – Independent variable in strictly increasing order.

• y (1-D array-like of size n) – Dependent variable.

• make_periodic (bool, default: False) – If false, append the last y point to y array. If true, append the first y point to y array.

Returns:

• ndarray – x, independent variable.

• ndarray – y, dependent variable.

Examples

>>> import numpy as np
>>> x = np.linspace(5, 15, 11)
>>> y = 2 * x
>>> res_x, res_y = append_one_sample(x, y, make_periodic=True)
>>> res_x[-1].item() == (2 * x[-1] - x[-2]).item()
True
>>> y[0].item() == res_y[-1].item()
True

oversample_linspace(a: ndarray, num: int)

Oversample array using linspace between each consecutive pair of array elements.

E.g., Array [1, 2, 3] oversampled by 2 becomes [1, 1.5, 2, 2.5, 3].

If input array is of size n, then resulting array is of size (n - 1) * num + 1.

If n is lower than 2, the original array is returned.

Parameters:

• a (1-D array) – Input array to oversample.

• num (int) – Number of elements inserted between each pair of array elements. Larger or equal to 2.

Returns:

1-D array containing num linspaced elements between each array elements’ pair. Its length is equal to (len(a) - 1) * num + 1

Return type:

ndarray

Examples

>>> import numpy as np
>>> from traffic_weaver.sorted_array_utils import oversample_linspace
>>> oversample_linspace(np.asarray([1, 2, 3]), 4).tolist()
[1.0, 1.25, 1.5, 1.75, 2.0, 2.25, 2.5, 2.75, 3.0]

oversample_piecewise_constant(a: ndarray, num: int)

Oversample array using same left value between each consecutive pair of array elements.

E.g., Array [1, 2, 3] oversampled by 2 becomes [1, 1, 2, 2, 3].

If input array is of size n, then resulting array is of size (n - 1) * num + 1.

If n is lower than 2, the original array is returned.

Parameters:

• a (1-D array) – Input array to oversample.

• num (int) – Number of elements inserted between each pair of array elements. Larger or equal to 2.

Returns:

1-D array containing num elements between each array elements’ pair. Its length is equal to (len(a) - 1) * num + 1

Return type:

ndarray

Examples

>>> import numpy as np
>>> from traffic_weaver.sorted_array_utils import oversample_piecewise_constant
>>> oversample_piecewise_constant(np.asarray([1.0, 2.0, 3.0]), 4).tolist()
[1.0, 1.0, 1.0, 1.0, 2.0, 2.0, 2.0, 2.0, 3.0]

extend_linspace(a: ndarray, n: int, direction='both', lstart: float = None, rstop: float = None)

Extends array using linspace with n elements.

Extends array a from left and/or right with n elements each side.

When extending to the left, the starting value is lstart (inclusive) and ending value as a[0] (exclusive). By default, lstart is a[0] - (a[n] - a[0]).

When extending to the right, the starting value a[-1] (exclusive) and ending value is rstop (inclusive). By default, rstop is a[-1] + (a[-1] - a[-1 - n])

direction determines whether to extend to both, left or right. By default, it is ‘both’.

Parameters:

• a (1-D array)

• n (int) – Number of elements to extend

• direction ('both', 'left' or 'right', default: 'both') – Direction in which array should be extended.

• lstart (float, optional) – Starting value of the left extension. By default, it is a[0] - (a[n] - a[0]).

• rstop (float, optional) – Ending value of the right extension. By default, it is a[-1] + (a[-1] - a[-1 - n]).

Returns:

1-D extended array.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from traffic_weaver.sorted_array_utils import extend_linspace
>>> a = np.array([1, 2, 3])
>>> extend_linspace(a, 2, direction='both').tolist()
[-1.0, 0.0, 1.0, 2.0, 3.0, 4.0, 5.0]

>>> extend_linspace(a, 4, direction='right', rstop=4).tolist()
[1.0, 2.0, 3.0, 3.25, 3.5, 3.75, 4.0]

extend_constant(a: ndarray, n: int, direction='both')

Extends array with first/last value with n elements.

Extends array a from left and/or right with n elements each side.

When extending to the left, value a[0] is repeated. When extending to the right, value a[-1] is repeated.

direction determines whether to extend to both, left or right. By default, it is ‘both’.

Parameters:

• a (1-D array)

• n (int) – Number of elements to extend

• direction ('both', 'left' or 'right', optional: 'both') – Direction in which array should be extended.

Returns:

1-D extended array.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from traffic_weaver.sorted_array_utils import extend_constant
>>> a = np.array([1, 2, 3])
>>> extend_constant(a, 2, direction='both').tolist()
[1, 1, 1, 2, 3, 3, 3]

rectangle_integral(x, y)

Integral values between each pair of points using rectangle approx.

In particular, if function contains average values, then it corresponds to the exact value of the integral.

Parameters:

• x (1-D array-like of size n) – Independent variable in strictly increasing order.

• y (1-D array-like of size n) – Dependent variable.

Returns:

Values of the integral.

Return type:

1-D array-like of size n-1

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 6)
>>> y = np.array([1, 3, 2, 4, 5, 6])
>>> rectangle_integral(x, y)
array([ 2.,  6.,  4.,  8., 10.])

trapezoid_integral(x, y)

Calculates integral between each pair of points using trapezoidal rule.

Parameters:

• x (1-D array-like of size n) – Independent variable in strictly increasing order.

• y (1-D array-like of size n) – Dependent variable.

Returns:

Values of the integral.

Return type:

1-D array-like of size n-1

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 6)
>>> y = np.array([1, 3, 2, 4, 5, 6])
>>> trapezoid_integral(x, y)
array([ 4.,  5.,  6.,  9., 11.])

integral(x, y, method: str = 'trapezoid')

Calculate integral y over range x according to provided method.

Parameters:

• n (1-D array-like of size) – Independent variable in strictly increasing order.

• y (1-D array-like of size n) – Dependent variable.

• method (str, default: 'trapezoid') – Method to calculate integral of target function. Available options: ‘trapezoid’, ‘rectangle’

Returns:

Values of the integral.

Return type:

1-D array-like of size n-1

find_closest_lower_equal_element_indices_to_values(x: ndarray | list, lookup: ndarray | list, fill_not_valid: bool = True)

Find indices of closest lower or equal element in x to each element in lookup.

Parameters:

• x (np.ndarray) – Array of values to search in.

• lookup (np.ndarray) – Values to search for.

• fill_not_valid (bool, default: True) – If True, fill indices of lookup values that are lower than the first element in ‘x’ with 0.

Returns:

Array of indices of closest lower or equal element in x to each element in lookup.

Return type:

np.ndarray

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 11)
>>> lookup = np.array([-1, 1.1, 3.3, 9, 10.2])
>>> find_closest_lower_equal_element_indices_to_values(x, lookup, fill_not_valid=True)
array([ 0,  1,  3,  9, 10])

find_closest_higher_equal_element_indices_to_values(x: ndarray | list, lookup: ndarray | list, fill_not_valid: bool = True)

Find indices of closest higher or equal element in x to each element in lookup.

Parameters:

• x (np.ndarray) – Array of values to search in.

• lookup (np.ndarray) – Values to search for.

• fill_not_valid (bool, default: True) – If True, fill indices of lookup values that are higher than the last element in ‘x’ with ‘len(x) - 1’.

Returns:

Array of indices of closest higher or equal element in x to each element in lookup.

Return type:

np.ndarray

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 11)
>>> lookup = np.array([-1, 1.1, 3.3, 9, 10.2])
>>> find_closest_higher_equal_element_indices_to_values(x, lookup, fill_not_valid=True)
array([ 0,  2,  4,  9, 10])

find_closest_lower_or_higher_element_indices_to_values(x: ndarray | list, lookup: ndarray | list)

Find indices of closest element in x to each element in lookup.

Parameters:

• x (np.ndarray) – Array of values to search in.

• lookup (np.ndarray) – Values to search for.

Returns:

Array of indices of closest element in x to each element in lookup.

Return type:

np.ndarray

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 11)
>>> lookup = np.array([-1, 1.1, 1.9, 2.1, 9, 10.2])
>>> find_closest_lower_or_higher_element_indices_to_values(x, lookup)
array([ 0,  1,  2,  2,  9, 10])

find_closest_element_indices_to_values(x: ndarray | list, lookup: ndarray | list, strategy: str = 'closest', fill_not_valid: bool = True)

Find indices of closest element in x to each element in lookup according to the strategy.

Parameters:

• x (np.ndarray) – Array of values to search in.

• lookup (np.ndarray) – Values to search for.

• strategy (str, default: 'closest') – Strategy to find the closest element. ‘closest’: closest element (lower or higher) ‘lower’: closest lower or equal element ‘higher’: closest higher or equal element

• fill_not_valid (bool, default: True) – Used in case of ‘lower’ and ‘higher’ strategy. If True, fill indices of lookup valules that are lower than the first element in ‘x’ with ‘x[0]’, fill indices of lookup values that are higher than the last element in ‘x’ with ‘len(x) - 1’.

Returns:

Array of indices of closest element in x to each element inlookup.

Return type:

np.ndarray

sum_over_indices(a, indices)

Sum values of array a over ranges defined by indices.

Parameters:

• a (array-like) – Array of values.

• indices (array-like of int) – Array of indices defining ranges over which to sum values.

Return type:

Array of sums of values over ranges defined by indices.

Examples

>>> import numpy as np
>>> x = np.linspace(0, 10, 11)
>>> indices = np.array([0, 3, 6, 10])
>>> sum_over_indices(x, indices)
array([ 3., 12., 30.])