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/ormask_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 parametermasked_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
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.
-
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
-
T
¶ Transpose of the MadArray.
-
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 fromMadArray
and adds an attributefs
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 fromMadArray
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, usedata.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.
-
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
-
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:
-
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.
-
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
-
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.