References

Release:1.1.2
Date:November 14, 2018

madarrays.masked_array module

Definition of a masked array.

class madarrays.mad_array.MadArray[source]

Bases: numpy.ndarray

Subclass of numpy.ndarray to handle data with missing elements.

Type of entry: entries of array can be int, float, or complex.

Masking: the masking of entries has two different modes:

  • Entries can be either masked or not masked, leading to a boolean mask, whose entries are equal to True if the corresponding data entry is masked, or False otherwise.

    This is the default mode and the mode selected when specifying mask during creation.

  • Complex entries can have only the magnitude or phase component masked, or both. The resulting mask has integers entries, equal to:

    • 0 if the phase and the magnitude are not masked (known magnitude and phase);
    • 1 if only the phase is masked (known magnitude, unknown phase);
    • 2 if only the magnitude is masked (unknown magnitude, known phase);
    • 3 if the magnitude and the phase are masked (unknown magnitude and phase).

    This mode is selected when specifying mask_magnitude and/or mask_phase during creation. Entries are converted to a complex type.

    If entries are complex values and mask is given during creation, both the magnitude and phase are masked and the boolean mask mode is used.

Indexing: two different modes to index a MadArray object are implemented:

  • a MadArray object with shape corresponding to the indices is returned, with both the data matrix and the mask properly indexed. This is the default mode;
  • a MadArray object with unchanged shape is returned, where non-indexed entries are set as masked. This mode is selected by setting the parameter masked_indexing to True.

Numpy behaviour: it is possible to use standard operations (+, -, /, //, *, T) between two MadArray objects, likewise operations between numpy arrays. The resulting object has a mask consisting of the union of the operands. It is also possible to use pickle operations to jointly store the data and the mask.

Parameters:

data : array_like

Multidimensional array. See Type of Entry.

mask : boolean array_like, optional

Mask for boolean masking mode. See Masking.

mask_magnitude : boolean array_like or None, optional

Magnitude mask for masking with complex data. See Masking.

mask_phase : boolean or array_like or None, optional

Phase mask for masking with complex data. See Masking.

masked_indexing : bool or None, optional

Indicate how the indexing is performed. If None, set to False. See Indexing.

Warning

This class inherits from ndarray or subclass of ndarray. Instances can be then manipulated like ndarrays (e.g., indexation). While some methods have been implemented taking into account the mask, some may cause unexpected behavior (e.g., mean).

See also

numpy.doc.subclassing

Notes

This class implements an alternative masked array different from numpy.ma.MaskedArray. The reason of this choice is that it is only used as a container of a ndarray and a mask. No masked operations are needed.

n_missing_data

Number of missing data (double or tuple).

Number of masked coefficients if dtype is int or float. Number of masked coefficients in phase and magnitude masks if dtype is complex.

ratio_missing_data

Ratio of missing data (double or tuple).

Ratio of masked coefficients if dtype is int or float. Ratio of masked coefficients in phase and magnitude masks if dtype is complex.

is_masked()[source]

Indicate if one or several elements are masked.

to_np_array(fill_value=None)[source]

Return a numpy array.

If fill_value is not None, masked elements are replaced according to the type of entries:

  • fill_value if the type of entries is int or float;
  • If the type is complex, missing entries are replaced either by:
    • a complex number with the known magnitude value without the phase information if only the phase is masked;
    • a complex number of magnitude 1 with the known phase if only the magnitude is masked;
    • by fill_value if both magnitude and phase are masked.
Parameters:

fill_value : scalar or None

Value used to fill masked elements. If None, the initial value is kept.
Returns:

nd-array
is_equal(other)[source]
T

Transpose of the MadArray.

copy(order='C')[source]
transpose(*axes)[source]
get_known_mask(mask_type='all')[source]

Boolean mask for known coefficients.

Compute the boolean mask marking known coefficients as True.

Parameters:

mask_type : {‘all’, ‘any’, ‘magnitude’, ‘phase’, ‘magnitude only’, ‘phase only’}

Type of mask:

  • all: mark coefficients for wich both the magnitude and the phase are known,
  • any: mark coefficients for wich the magnitude or the phase are known (including when both the magnitude and the phase are known),
  • magnitude: mark coefficients for wich the magnitude is known,
  • phase: mark coefficients for wich the phase is known,
  • magnitude only: mark coefficients for wich both the magnitude is known and the phase is unknown,
  • phase only: mark coefficients for wich both the phase is known and the magnitude is unknown.
Returns:

mask : boolean nd-array

Boolean array with entries set to True if the corresponding value in the object is known.
Raises:

ValueError

If mask_type has an invalid value.
get_unknown_mask(mask_type='any')[source]

Boolean mask for unknown coefficients.

Compute the boolean mask marking unknown coefficients as True.

Parameters:

mask_type : {‘any’, ‘all’, ‘magnitude’, ‘phase’, ‘magnitude only’, ‘phase only’}

Type of mask:

  • any: mark coefficients for wich the magnitude or the phase are unknown (including when both the magnitude and the phase are unknown),
  • all: mark coefficients for wich both the magnitude and the phase are unknown,
  • magnitude: mark coefficients for wich the magnitude is unknown,
  • phase: mark coefficients for wich the phase is unknown,
  • magnitude only: mark coefficients for wich both the magnitude is unknown and the phase is known,
  • phase only: mark coefficients for wich both the phase is unknown and the magnitude is known.
Returns:

mask : boolean nd-array

Boolean array with values set to True if the corresponding value in the object is unknown.
Raises:

ValueError

If mask_type has an invalid value.

madarrays.waveform module

Definition of a masked waveform.

class madarrays.waveform.Waveform[source]

Bases: madarrays.mad_array.MadArray

Subclass of MadArray to handle mono and stereo audio signals.

Waveform inherits from MadArray and adds an attribute fs to store the sampling frequency, as well as methods to facilitate the manipulation of audio files.

Type of entries: audio data entries can have different types, that are associated with specific constraints on the values:

  • float: the values are float between -1 and 1;
  • int: the values are integers between a range that depends on the precision.
  • complex: the real and imaginary parts are float between -1 and 1.

High-precision types (float128, int64, complex256) may lead to problems and should be used with caution.

The casting of a waveform in a different dtype depends on the current dtype and the desired dtype (complex casting is similar to float casting):

  • Integer-to-real casting is performed by applying on each entry \(x\) the function \(f(x)=\frac{x - z}{2^{n-1}}\), where the source integral type is coded with \(n\) bits, and \(z\) is the integer associated with zero, i.e., \(z=0\) for a signed type (int) and \(z=2^{n-1}\) for an unsigned type (uint).
  • Real-to-integer casting is performed by applying on each entry \(x\) the function \(f(x)=\lfloor\left(x + 1\right) 2^{n-1} + m\rfloor\), where the target integral type is coded with \(n\) bits, and \(m\) is the minimum integer value, i.e., \(m=-2^{n-1}\) for a signed type (int) and \(z=0\) for an unsigned type (uint);
  • Real-to-real casting is obtained by a basic rounding operation;
  • Integer-to-integer casting is obtained by chaining an integer-to-float64 casting and a float64-to-integer casting.

Clipping is performed for unexpected values:

  • When casting to float, values outside \([-1, 1]\) are clipped;

  • When casting to int, values outside the minimum and maximum values allowed by the integral type are clipped:

    • \(\left[-2^{n-1}, 2^{n-1}-1\right]\) for \(n\)-bits signed integers;
    • \(\left[0, 2^{n}-1\right]\) for \(n\)-bits unsigned integers.

These constraints are only applied when calling explicitely the method astype().

Masking: Waveform allows for complex entries, but only real-like masking is permitted, i.e. it is not possible to mask only the phase or the amplitude. In particular, this implies that the attribute _is_complex inherited from MadArray is always equal to False.

Parameters:

data : nd-array [N] or [N, 2]

Audio samples, as a N-length vector for a mono signal or a [N, 2]-shape array for a stereo signal

fs : int or float, optional

Sampling frequency of the original signal, in Hz. If float, truncated. If None and data is a Waveform, use data.fs, otherwise it is set to 1.

mask : nd-array, optional

Boolean mask with True values for missing samples. Its shape must be the same as data.

indexing :

See MadArray.
fs

Frequency sampling of the audio signal (int or float).

The signal is not resampled when the sampling frequency is modified.

Raises:

ValueError

If fs is not positive.
rms

Root mean square error of the masked signal (float).

Raises:

NotImplementedError

If data is with an integer type.
length

Length of the signal, in samples.

duration

Duration of the signal, in seconds.

n_channels

Number of channels (1 for mono, 2 for stereo).

time_axis

Time axis.

is_stereo()[source]

Indicates whether the signal is stereo or not.

set_rms(rms)[source]

Set root mean square error of the signal.

Parameters:

rms : float

Root mean square of the signal.
Raises:

ValueError

If rms is negative.

NotImplementedError

If data is with an integer type.
resample(fs)[source]

Resample the audio signal, in place.

Can be only performed on a waveform without missing data.

Note that if the current or the new sampling frequencies are not integers, the new sampling frequency may be different from the desired value since the resampling method only allows input and output frequencies of type int. In this case, a warning is raised.

Parameters:

fs : int or float

New sampling frequency.
Raises:

ValueError

If fs is not a positive number. If self has missing samples.

UserWarning
plot(x_axis_label='Time (s)', y_axis_label='', cpx_mode='real', fill_value=0, **kwargs)[source]

Plot the signal.

Parameters:

x_axis_label : str

Label of the x axis.

y_axis_label : str

Label of the y axis.

cpx_mode : {‘real’, ‘imag’, ‘both’}

In case of a complex-valued signal, plot the real part only (‘real’), the imaginary part only (‘imag’), or both curves (‘both’). This option has no effect if the signal is real-valued.

fill_value : scalar or None

Value used to fill missing data for display. If None, the existing value is used (e.g., for clipping).
Returns:

List of Line
Other Parameters:
 

kwargs
plot_mask(x_axis_label='Time (s)', y_axis_label='', **kwargs)[source]

Plot the mask.

Parameters:

x_axis_label : str

Label of the time axis (horizontal axis).

y_axis_label : str

Label of the frequency axis (vertical axis).
to_wavfile(filename, dtype=None)[source]

Save the wavefile as an audio wav file.

Parameters:

filename : str or pathlib.Path

Name of the file including paths and extension

dtype : data-type or None, optional

Type of the entries of the wav file. If None, use current dtype of data.
Raises:

UserWarning

If the signal is complex.

ValueError

If the sampling frequency is not an integer from the set of supported frequencies madarrays.waveform.VALID_IO_FS).

NotImplementedError

If dtype is not supported by the current implementation.

See also

scipy.io.wavfile.write

static from_wavfile(filename, dtype=<class 'numpy.float64'>, conversion_to_mono=None)[source]

Load an audio file and return an Waveform object.

Parameters:

filename : str or pathlib.Path

Name of the audio file

dtype : data-type, optional

Output data type. If None, the data type from the wavfile is kept. See Type of Entry.

conversion_to_mono : {‘left’, ‘right’, ‘mean’} or None, optional

If None (default), no conversion is performed. If str, select the appropriate channel (left or right), or the mean between the left and right channels if stereo.
Returns:

Waveform
fade(mode='both', fade_duration=None, fade_length=None)[source]

Apply fade-in and/or fade-out.

Half a hanning window with the specified length or duration is used (exactly one parameter fade_duration or fade_length must be set).

Parameters:

mode : {‘both’, ‘in’, ‘out’}, optional

Signal to be processed.

fade_duration : float, optional

Duration, in seconds, of the fade effect.

fade_length : int, optional

Length, in samples, of the fade effect.
Raises:

ValueError

If neither fade_duration nor fade_length is given. If both fade_duration and fade_length are given. If fade_duration or fade_length are greater than the duration or length of the waveform. If fade_duration or fade_length are negative. If mode is invalid.
show_player()[source]

Show the player when using jupyter notebook.

Raises:

ValueError

If sampling frequency is 1.
play(scale=False)[source]

Play the audio file.

Parameters:

scale : bool

If True, the data is normalized by maximum value.
Returns:

simpleaudio.PlayObject

Object useful to handle the played audio stream.
Raises:

ValueError

If sampling frequency is 1.
stop()[source]

Stop playing (does nothing if the sound is not played)

is_playing()[source]

Indicates whether the sound is currently being played.

Returns:

bool

True if the sound is currently being played, False otherwise.
get_analytic_signal(N=None, axis=0)[source]

Return the analytic waveform.

Parameters:

N : int, optional

Number of Fourier components. If None, set to x.shape[axis].

axis : int, optional

Axis along which to do the transformation.
Returns:

Waveform
Raises:

TypeError

If Waveform has missing samples.

See also

scipy.signal.hilbert

clip(min_value=None, max_value=None)[source]

Clip audio data according to given bound values.

See Type of Entry for details.

Parameters:

max_value : float, optional

Clipping is applied above this value.

min_value : float, optional

Clipping is applied below this value.
Raises:

UserWarning

If some coefficients are actually clipped.

Notes

Masked values can be also clipped.

astype(dtype)[source]

Cast the waveform into a given type (float, int, or complex).

Parameters:

dtype : data-type, optional

Output data type. See Type of Entry.
Returns:

nd-array

Waveform with the desired dtype.
Raises:

TypeError

If argument dtype is an unsupported data type.

UserWarning

If some coefficients are actually clipped.
copy(order='C')[source]
is_equal(other)[source]