pyfar.utils#

The utilities contain functions that are helpful when working with multiple pyfar audio objects. The pyfar gallery gives background information to work with audio objects including an introduction to the channel shape (cshape), channel axis (caxis), and channel dimension (cdim).

Functions:

broadcast_cdim(signal, cdim)

Broadcast a signal to a certain cdim.

broadcast_cdims(signals[, cdim])

Broadcast multiple signals to a common cdim.

broadcast_cshape(signal, cshape)

Broadcast a signal to a certain cshape.

broadcast_cshapes(signals[, cshape])

Broadcast multiple signals to a common cshape.

concatenate_channels(signals[, caxis, ...])

Merge multiple Signal, Timedata or Frequencydata objects along a given caxis.
pyfar.utils.broadcast_cdim(signal, cdim)[source]#

Broadcast a signal to a certain cdim.

The channel dimension (cdim) gives the dimension of the audio data excluding the last dimension, which is n_samples for time domain objects and n_bins for frequency domain objects. The signal is broadcasted to cdim by prepending cdim - len(signal.cshape) dimensions.

Parameters:
Returns:

signal – The broadcasted copy input signal

Return type:

Signal, TimeData, FrequencyData

pyfar.utils.broadcast_cdims(signals, cdim=None)[source]#

Broadcast multiple signals to a common cdim.

The channel dimension (cdim) gives the dimension of the audio data excluding the last dimension, which is n_samples for time domain objects and n_bins for frequency domain objects. The signals are broadcasted to cdim by prepending cdim - len(signal.cshape) dimensions.

Parameters:

  • signals (tuple of Signal, TimeData, FrequencyData) – The signals to be broadcasted in a tuple.

  • cdim (int, optional) – The cdim to which signal is broadcasted. If cdim is None the signals are broadcasted to the largest cdim. The default is None.

Returns:

signals – The broadcasted copies of the input signals in a tuple.

Return type:

tuple of Signal, TimeData, FrequencyData

pyfar.utils.broadcast_cshape(signal, cshape)[source]#

Broadcast a signal to a certain cshape.

The channel shape (cshape) gives the shape of the audio data excluding the last dimension, which is n_samples for time domain objects and n_bins for frequency domain objects. The broadcasting follows the numpy broadcasting rules.

Parameters:

  • signal (Signal, TimeData, FrequencyData) – The signal to be broadcasted.

  • cshape (tuple) – The cshape to which signal is broadcasted.

Returns:

signal – Broadcasted copy of the input signal

Return type:

Signal, TimeData, FrequencyData

pyfar.utils.broadcast_cshapes(signals, cshape=None)[source]#

Broadcast multiple signals to a common cshape.

The channel shape (cshape) gives the shape of the audio data excluding the last dimension, which is n_samples for time domain objects and n_bins for frequency domain objects. The broadcasting follows the numpy broadcasting rules.

Parameters:

  • signals (tuple of Signal, TimeData, FrequencyData) – The signals to be broadcasted in a tuple.

  • cshape (tuple, optional) – The cshape to which the signals are broadcasted. If cshape is None it is determined from the cshapes of the input signals using numpy.broadcast_shapes. The default is None.

Returns:

signals – The broadcasted copies of the input signals in a tuple.

Return type:

tuple of Signal, TimeData, FrequencyData

pyfar.utils.concatenate_channels(signals, caxis=0, broadcasting=False)[source]#

Merge multiple Signal, Timedata or Frequencydata objects along a given caxis.

Parameters:

  • signals (tuple of Signal, TimeData or FrequencyData) – The signals to concatenate. All signals must be of the same object type and either have the same cshape or be broadcastable to the same cshape, except in the dimension corresponding to caxis (the first, by default). If this is the case, set broadcasting=True.

  • caxis (int) – The channel axis (caxis) along which the signals are concatenated. The channel axis gives the axe of the audio data excluding the last dimension, which is n_samples for time domain objects and n_bins for frequency domain objects. The default is 0.

  • broadcasting (bool) – If this is True, the signals will be broadcasted to common cshape, except for the caxis along which the signals are concatenated. The caxis of the signals are broadcasted following the numpy broadcasting rules The default is False.

Returns:

merged – The merged signal object.

Return type:

Signal, TimeData, FrequencyData