### GraSP Tutorial

###### Fri, 1 Sep 2017

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.

Category: Graph Signal Processing Tagged: