Arrays Module

Additional dependencies

To use the soundevent.arrays module you need to install some additional dependencies. Make sure you have them installed by running the following command:

pip install soundevent[audio]

soundevent.arrays

Module for manipulation of xarray.DataArray objects.

This module provides functions for manipulating xarray.DataArray objects, including creating range dimensions, setting dimension attributes, cropping and extending axes, getting dimension ranges and widths, and setting values at specific positions.

soundevent.arrays.dimensions

Creating and manipulating DataArray dimensions in computational acoustics.

This module provides functions to:

• Define standard dimensions: Quickly create common dimensions in computational acoustics like 'time', 'frequency', 'channel', 'category', and 'feature' using the Dimensions enumeration.

• Build flexible data structures: Construct range-based dimensions (e.g., for time or frequency) with desired start, stop, and step values using create_range_dim.

• Work with time series: Generate time dimensions from arrays or given parameters with create_time_range and create_time_dim_from_array.

• Handle frequency representations: Create frequency dimensions from arrays or specified ranges with create_frequency_range and create_frequency_dim_from_array.

• Modify and extract metadata: Set dimension attributes (set_dim_attrs), retrieve dimension ranges (get_dim_range), calculate dimension width (get_dim_width), and estimate dimension step size (get_dim_step).

Classes:

Name	Description
Dimensions	Defines standard dimension names for computational acoustics arrays.

Functions:

Name	Description
create_frequency_dim_from_array	Create a frequency dimension from an array of frequency values.
create_frequency_range	Generate an xarray Variable representing a frequency range dimension.
create_range_dim	Create a range dimension.
create_time_dim_from_array	Create a time dimension from an array of time values.
create_time_range	Generate an xarray Variable representing a time range dimension.
estimate_dim_step	Estimate the step size of a numerical array.
get_coord_index	Get the index of a value along a dimension in a DataArray.
get_dim_range	Get the range of a dimension in a data array.
get_dim_step	Calculate the step size between values along a dimension in a DataArray.
get_dim_width	Get the width of a dimension in a data array.
set_dim_attrs	Set the range of a dimension in a data array.

Attributes

soundevent.arrays.dimensions.FREQUENCY_LONG_NAME = 'Frequency' module-attribute

soundevent.arrays.dimensions.FREQUENCY_STANDARD_NAME = 'frequency' module-attribute

soundevent.arrays.dimensions.FREQUENCY_UNITS = 'Hz' module-attribute

soundevent.arrays.dimensions.TIME_LONG_NAME = 'Time since start of recording' module-attribute

soundevent.arrays.dimensions.TIME_STANDARD_NAME = 'time' module-attribute

soundevent.arrays.dimensions.TIME_UNITS = 's' module-attribute

Classes

soundevent.arrays.dimensions.Dimensions

Bases: str, Enum

Defines standard dimension names for computational acoustics arrays.

This enumeration provides convenient and descriptive names for dimensions essential to representing acoustic data

Notes

Use these dimension names to ensure consistency and clarity in your code.

Attributes:

Name	Type	Description
category		Name for the category dimension of an array.
channel		Name for the channel dimension of an array.
feature		Name for the feature dimension of an array.
frequency		Name for the frequency dimension of an array.
time		Name for the time dimension of an array.

Attributes

category = 'category' class-attribute instance-attribute

Name for the category dimension of an array.

This dimension represents a categorical variable or label for each element in the array. If the original data is not categorical, it's converted to categorical data. Each value should be a string or integer label corresponding to a category or class.

channel = 'channel' class-attribute instance-attribute

Name for the channel dimension of an array.

This dimension represents the channel number of a multi-channel array, typically used in multi-channel audio recordings or spectrograms. Each channel corresponds to a distinct audio source or microphone in the recording.

feature = 'feature' class-attribute instance-attribute

Name for the feature dimension of an array.

This dimension represents a feature or numerical descriptor of the data. It's not limited to feature extraction results but can also include hand-measured or derived features. If an array contains multiple features, each feature should be stored along this dimension, with the name of the feature stored as a coordinate variable. If the array has time and frequency dimensions, the feature dimension then represents the feature values at each time-frequency point.

frequency = 'frequency' class-attribute instance-attribute

Name for the frequency dimension of an array.

This dimension represents frequency in Hz and should monotonically increase from the start to the end of the array. Generally regularly spaced, it may contain irregular spacing, such as with a logarithmic frequency scale or custom frequency bins.

time = 'time' class-attribute instance-attribute

Name for the time dimension of an array.

This dimension represents time in seconds and should monotonically increase from the start to the end of the array. While generally regularly spaced, it may contain missing values or irregular spacing in special cases.

Functions

soundevent.arrays.dimensions.create_frequency_dim_from_array(coods, name=Dimensions.frequency.value, step=None, estimate_step=False, dtype=None, **kwargs)

Create a frequency dimension from an array of frequency values.

Parameters:

Name	Type	Description	Default
coods	ndarray	The frequency values.	required
name	str	The name of the frequency dimension.	frequency.value
dtype	Optional[DTypeLike]	The data type of the frequency values. If None, the data type is inferred from the input array.	None
**kwargs		Additional attributes to store on the frequency dimension.	{}

Returns:

Type	Description
Variable	The frequency dimension variable.

soundevent.arrays.dimensions.create_frequency_range(low_freq, high_freq, step, name=Dimensions.frequency.value, dtype=np.float64, **attrs)

Generate an xarray Variable representing a frequency range dimension.

Creates a frequency range with a specified start (in Hz), end (in Hz), and step size (in Hz).

Parameters:

Name	Type	Description	Default
low_freq	float	Start of the frequency range (in Hz).	required
high_freq	float	End of the frequency range (in Hz).	required
step	float	Step size between frequency values (in Hz).	required
name	str	Name of the frequency dimension. Defaults to 'frequency'.	frequency.value
dtype	DTypeLike	Data type of the frequency values. Defaults to np.float64.	float64
**attrs		Additional attributes for the xarray Variable.	{}

Returns:

Type	Description
Variable	Variable containing the frequency range values.

soundevent.arrays.dimensions.create_range_dim(name, start, stop, step=None, size=None, dtype=np.float64, **attrs)

Create a range dimension.

Most coordinates used in computational bioacoustics are regularly spaced ranges. This function creates a range dimension with a specified start, stop, and step size. It stores the start, end, and step values as attributes on the coordinate.

Parameters:

Name	Type	Description	Default
name	str	The name of the range dimension.	required
start	float	The start value of the range.	required
stop	float	The stop value of the range.	required
step	float	The step size between values in the range.	None
dtype	dtype or str	The data type of the values in the range. Defaults to np.float32.	float64
**attrs		Additional attributes to store on the range dimension.	{}

Returns:

Type	Description
Variable	A variable representing the range dimension.

Notes

• The range is created using np.arange(start, stop, step, dtype).
• The variable has attributes 'start', 'end', and 'step' representing the range parameters.

soundevent.arrays.dimensions.create_time_dim_from_array(coods, name=Dimensions.time.value, dtype=None, step=None, samplerate=None, estimate_step=False, **kwargs)

Create a time dimension from an array of time values.

Parameters:

Name	Type	Description	Default
coods	ndarray	The time values.	required
name	str	The name of the time dimension.	time.value
dtype	Optional[DTypeLike]	The data type of the time values. If None, the data type is inferred from the input array.	None
**kwargs		Additional attributes to store on the time dimension.	{}

Returns:

Type	Description
Variable	The time dimension variable.

soundevent.arrays.dimensions.create_time_range(start_time, end_time, step=None, samplerate=None, name=Dimensions.time.value, dtype=np.float64, **attrs)

Generate an xarray Variable representing a time range dimension.

Creates a time range with specified start (in seconds), end (in seconds), and the desired time step between values.

Parameters:

Name	Type	Description	Default
start_time	float	Start of the time range (in seconds).	required
end_time	float	End of the time range (in seconds).	required
step	Optional[float]	Step size between time values (in seconds). If not provided, calculated as 1 / samplerate.	None
samplerate	Optional[float]	Sampling rate (in Hz). Used to calculate step if step is not given. If both step and samplerate are provided, step takes precedence.	None
name	str	Name of the time dimension. Defaults to 'time'.	time.value
dtype	DTypeLike	Data type of the time values. Defaults to np.float64.	float64
**attrs		Additional attributes for the xarray Variable.	{}

Returns:

Type	Description
Variable	Variable containing the time range values.

soundevent.arrays.dimensions.estimate_dim_step(data, rtol=1e-05, atol=1e-08, check_tolerance=True)

Estimate the step size of a numerical array.

Parameters:

Name	Type	Description	Default
data	ndarray	The numerical array.	required
rtol	float	The relative tolerance used when checking if all values are within a specified range of the mean step size. Defaults to 1e-5.	1e-05
atol	float	The absolute tolerance used when checking if all values are within a specified range of the mean step size. Defaults to 1e-8.	1e-08
check_tolerance	bool	A flag indicating whether to perform a tolerance check on the differences between consecutive values. If True (default), raises a ValueError if the differences exceed the specified tolerances.	True

Returns:

Type	Description
float	The estimated step size of the array.

Raises:

Type	Description
ValueError	If check_tolerance is True and the differences between consecutive values exceed the specified tolerances (indicating an irregular step size).

Notes

This function calculates the mean of the differences between consecutive values in the array. If check_tolerance is True, it verifies if all differences are within a specified tolerance (defined by rtol and atol) of the calculated mean step size. If not, it raises a ValueError indicating an irregular step size.

This function assumes the array values are numerical and equidistant (constant step size) unless the tolerance check fails.

soundevent.arrays.dimensions.get_coord_index(arr, dim, value, raise_error=True)

Get the index of a value along a dimension in a DataArray.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input DataArray.	required
dim	str	The name of the dimension.	required
value	float	The value to find along the dimension.	required
raise_error	bool	A flag indicating whether to raise an error if the value is outside the range of the dimension. If True (default), raises a KeyError. If False, returns the index of the closest value within the range.	True

Returns:

Type	Description
int	The index of the value along the specified dimension.

Raises:

Type	Description
ValueError	If the value is not found within the range of the dimension or if the dimension is not found in the DataArray.

soundevent.arrays.dimensions.get_dim_range(array, dim)

Get the range of a dimension in a data array.

Parameters:

Name	Type	Description	Default
array	DataArray	The data array from which to extract the dimension range.	required
dim	str	The name of the dimension.	required

Returns:

Type	Description
Tuple[Optional[float], Optional[float]]	A tuple containing the start and end values of the dimension range.

Raises:

Type	Description
KeyError	If the dimension is not found in the data array.

soundevent.arrays.dimensions.get_dim_step(arr, dim, rtol=1e-05, atol=1e-08, check_tolerance=True, estimate_step=True)

Calculate the step size between values along a dimension in a DataArray.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input DataArray.	required
dim	str	The name of the dimension for which to calculate the step size.	required
rtol	float	The relative tolerance used when checking if all coordinate differences are within a specified range of the mean step size. Defaults to 1e-5.	1e-05
atol	float	The absolute tolerance used when checking if all coordinate differences are within a specified range of the mean step size. Defaults to 1e-8.	1e-08
check_tolerance	bool	A flag indicating whether to perform a tolerance check on the coordinate differences. If True (default), raises a ValueError if the differences exceed the specified tolerances.	True
estimate_step	bool	A flag indicating whether to estimate the step size if not present in the dimension attributes. If True (default), calculates the mean step size from the coordinate values. Otherwise, raises a ValueError if the step size is not found in the dimension attributes.	True

Returns:

Type	Description
float	The calculated step size (spacing) between consecutive values along the specified dimension.

Raises:

Type	Description
ValueError	If check_tolerance is True and the coordinate differences exceed the specified tolerances (indicating an irregular step size).

Notes

This function first attempts to retrieve the step size from the dimension's attributes using the standard attribute name 'step' defined in the RangeAttrs enumeration. If the attribute is not present, it calculates the step size by taking the mean of the differences between consecutive coordinate values.

If check_tolerance is True, the function verifies if all coordinate differences are within a specified tolerance (defined by rtol and atol) of the calculated mean step size. If not, it raises a ValueError indicating an irregular step size.

This function assumes the DataArray coordinates are numerical and equidistant (constant step size) unless a valid step size attribute is present or the tolerance check fails.

soundevent.arrays.dimensions.get_dim_width(arr, dim)

Get the width of a dimension in a data array.

Parameters:

Name	Type	Description	Default
arr	DataArray	The data array containing the dimension.	required
dim	str	The name of the dimension.	required

Returns:

Type	Description
float	The width of the dimension.

Raises:

Type	Description
KeyError	If the dimension is not found in the data array.

soundevent.arrays.dimensions.set_dim_attrs(array, dim, **attrs)

Set the range of a dimension in a data array.

Use this function to set the precise start and end values of a dimension in a data array. This is useful when the coordinates represent the start of a range, but you want to specify the end of the range as well.

The start and end values are stored as attributes on the coordinates.

soundevent.arrays.attributes

Standard attributes for acoustic data arrays.

This module provides enumerations for commonly used attributes to describe dimensions and arrays of numerical data in computational acoustics tasks. These attributes are based on a subset of the Climate and Forecast (CF) conventions documentation, a widely used standard for describing scientific data.

The module includes enums for:

• Dimension attributes
• Range attributes
• Array attributes

By using these standard attributes, you can ensure interoperability and consistency in your acoustic data representation.

For a complete list of CF conventions attributes, refer to the Attribute Conventions.

Classes:

Name	Description
ArrayAttrs	Standard attribute names for acoustic data arrays.
DimAttrs	Standard attribute names for acoustic data dimensions.

Classes

soundevent.arrays.attributes.ArrayAttrs

Bases: str, Enum

Standard attribute names for acoustic data arrays.

This enumeration defines standard attribute names used to describe properties of acoustic data arrays. These attributes follow the CF conventions and provide a consistent way to represent information about the data.

Attributes:

Name	Type	Description
comment		Attribute name for any additional comments or explanations about the
long_name		Attribute name for a human-readable description of the array variable.
references		Attribute name for references to external documentation or resources
standard_name		Attribute name for the standard name of an array variable.
units		Attribute name for the units of an array variable.

Attributes

comment = 'comment' class-attribute instance-attribute

Attribute name for any additional comments or explanations about the array variable.

long_name = 'long_name' class-attribute instance-attribute

Attribute name for a human-readable description of the array variable.

This can be more detailed than the standard name and provide additional context for users.

references = 'references' class-attribute instance-attribute

Attribute name for references to external documentation or resources that provide more information about the array variable.

standard_name = 'standard_name' class-attribute instance-attribute

Attribute name for the standard name of an array variable.

As defined by the CF conventions. This provides a consistent way to identify arrays across different datasets.

units = 'units' class-attribute instance-attribute

Attribute name for the units of an array variable.

This specifies the physical quantity represented by the array, such as 'dB' for sound pressure level or 'meters' for distance. It follows the UDUNITS standard for unit symbols.

soundevent.arrays.attributes.DimAttrs

Bases: str, Enum

Standard attribute names for acoustic data dimensions.

This enumeration defines standard attribute names used to describe dimensions of acoustic data arrays. These attributes follow the CF conventions and provide a consistent way to represent information about dimensions, such as units, standard names, and long names.

Attributes:

Name	Type	Description
long_name		Attribute name for a human-readable description of the dimension.
standard_name		Attribute name for the standard name of a dimension.
step		Attribute name for the step size of a range dimension.
units		Attribute name for the units of a dimension.

Attributes

long_name = 'long_name' class-attribute instance-attribute

Attribute name for a human-readable description of the dimension.

This can be more detailed than the standard name and provide additional context for users.

standard_name = 'standard_name' class-attribute instance-attribute

Attribute name for the standard name of a dimension.

As defined by the CF conventions. This provides a consistent way to identify dimensions across different datasets.

step = 'step' class-attribute instance-attribute

Attribute name for the step size of a range dimension.

Specifies the distance between consecutive values in the range, which might not be explicitly stored as a coordinate value. If not present, the dimension is assumed to be irregularly spaced. Not a standard CF attribute.

units = 'units' class-attribute instance-attribute

Attribute name for the units of a dimension.

This specifies the physical quantity represented by the dimension, such as 'seconds' for time or 'meters' for distance. It follows the UDUNITS standard for unit symbols.

soundevent.arrays.operations

Module for manipulation of xarray.DataArray objects.

Functions:

Name	Description
adjust_dim_range	Adjust the range of a specified dimension in an xarray DataArray.
adjust_dim_width	Adjust the width of an xarray DataArray along a specified dimension.
center	Center the values of a data array around zero.
crop_dim	Crop a dimension of a data array to a specified range.
crop_dim_width	Crops an xarray DataArray along a specified dimension to a given width.
extend_dim	Extend a dimension of a data array to a specified range.
extend_dim_width	Extend an xarray DataArray along a specified dimension to a given width.
normalize	Normalize the values of a data array to the range [0, 1].
offset	Offset the values of a data array by a constant value.
resize	Resize a data array to the specified dimensions.
scale	Scale the values of a data array by a constant value.
set_value_at_pos	Set a value at a specific position in a data array.
to_db	Compute the decibel values of a data array.

Attributes

soundevent.arrays.operations.Position = Literal['start', 'center', 'end'] module-attribute

Functions

soundevent.arrays.operations.adjust_dim_range(array, dim, start=None, stop=None, fill_value=0)

Adjust the range of a specified dimension in an xarray DataArray.

This function modifies the range of a given dimension (dim) in an xarray DataArray to match a desired range defined by start and stop. It ensures that the adjusted dimension aligns with these bounds while considering the original step size of the dimension.

Parameters:

Name	Type	Description	Default
array	DataArray	The input xarray DataArray to be adjusted.	required
dim	str	The name of the dimension to be adjusted.	required
start	float	The desired starting value for the dimension. If None (default), the starting value is not adjusted.	None
stop	float	The desired stopping value for the dimension. If None (default), the stopping value is not adjusted.	None
fill_value	float	The value to fill for missing data in the extended range. Defaults to 0.	0

Returns:

Type	Description
DataArray	The adjusted xarray DataArray with the modified dimension range.

Raises:

Type	Description
ValueError	If both start and stop are None. If start is greater than or equal to stop.

Notes

The function utilizes crop_dim and extend_dim to modify the specified dimension. It calculates adjusted bounds to ensure the modified dimension aligns with the desired range while preserving the original step size as much as possible.

soundevent.arrays.operations.adjust_dim_width(array, dim, width, fill_value=0, position='start')

Adjust the width of an xarray DataArray along a specified dimension.

This function effectively places the original array within a larger or smaller array of the desired width (width), cropping or extending it as needed. The position parameter controls where the original array is placed within this other array:

• 'start': Places the input array at the start, cropping or extending towards the end.
• 'end': Places the input array at the end, cropping or extending towards the start.
• 'center': Places the input array at the center, cropping or extending at both ends.

Parameters:

Name	Type	Description	Default
array	DataArray	The DataArray to be adjusted.	required
dim	str	The name of the dimension to adjust.	required
width	int	The desired width of the dimension.	required
fill_value	float	The value to fill the extended region with, if extending.	0
position	(start, end, center)	The position from which to crop or at which to extend. - 'start': Crop/extend at the beginning of the dimension. - 'end': Crop/extend at the end of the dimension. - 'center': Crop/extend at the center of the dimension.	'start'

Returns:

Type	Description
DataArray	The adjusted DataArray.

Raises:

Type	Description
ValueError	If the width is less than 1.

Examples:

>>> import xarray as xr
>>> import numpy as np
>>> array = xr.DataArray(np.arange(10), dims="x")
>>> adjust_dim_width(array, "x", 5, position="start")
<xarray.DataArray (x: 5)>
array([0, 1, 2, 3, 4])
Coordinates:
  * x        (x) int64 0 1 2 3 4
>>> adjust_dim_width(array, "x", 12, position="end")
<xarray.DataArray (x: 12)>
array([0., 0., 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])
Coordinates:
  * x        (x) float64 -2.0 -1.0 0.0 1.0 2.0 3.0 ... 6.0 7.0 8.0 9.0 10.0

soundevent.arrays.operations.center(arr)

Center the values of a data array around zero.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to center.	required

Returns:

Type	Description
DataArray	The centered data array.

Notes

This function stores the offset used for centering as an attribute in the output data array.

soundevent.arrays.operations.crop_dim(arr, dim, start=None, stop=None, right_closed=False, left_closed=True, eps=1e-05)

Crop a dimension of a data array to a specified range.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to crop.	required
dim	str	The name of the dimension to crop.	required
start	Optional[float]	The start value of the cropped range. If None, the current start value of the axis is used. Defaults to None.	None
stop	Optional[float]	The stop value of the cropped range. If None, the current stop value of the axis is used. Defaults to None.	None
right_closed	bool	Whether the right boundary of the cropped range is closed. Defaults to False.	False
left_closed	bool	Whether the left boundary of the cropped range is closed. Defaults to True.	True
eps	float	A small value added to start and subtracted from stop to ensure open intervals. Defaults to 10e-6.	1e-05

Returns:

Type	Description
DataArray	The cropped data array.

Raises:

Type	Description
ValueError	If the coordinate for the specified dimension does not have 'start' and 'stop' attributes, or if the specified range is outside the current axis range.

Notes

The function crops the specified dimension of the data array to the range [start, stop). The right_closed and left_closed parameters control whether the boundaries of the cropped range are closed or open. A small value eps is added to start and subtracted from stop to ensure open intervals if right_closed or left_closed is False. The 'start' and 'stop' attributes of the cropped dimension coordinate are updated accordingly.

soundevent.arrays.operations.crop_dim_width(array, dim, width, position='start')

Crops an xarray DataArray along a specified dimension to a given width.

Parameters:

Name	Type	Description	Default
array	DataArray	The DataArray to be cropped.	required
dim	str	The name of the dimension to crop.	required
width	int	The desired width of the dimension after cropping.	required
position	(start, end, center)	The position from which to crop. - 'start': Crop from the beginning of the dimension. - 'end': Crop from the end of the dimension. - 'center': Crop from the center of the dimension.	'start'

Returns:

Type	Description
DataArray	The cropped DataArray.

Raises:

Type	Description
ValueError	If the new width is greater than or equal to the current width, or if the position is invalid.

Examples:

>>> import xarray as xr
>>> import numpy as np
>>> array = xr.DataArray(np.arange(10), dims="x")
>>> crop_dim_width(array, "x", 5, position="start")
<xarray.DataArray (x: 5)>
array([0, 1, 2, 3, 4])
Coordinates:
  * x        (x) int64 0 1 2 3 4
>>> crop_dim_width(array, "x", 3, position="end")
<xarray.DataArray (x: 3)>
array([7, 8, 9])
Coordinates:
  * x        (x) int64 7 8 9
>>> crop_dim_width(array, "x", 4, position="center")
<xarray.DataArray (x: 4)>
array([3, 4, 5, 6])
Coordinates:
  * x        (x) int64 3 4 5 6

soundevent.arrays.operations.extend_dim(arr, dim, start=None, stop=None, fill_value=0, eps=1e-05, left_closed=True, right_closed=False)

Extend a dimension of a data array to a specified range.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to extend.	required
dim	str	The name of the dimension to extend.	required
start	Optional[float]	The start value of the extended range.	None
stop	Optional[float]	The stop value of the extended range.	None
fill_value	float	The value to fill for missing data in the extended range. Defaults to 0.	0
eps	float	A small value added to start and subtracted from stop to ensure open intervals. Defaults to 10e-6.	1e-05
left_closed	bool	Whether the left boundary of the extended range is closed. Defaults to True.	True
right_closed	bool	Whether the right boundary of the extended range is closed. Defaults to False.	False

Returns:

Type	Description
DataArray	The extended data array.

Raises:

Type	Description
KeyError	If the dimension is not found in the data array.

Notes

The function extends the specified dimension of the data array to the range [start, stop). If the specified range extends beyond the current axis range, the function adds values to the beginning or end of the coordinate array. The 'start' and 'stop' attributes of the extended dimension coordinate are updated accordingly.

soundevent.arrays.operations.extend_dim_width(array, dim, width, fill_value=0, position='start')

Extend an xarray DataArray along a specified dimension to a given width.

Parameters:

Name	Type	Description	Default
array	DataArray	The DataArray to be extended.	required
dim	str	The name of the dimension to extend.	required
width	int	The desired width of the dimension after extension.	required
fill_value	float	The value to fill the extended region with.	0
position	(start, end, center)	The position at which to extend. Imagine placing the original array within a larger array of the desired width. This parameter controls where the original array is placed within this larger array: 'start': Keep the start position of the original array, and extend towards the end of the larger array. 'end': Keep the end position of the original array, and extend towards the start of the larger array. 'center': Extend at both ends of the original array, keeping it centered within the larger array.	'start'

Returns:

Type	Description
DataArray	The extended DataArray.

Raises:

Type	Description
ValueError	If the new width is less than or equal to the current width, or if the position is invalid.

Examples:

>>> import xarray as xr
>>> import numpy as np
>>> array = xr.DataArray(np.arange(5), dims="x")
>>> extend_dim_width(array, "x", 8, position="start")
<xarray.DataArray (x: 8)>
array([0., 1., 2., 3., 4., 0., 0., 0.])
Coordinates:
  * x        (x) float64 0.0 1.0 2.0 3.0 4.0 5.0 6.0 7.0
>>> extend_dim_width(array, "x", 7, position="end")
<xarray.DataArray (x: 7)>
array([0., 0., 0., 1., 2., 3., 4.])
Coordinates:
  * x        (x) int64 -2 -1  0  1  2  3  4
>>> extend_dim_width(array, "x", 9, position="center")
<xarray.DataArray (x: 9)>
array([0., 0., 0., 1., 2., 3., 4., 0., 0.])
Coordinates:
  * x        (x) float64 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 5.0 6.0

soundevent.arrays.operations.normalize(arr)

Normalize the values of a data array to the range [0, 1].

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to normalize.	required

Returns:

Type	Description
DataArray	The normalized data array.

Notes

This function stores the offset and scale factor used for normalization as attributes in the output data array.

soundevent.arrays.operations.offset(arr, val)

Offset the values of a data array by a constant value.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to offset.	required
val	float	The value to add to the data array.	required

Returns:

Type	Description
DataArray	The offset data array.

Notes

This function stores the offset used for the offsetting as an attribute in the output data array.

soundevent.arrays.operations.resize(arr, method='linear', dtype=np.float64, **dims)

Resize a data array to the specified dimensions.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to resize.	required
method	InterpOptions	The interpolation method to use. Defaults to 'linear'.	'linear'
dtype	DTypeLike	The data type of the resized data array. Defaults to np.float64.	float64
**dims	int	The new dimensions for each axis of the data array.	{}

Returns:

Type	Description
DataArray	The resized data array.

Raises:

Type	Description
ValueError	If the new dimensions do not match the current dimensions of the data array.

Notes

This function resizes the data array to the specified dimensions. The function does not modify the data array in place.

soundevent.arrays.operations.scale(arr, val)

Scale the values of a data array by a constant value.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array to scale.	required
val	float	The value to multiply the data array by.	required

Returns:

Type	Description
DataArray	The scaled data array.

Notes

This function stores the scale factor used for scaling as an attribute in the output data array.

soundevent.arrays.operations.set_value_at_pos(array, value, **query)

Set a value at a specific position in a data array.

Parameters:

Name	Type	Description	Default
array	DataArray	The input data array.	required
value	Any	The value to set at the specified position.	required
**query	dict	Keyword arguments specifying the position in each dimension where the value should be set. Keys are dimension names, values are the positions.	{}

Returns:

Type	Description
DataArray	The modified data array with the value set at the specified position.

Raises:

Type	Description
ValueError	If a dimension specified in the query is not found in the data array.
KeyError	If the position specified in the query is outside the range of the corresponding dimension.

Notes

Modifies the input data array in-place.

When specifying approximate positions (e.g., x=1.5) the value will be set at the closest coordinate to the left of the specified value. This aligns with how coordinates are often interpreted as the boundaries of intervals.

If value is a tuple or list, its dimensions must match the queried dimensions of the array, and the value will be set at the specified position along each dimension.

Examples:

>>> import xarray as xr
>>> import numpy as np
>>> data = np.zeros((3, 3))
>>> coords = {"x": np.arange(3), "y": np.arange(3)}
>>> array = xr.DataArray(data, coords=coords, dims=("x", "y"))

Setting a single value:

>>> array = set_value_at_position(array, 1, x=1, y=1)
>>> print(array)
<xarray.DataArray (x: 3, y: 3)>
array([[0., 0., 0.],
       [0., 1., 0.],
       [0., 0., 0.]])

Setting a value at an approximate position:

>>> array = xr.DataArray(data, coords=coords, dims=("x", "y"))
>>> array = set_value_at_position(array, 1, x=1.5, y=1.5)
>>> print(array)
<xarray.DataArray (x: 3, y: 3)>
array([[0., 0., 0.],
       [0., 1., 0.],
       [0., 0., 0.]])

Setting a multi-dimensional value:

>>> array = xr.DataArray(data, coords=coords, dims=("x", "y"))
>>> value = np.array([1, 2, 3])
>>> array = set_value_at_position(array, value, x=1)
>>> print(array)
<xarray.DataArray (x: 3, y: 3)>
array([[0., 0., 0.],
       [1., 2., 3.],
       [0., 0., 0.]])

soundevent.arrays.operations.to_db(arr, ref=1.0, amin=1e-10, min_db=-80.0, max_db=None, power=1)

Compute the decibel values of a data array.

Parameters:

Name	Type	Description	Default
arr	DataArray	The input data array.	required
ref	Union[float, Callable[[DataArray], float]]	The reference value for the decibel computation. Defaults to 1.0.	1.0
amin	float	Minimum threshold for the input data array. Defaults to 1e-10. All values below this threshold are replaced with this value before computing the decibel values.	1e-10
min_db	Optional[float]	The minimum decibel value for the output data array. Defaults to 80.0. All values below this threshold are replaced with this value. If None, no minimum threshold is applied.	-80.0
max_db	Optional[float]	The maximum decibel value for the output data array. Defaults to None. All values above this threshold are replaced with this value. If None, no maximum threshold is applied.	None

Returns:

Type	Description
DataArray	The data array with decibel values computed.

Notes

The function computes the decibel values of the input data array using the formula 10 * log10(arr / ref).

This function is heavily inspired by and includes modifications of code originally found in librosa, available at https://github.com/librosa/librosa/. The original code is licensed under the ISC license.

Original copyright notice: Copyright (c) 2013--2023, librosa development team.

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.