# Additional utilities¶

MDP offers some additional utilities of general interest
in the `mdp.utils`

module. Refer to the
API
for the full documentation and interface description.

- mdp.utils.CovarianceMatrix
This class stores an empirical covariance matrix that can be updated incrementally. A call to the

`fix`

method returns the current state of the covariance matrix, the average and the number of observations, and resets the internal data.Note that the internal sum is a standard

`__add__`

operation. We are not using any of the fancy sum algorithms to avoid round off errors when adding many numbers. If you want to contribute a`CovarianceMatrix`

class that uses such algorithms we would be happy to include it in MDP. For a start see the Python recipe by Raymond Hettinger. For a review about floating point arithmetic and its pitfalls see*What every computer scientist should know about floating-point arithmetic*by David Goldberg, ACM Computing Surveys, Vol 23, No 1, March 1991.- mdp.utils.DelayCovarianceMatrix
- This class stores an empirical covariance matrix between the signal and time delayed signal that can be updated incrementally.
- mdp.utils.MultipleCovarianceMatrices
- Container class for multiple covariance matrices to easily execute operations on all matrices at the same time.
- mdp.utils.dig_node (node)
- Crawl recursively an MDP
`Node`

looking for arrays. Return (dictionary, string), where the dictionary is: { attribute_name: (size_in_bytes, array_reference)} and string is a nice string representation of it. - mdp.utils.get_node_size (node)
- Get
`node`

total byte-size using`cPickle`

with protocol=2. (The byte-size is related the memory needed by the node). - mdp.utils.progressinfo (sequence, length, style, custom)
A fully configurable text-mode progress info box tailored to the command-line die-hards. To get a progress info box for your loops use it like this:

>>> for i in progressinfo(sequence): ... do_something(i)

You can also use it with generators, files or any other iterable object, but in this case you have to specify the total length of the sequence:

>>> for line in progressinfo(open_file, nlines): ... do_something(line)

A few examples of the available layouts:

[===================================73%==============>...................] Progress: 67%[======================================> ] 23% [02:01:28] - [00:12:37]

- mdp.utils.QuadraticForm
- Define an inhomogeneous quadratic form as
`1/2 x'Hx + f'x + c`

. This class implements the quadratic form analysis methods presented in: Berkes, P. and Wiskott, L. On the analysis and interpretation of inhomogeneous quadratic forms as receptive fields.*Neural Computation*, 18(8): 1868-1895. (2006). - mdp.utils.refcast (array, dtype)
- Cast the array to
`dtype`

only if necessary, otherwise return a reference. - mdp.utils.rotate (mat, angle, columns, units)
Rotate in-place a NxM data matrix in the plane defined by the

`columns`

when observation are stored on rows. Observations are rotated counterclockwise. This corresponds to the following matrix-multiplication for each data-point (unchanged elements omitted):[ cos(angle) -sin(angle) [ x_i ] sin(angle) cos(angle) ] * [ x_j ]

- mdp.utils.random_rot (dim, dtype)
- Return a random rotation matrix, drawn from the Haar distribution
(the only uniform distribution on SO(n)).
The algorithm is described in the paper
Stewart, G.W.,
*The efficient generation of random orthogonal matrices with an application to condition estimators*, SIAM Journal on Numerical Analysis, 17(3), pp. 403-409, 1980. For more information see this Wikipedia entry. - mdp.utils.symrand (dim_or_eigv, dtype)
- Return a random symmetric (Hermitian) matrix with eigenvalues uniformly distributed on (0,1].

## HTML Slideshows¶

The `mdp.utils`

module contains some classes and helper function to
display animated results in a Webbrowser. This works by creating an
HTML file with embedded JavaScript code, which dynamically loads
image files (the images contain the content that you want to animate
and can for example be created with matplotlib).
MDP internally uses the open source Templete templating libray,
written by David Bau.

The easiest way to create a slideshow it to use one of these two helper function:

- mdp.utils.show_image_slideshow (filenames, image_size, filename=None, title=None, **kwargs)
- Write the slideshow into a HTML file, open it in the browser and
return the file name.
`filenames`

is a list of the images files that you want to display in the slideshow.`image_size`

is a 2-tuple containing the width and height at which the images should be displayed. There are also a couple of additional arguments, which are documented in the docstring. - mdp.utils.image_slideshow (filenames, image_size, title=None, **kwargs)
- This function is similar to
`show_image_slideshow`

, but it simply returns the slideshow HTML code (including the JavaScript code) which you can then embed into your own HTML file. Note that the default slideshow CSS code is not included, but it can be accessed in`mdp.utils.IMAGE_SLIDESHOW_STYLE`

.

Note that there are also two demos in the Examples section Slideshow.

## Graph module¶

MDP contains `mdp.graph`

, a lightweight package to handle directed graphs.

- mdp.graph.Graph
Represent a directed graph. This class contains several methods to create graph structures and manipulate them, among which

`add_tree`

: Add a tree to the graph.The tree is specified with a nested list of tuple, in a LISP-like notation. The values specified in the list become the values of the single nodes. Return an equivalent nested list with the nodes instead of the values.

Example::

>>> g = mdp.graph.Graph() >>> a = b = c = d = e = None >>> nodes = g.add_tree( (a, b, (c, d ,e)) )

Graph

`g`

corresponds to this tree, with all node values being`None`

:a / \ b c / \ d e

`topological_sort`

: Perform a topological sort of the nodes.`dfs`

,`undirected_dfs`

: Perform Depth First sort.`bfs`

,`undirected_bfs`

: Perform Breadth First sort.`connected_components`

: Return a list of lists containing the nodes of all connected components of the graph.`is_weakly_connected`

: Return True if the graph is weakly connected.

- mdp.graph.GraphEdge
- Represent a graph edge and all information attached to it.
- mdp.graph.GraphNode
- Represent a graph node and all information attached to it.
- mdp.graph.recursive_map (fun, seq)
- Apply a function recursively on a sequence and all subsequences.
- mdp.graph.recursive_reduce (func, seq, *argv)
- Apply
`reduce(func, seq)`

recursively to a sequence and all its subsequences.