#### Previous topic

MP routines Documentation

#### Next topic

Union of MDCT basis Classes documentation :

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

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

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!

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

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

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

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

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

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

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

Attributes

Methods

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