GraSP Tutorial

2017-09-01T00:00:00-07:00

The Graph Signal Processing toolbox GraSP can be found here, and here (both are GIT repositories with the same content).

Installation

Before being able to use the toolbox, several third party tools need to be downloaded and made available to Matlab. To do that, go to the grasp root folder and run the command:

grasp_install

Then setup Matlab path to make the GraSP toolbox available to Matlab:

grasp_start

You are know ready to use the toolbox.

Getting Started

First, we need a graph to perform graph signal processing on. You can use the provided functions in Graphs/ or any structure you have (we will come back to that later). For example, a random sampling in 2D square, with edges weighted by a Gaussian kernel of the Euclidean distance, is obtained using grasp_plane_rnd:

g = grasp_plane_rnd(100);

The structure g contains now several fields describing this graph. To show this graph, use the grasp_show_graph function:

grasp_show_graph(gca, g);

The first signal we use in this tutorial is a delta signal obtained by grasp_delta:

delta_1 = grasp_delta(g, 1);

We can show it on the previous figure using:

grasp_show_graph(gca, g, 'node_values', delta_1);

We observe in the command above a first way of giving optional parameters to functions in the toolbox, using pairs of name and value. The other way of achieving the same goal is through a Matlab structure:

options = { 'node_values', delta_1 };
grasp_show_graph(gca, g, options);

We will use the first form in this tutorial, but sometime the second form is more efficient.

The next step is to construct the graph Fourier transform. This is done by computing the eigendecomposition of a matrix, and performed by grasp_eigendecomposition:

g = grasp_eigendecomposition(g);

This completes the data structure g with the graph Fourier transform. To perform the GFT on the delta signal we defined, we can use the grasp_fourier function:

delta_1_hat = grasp_fourier(g, delta_1);

Components of delta_1_hat are the Fourier components of the signal delta_1 ordered by increasing frequency.

Now that the GFT is defined, we can compute a more complex signal using grasp_heat_kernel:

heat = grasp_heat_kernel(g);

This signal is a low pass signal. We can then convolve the two signals using:

conv_sig = grasp_convolution(heat, delta_1);

You can find more operators in the Operators/ folder.

Graphs

We saw in the previous section that we can build a graph using the function in the folder Graphs/. Another way is to construct the GraSP structure from the adjacency matrix of the graph. If A is the adjacency matrix, then we just have to do:

g = grasp_struct();
g.A = A;

Showing the graph g on a figure then involves the field layout of the structure g. This a two column array with as many rows as vertices in the graph. The first column corresponds to the horizontal coordinate, and the second to the vertical coordinate. Coordinates are between 0 and 10. If you have access to a meaningful layout, you can use it to compute g.layout. Otherwise, use grasp_layout to do this computation automatically:

g.layout = grasp_layout(g);

This function requires GraphViz to be installed on your computer.

Manipulating graphs

You will find several functions in Graphs/Tools to refine a graph, such as computing Gaussian weights (grasp_adjacency_gaussian), thresholding edges (grasp_adjacency_thresh) or performing KNN selection of edges (grasp_adjacency_knn).

Import/Export

You can export a graph structure (adjacency matrix and layout) in two CSV files (one for the vertices and one for the edges) for use outside matlab using the function grasp_exportcsv:

grasp_exportcsv(g, 'vertices.csv', 'edges.csv');

This structure can then be imported back into Matlab using grasp_importcsv, used in another software, or used with the LaTeX package provided with GraSP (commands displaying graphs and matrices).

If you have a CSV file with the adjacency matrix and a layout, you can also use grasp_importcsv to import the graph into GraSP.

Finally, GraSP provides function to convert structure from (grasp_from_gspbox) and to (grasp_to_gspbox) the toolbox GSPbox, making them compatible with one another.

Plotting Functions

We saw the most useful function grasp_show_graph in action earlier. This function has several parameters to control how the figure is rendered. We invite you to read its documentation and experiment. Two of interest are node_values seen earlier, and show_edges that should be set to false when the number of edges is high to speed up the function.

Based on this function, we have also grasp_show_fouriermodes displaying all (or some) Fourier modes on the same figure within several subaxes.

Next, we have grasp_show_matrix that improves upon the builtin function imshow and giving control over the color scale or the size of the pixels to plot a matrix.

We also have several functions to better control figures and axes. First, Matlab offers the possibility of having titles to figure that differ from the standard Figure x where x is an integer. We use that possibility and wrap everything nicely in grasp_open_figurename.

Also, to have better control over subaxes, compared to the builtin function subplot, we provide grasp_subaxis that controls margin between axes allowing for denser figures. The function grasp_subaxis_matrix_dimensions gives also the ideal number of rows and columns given a total number of figures to maximize the size of the subaxes. Typical usage of this functions is:

[nb_rows, nb_cols] = grasp_subaxis_matrix_dimensions(n)
...
grasp_subaxis(nb_rows, nb_cols, i);
...

In Util/, the function grasp_set_blue_red_colormap will switch the color scale to a blue - white - red one. This is especially useful when the color scale (color_scale of grasp_show_graph and grasp_show_matrix) is symmetric about 0 (from -x to +x) such that 0 is white. Color intensity correspond to how big the value is, and the actual color corresponds to negative or positive values.