Table Of Contents

Previous topic

MP routines Documentation

Next topic

Union of MDCT basis Classes documentation :

This Page

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, fast_create=False)

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.


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


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



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


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


downsampling the signal by taking only a portion of the data


returns the duration in seconds


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


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


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

Returns :

The Spectrogram matrix :

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


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


apply a sine window on norders

write(fileOutputPath, normalize=False, 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


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, fast_create=False)

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


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)


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

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


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


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


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


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


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.


nature: str A string describing the atom type (e.g MDCT, MCLT , GaborReal) default is MDCT


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 BaseBlock that handles the projection of a residual signal along with

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




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