# References¶

Release: 1.1.1 October 17, 2018

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.

• 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.

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

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. nd-array
is_equal(other)[source]
T

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

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. mask : boolean nd-array Boolean array with entries set to True if the corresponding value in the object is known. ValueError If mask_type has an invalid value.
get_unknown_mask(mask_type='any')[source]

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. mask : boolean nd-array Boolean array with values set to True if the corresponding value in the object is unknown. ValueError If mask_type has an invalid value.

class madarrays.waveform.Waveform[source]

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 :
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. 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. 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: Returns: 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). List of Line kwargs
plot_mask(x_axis_label='Time (s)', y_axis_label='', **kwargs)[source]

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. 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.
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. Waveform
fade(mode='both', fade_duration=None, fade_length=None)[source]

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

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. simpleaudio.PlayObject Object useful to handle the played audio stream. 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. Waveform TypeError If Waveform has missing samples.
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. 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. nd-array Waveform with the desired dtype. TypeError If argument dtype is an unsupported data type. UserWarning If some coefficients are actually clipped.
copy(order='C')[source]
is_equal(other)[source]