Classes Package Documentation:

The root PyMP package contains all basic pymp objects such as Signal , Approx and abstract classes Dico, Atom and Block

Signal and Approximation Handles

Module signals

The main class is Signal, it can be instantiated from a numpy array using the main constructor (multichannel is allowed).

It can also be created from a file on the disk using the path as argument in the constructor

Longer Signals are handled with LongSignal objects.

class PyMP.signals.Signal(data=[], Fs=0, normalize=False, mono=False, debug_level=None)

This file defines the main class handling audio signal in the Pymp Framework.

A Signal is fairly a numpy array (called data) and a collection of attributes. Longer signals should not be loaded in memory. the LongSignal class allows to define this kind of signal, and slice it in frames overlapping or not.

Notes

For use in the PyMP framework, other methods need to be defined:

add() : adds an atom waveform to the current signal and updates energy subtract() : the opposite operation

Attributes

data	array	a numpy array containing the signal data
channel_num	int	The number of channel
length	int	The length in samples (integer) of the signal (total dimension of the numpy array is channel_num x length)
fs	int	The sampling frequency
location	str , optional	Where the original file is located on the disk
sample_width	int	Various bit format exist for wav file, this allows to handle it
is_normalized	bool	A boolean telling is the numpy array has been normalized (which here means its values are between -1 and 1)
energy	float	The energy () of the array

Methods

add(atom)

adds the contribution of the atom at the position specified by the atom.timeLocalization property

crop(startIndex=0, stopIndex=None)

cropping routine, usage is quite obvious

depad(zero_pad)

Remove zeroes from the edges WARNING: no test on the deleted data: make sure these are zeroes!

downsample(newFs)

downsampling the signal by taking only a portion of the data

get_duration()

returns the duration in seconds

normalize()

makes sure all values of the array are between -1 and 1 CAUTION: this is an amplitude normalization not an energy one

pad(zero_pad)

Pad edges with zeroes

play(prevent_too_long=True, int_type=<type 'numpy.int16'>)

EXPERIMENTAL: routine to play the signal using wave and pyaudio

plot(pltStr='b-', legend=None)

DEPRECATED plot the array using matplotlib

resample(newFs)

resampling the signal

spectrogram(wsize=512, tstep=256, order=2, log=False, ax=None, cmap=None, cbar=True)

Compute and plot the (absolute value) spectrogram of the signal

Based on a short-time fourier transform

Parameters :

wsize : int

length of the STFT window in samples (must be a multiple of 4)

tstep : int , opt

step between successive windows in samples (must be a multiple of 2, a divider of wsize and smaller than wsize/2) (default: wsize/2)

order : int, opt

1 will have the Magnitude Spectrum, 2 the Power Spectrum

log : bool, opt

Set to True for the log-spectrogram

subtract(atom, debug=0, prevent_energy_increase=True)

Subtracts the atom waveform from the signal, at the position specified by the atom.timeLocalization property if prevent_energy_increase is True, an error will be raised if subtracting the atom increases the signal’s energy

wigner_plot(window=True)

Calculate the wigner ville distribution and plots it WARNING: not sufficiently tested!

window(K)

apply a sine window on norders

write(fileOutputPath, pad=0)

Write the current signal at the specified location in wav format

This is done using the wave python library

class PyMP.signals.LongSignal(filepath, frame_size=49152, frame_duration=None, mono=False, Noverlap=0)

A class handling long audio signals

Subclass of Signal where the data is not loaded at once for memory consumptions purposes Instead, the data is sliced in frames that can be loaded later individually. very useful to process large files such as audio archives

Attributes

Module approx

The main class is Approx. It describe an approximant of a signal. This object handles MP constructed approximations. It isis quite similar in nature to the MPTK [1] Book object but allows further manipulations in python such as plotting the time frequency distribution of atoms

An approximant can be manipulated in various ways. Obviously atoms can be edited by several methods among which PyMP.Approx.add() , remove() and filterAtom()

Measure of distorsion can be estimated by the method Approx.compute_srr()

Approx objets can be exported in various formats using to_dico() , to_sparse_array() , to_array() , write_to_xml() , dumpToDisk() ,

and reversely can be recovered from these formats

A useful plotting routine, plot_tf() is provided to visualize atom distribution in the time frequency plane Also an experimental 3D plot taking the atom iteration number as a depth parameter plot_3d()

class PyMP.approx.Approx(dico=None, atoms=[], original_signal=None, length=0, Fs=0, debug_level=None)

The approx class encapsulate the approximation that is iteratively being constructed by a greed algorithm

Attributes

dico	BaseDico	the dictionary (as a BaseDico object) from which it has been constructed
atoms	list	a list of BaseAtom objets
atom_number	int	the length of the atoms list
srr	float	the Signal to Residual Ratio achieved by the approximation
original_signal	Signal	a Signal object that is the original signal
length	int	Length in samples of the time signal, same as the one of original_signal
recomposed_signal	Signal	a Signal objet for the reconstructed signal (as the weighted sum of atoms specified in the atoms list)

Methods

add(newAtom, clean=False, noWf=False)

this function adds an atom to the collection and updates the internal signal approximant

compute_srr(residual=None)

routine to compute approximation Signal To Residual ratio so far using:

rac{| ilde{x} |^2}{| ilde{x} - x |^2}

where :math:` ilde{x}` is the reconstructed signal and the original

filter_atoms(scale=0, time_interv=None, freq_interv=None)

Filter the atom list by the given criterion, returns an new approximant object

get_neighbors(atom)

returns the atom neighbor indexes

plot_3d(itStep, fig=None)

Creates a 3D Time-Frequency plot with various steps NOT WORKING below 0.99 EXPERIMENTAL

plot_tf(labelX=True, labelY=True, fontsize=12, ylim=None, patchColor=None, labelColor=None, multicolor=False, axes=None, maxAtoms=None, recenter=None, keepValues=False, french=False, Alpha=False, logF=False, cmap=None)

A time Frequency plot routine using Matplotlib

each atom of the approx is plotted in a time-frequency plane with a gray scale for amplitudes Many options are available:

• labelX : whether or not to add the Time label on the X axis
• labelY : whether or not to add the Frequency label on the Y axis
• fontsize : the label fontSize
• ylim : the frequency range of the plot
• patchColor : specify a single color for all atoms
• maxAtoms : specify a maximum number of atom to take into account. Usually atoms are ordered by decreasing amplitude due to MP rules, meaning only the most salient atoms will be plotted
• recenter : a couple of values to offset the time and frequency localization of atoms
• keepValues : use atom Amplitudes for atom colorations
• french : all labels in french
• Alpha : use transparency
• logF : frequency axis in logarithmic scale

remove(atom, position=None)

We need a routine to remove an atom , by default the last atom is removed

synthesize(method=0, forceReSynthesis=True)

function that will synthesise the approximant using the list of atoms this is mostly DEPRECATED

to_array()

Returns the approximant as an array object , key is the index of the atom and value is its amplitude

to_dico()

Returns the approximant as a sparse dictionary object , key is the index of the atom and values are atom objects

to_sparse_array()

Returns the approximant as a sparse dictionary object , key is the index of the atom and value is its amplitude

update(atom_indexes, new_weights, update_rec=False)

update atom values (e.g. after projection) and the recomposed_signal instance

Abstract MP classes

class PyMP.base.BaseAtom

Abstract Atom class interface:

To implement a new type of atom, you must derive from this class.

Attributes

nature: str		A string describing the atom type (e.g MDCT, MCLT , GaborReal) default is MDCT
length: int, optional		Sample length of the atom (default is 0)
timePosition	int	The index of the first atom sample in a signal

Methods

class PyMP.base.BaseDico

This class creates an interface that any type of dictionary should reproduce in order to be used correclty by Pursuit algorithm in this framework:

• sizes: a list of scales

• blocks: a list of blocks that handles the projection of a residual signal along with

  the selection of a projection maximum given a transform and a criteria

Attributes

Methods

get_pad()

the amount of zeroes that need to be added on the sides

class PyMP.base.BaseBlock

A block is an instance handling projections for Matching Pursuit.

Mandatory fields:

• type : the type of dictionary (e.g Gabor , MDCT , Haar ...)
• scale : the scale of the block
• residualSignal : a py_pursuit_Signal instance that describes the current residual

Mandatory methods

• update : updates the inner products table
• getMaximum : retrieve the maximum absolute value of inner products
• getMaxAtom : return a corresponding Atom instance

Methods