README.Rmd

---
output:
  md_document:
    variant: gfm
---
```{r Setup, include=FALSE}
library(gasper)
knitr::opts_chunk$set(
  collapse = TRUE,
  fig.align = "center",
  out.width = '50%',
  dpi = 150,
  comment = "#>"
)
```
# gasper

[![CRAN\_Status\_Badge](https://www.r-pkg.org/badges/version/gasper)](https://cran.r-project.org/package=gasper)
![CRAN Downloads](https://cranlogs.r-pkg.org/badges/gasper)
![CRAN Downloads](https://cranlogs.r-pkg.org/badges/grand-total/gasper)

Graph signal processing in R.
```{r,echo=FALSE}
f <- exp(-( (rlogo$xy[,1]-1)^2/2+(rlogo$xy[,2]-4)^2/2))
plot_signal(rlogo,f,size = 3)
```

## Download and Install

Install the devtools package if you haven't already.
```{r, eval=FALSE}
install.packages("devtools")
```

To install the development package, type the following at the R command line:
```{r, eval=FALSE}
devtools::install_github("fabnavarro/gasper")
library(gasper)
```

To install the CRAN version of the package, type the following:
```{r, eval=FALSE}
install.packages("gasper")
```

To obtain the complete list of package functions, simply type 
```{r, eval=FALSE}
help(package = "gasper")
```

## Getting Started

See the [package vignette](https://fnavarro.perso.math.cnrs.fr/rpackage/gasper_vignette.pdf) or [documentation](https://fnavarro.perso.math.cnrs.fr/rpackage/gasper.pdf) for more details.
You could also build and see the vignette associated with the package using the following lines of code
```{r, eval=FALSE}
devtools::install_github("fabnavarro/gasper", build_vignettes = TRUE)
library(gasper)
```

Then, to view the vignette
```{r, eval=FALSE}
vignette("gasper_vignette")
```

For an illustration of the features of the package, you can also refer to the following repo [SGWT-SURE](https://github.com/fabnavarro/SGWT-SURE) which provides an effective generalization of the Stein Unbiased Risk Estimate (SURE) for signal denoising/regression on graphs using Spectral Graph Wavelet Transform.

## Interface to the SuiteSparse Matrix Collection

The package also provides an interface to the SuiteSparse Matrix Collection, which is a large and actively growing set of sparse matrix benchmarks gathered from a broad spectrum of applications (for details see https://sparse.tamu.edu/).

Included in the package, the `SuiteSparseData` dataset contains data from the SuiteSparse Matrix Collection. The structure of this dataframe mirrors the structure presented on the SuiteSparse Matrix Collection website, allowing users to query and explore the dataset directly within R.
```{r, include=FALSE, eval=FALSE}
DT::datatable(SuiteSparseData, options = list(pageLength = 20, dom = 't'))
```

Here is a sample of the `SuiteSparseData` dataset, showing the first 15 rows of the table:
```{r}
SuiteSparseData_subset <- head(SuiteSparseData, 15)
```

```{r, echo=FALSE}
# table <- knitr::kable(SuiteSparseData_subset, 
#                format = "html", 
#                caption = "First 20 Rows of SuiteSparseData")
# styled_table <- kableExtra::kable_styling(table, 
#                               full_width = FALSE, 
#                               bootstrap_options = c("striped", "hover"))
# 
# styled_table
knitr::kable(SuiteSparseData_subset, format = "markdown")
```

Here's an example to retrieve all undirected weighted graphs with the number of columns and rows between 50 and 150:
```{r}
filtered_mat <- SuiteSparseData[SuiteSparseData$Kind == "Undirected Weighted Graph" & 
                                SuiteSparseData$Rows >= 50 & SuiteSparseData$Rows <= 150 &
                                SuiteSparseData$Cols >= 50 & SuiteSparseData$Cols <= 150, ]
```

```{r, echo=FALSE}
knitr::kable(filtered_mat, format = "markdown")
```

The `download_graph` function allows to download a test matrix from this collection. For example:
```{r, message=FALSE}
matrixname <- "usroads-48"
groupname <- "Gleich"
download_graph(matrixname,groupname)
attributes(`usroads-48`)
```

`usroads-48` is composed of the sparse matrix `sA` (in compressed sparse column format), coordinates `xy` (if present, in a data.frame), `dim` the number of rows, columns and numerically nonzero elements and `temp` path to the temporary directory where the matrix and downloaded files (including singular values if requested) are stored. Information about the matrix can be display via `file.show(paste(`usroads-48`$temp,"usroads-48",sep=""))` or in the console:
```{r}
cat(readLines(paste(`usroads-48`$temp,"usroads-48",sep="")), sep = "\n")
```
`download_graph` function has an optional svd argument; setting "svd = TRUE" downloads a ".mat" file containing the singular values of the matrix, if available. To access the temporary folder use, for example, 
```{r}
list.files(`usroads-48`$temp)
```

In addition, the `get_graph_info` function allows to retrieve detailed information about the matrix from the SuiteSparse Matrix Collection website (`rvest` package needs to be installed to use it). This function extracts and formats various properties and metadata associated with the matrix (i.e., it fetches the two to three tables with "MatrixInformation," "MatrixProperties" and, if available, "SVDStatistics"), providing a convenient way to access this overview of the graph directly within R. Here is how you can use it:
```{r, eval=FALSE}
graph_info <- get_graph_info(matrixname, groupname)
graph_info
```

```{r, echo=F}
graph_info <- get_graph_info(matrixname, groupname)
knitr::kables(
  list(knitr::kable(graph_info[[1]], valign = 't'),
    knitr::kable(graph_info[[2]], valign = 't')))
```

The `download_graph` function has an optional argument `add_info` which, when set to `TRUE`, automatically calls `get_graph_info` and appends the retrieved information to the output of `download_graph`. This makes it easy to get both the graph data and its associated information in a single function call.
```{r, eval=FALSE}
downloaded_graph <- download_graph(matrixname, groupname, add_info = TRUE)
downloaded_graph$info
```

It is also possible to plot a (planar) graph and plot signals defined on top of it. For example:
```{r, fig.show='hold'}
f <- sin(rnorm(nrow(`usroads-48`$xy)))
plot_graph(`usroads-48`, size = 0.05)
plot_signal(`usroads-48`, f, size = f/4)
```

In cases where these coordinates are not supplied, `plot_graph` employs simple spectral graph embedding to calculate some node coordinates (nodes that are connected or share structural similarities in the graph are placed close to each other in the spectral drawing). This is done using the function `spectral_coords`, which computes the spectral coordinates based on the eigenvectors associated with the smallest non-zero eigenvalues of the graph's Laplacian.
```{r, message=FALSE,fig.show='hold'}
matrixname <- "delaunay_n10"
groupname <- "DIMACS10"
download_graph(matrixname,groupname)
attributes(delaunay_n10)
plot_graph(delaunay_n10)
plot_signal(delaunay_n10,
            cos(1:nrow(delaunay_n10$sA)))
```

```{r, eval=FALSE}
graph_info <- get_graph_info(matrixname, groupname)
graph_info
```

```{r, echo=FALSE}
graph_info <- get_graph_info(matrixname, groupname)
knitr::kables(
  list(knitr::kable(graph_info[[2]], valign = 't'),
    knitr::kable(graph_info[[3]], valign = 't')))
```