meshbuilder.Rmd

---
title: "Mesh building"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Mesh building}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Here we'll cover building a mesh from some spatial data, modifying its parameters and plotting it and the data on an interactive map.

## Load in spatial data - CSV

To load data into the mesh builder we need to make sure it's in the correct format. This can be in the form of a `SpatialPolygonsDataFrame` or a `SpatialPointsDataFrame` or just a normal `data.frame` or `tibble`. Let's load in some
data that covers the Tibetan plateau from CSV.

First we download the data from our data repository. And then load in the data using `read.csv`

```{r}
fdmr::retrieve_tutorial_data(dataset = "tibetan_lakes")
lakes_data_filepath <- fdmr::get_tutorial_datapath(dataset = "tibetan_lakes", filename = "example_lake_data.csv")
lakes_data <- read.csv(lakes_data_filepath)
```

Now let's have a look at the names of the columns in the `data.frame`.

```{r}
names(lakes_data)
```

To create the mesh we need to pass in the latitude and longitude data to the [`fmesher::fmesher::fm_mesh_2d_inla`](https://inlabru-org.github.io/fmesher/reference/fm_mesh_2d.html) function. Looking at the column names we can see that `centroid_long` and `centroid_lat` look like likely candidates. Let's have a quick look at them.

```{r}
head(lakes_data[, c("centroid_lon", "centroid_lat")])
``` 

That looks correct. By default `mesh_builder` will look for `"LAT"` and `"LONG"` columns and raise an error if it can't find them. To avoid this we can either change the names of the columns in our data or pass in the names of those columns when we call the function. 

Let's call the `mesh_builder` function and pass in the data and tell it to use `centroid_long` and `centroid_lat` as the longitude and latitude columns. As we only have have a `data.frame` here we also need to pass in the coordinate reference system we want to use. We'll use the WGS84 coordinate reference system and pass in a `proj4string`. We're now ready to launch the mesh builder app.

> **_NOTE:_**  The mesh builder may take a short time (~ 20s) to build this mesh due to its size. 

```{r eval=FALSE}
fdmr::mesh_builder(spatial_data = lakes_data, x_coord = "centroid_lon", y_coord = "centroid_lat")
``` 

## Loading data - `rds` file

In other cases we may be given an `.rds` file. Let's load in an example from our COVID-19 dataset. This is the same data we previously used in the COVID-19 tutorial.

```{r}
fdmr::retrieve_tutorial_data(dataset = "covid")
sp_data <- fdmr::load_tutorial_data(dataset = "covid", filename = "spatial_data.rds")
head(sp_data)
```

The `sp_data` object is a `SpatialPolygonsDataFrame` containing 6789 features for areas of England. This object contains all the  contains all the values we
We can build a mesh by passing `sp_data` to the `mesh_builder` function.

```{r eval=FALSE}
fdmr::mesh_builder(spatial_data = sp_data)
```
 
## Customise initial parameters

If you want to customise the initial parameters used to build the mesh you can pass those values to the `mesh_builder` function. To see what parameters you can pass to the function you can use the `args` function.

```{r}
args(fdmr::mesh_builder)
```

Now we have the spatial data loaded we can think about some initial parameters for the mesh we're going to create. We'll calculate the initial range and max edge values from our data and
pass them into the `mesh_builder` function. These values will then be used as values for the initial mesh that's created but can be changed within the app.

```{r eval=FALSE}
initial_range <- diff(range(sp_data@data[, "LONG"])) / 5
max_edge <- initial_range / 8

max_edge_fin <- c(1, 2) * max_edge
offset <- c(initial_range / 4, initial_range)
cutoff <- max_edge / 7
```

> **_NOTE:_** By default we let `fmesher` select the defaults for these values itself. If you encounter long mesh build times try using the `meshbuilder` defaults of NULL values for `max_edge` etc. 

Now we're ready to start the app.

```{r eval=FALSE}
fdmr::mesh_builder(spatial_data = sp_data, max_edge = max_edge_fin, offset = offset, cutoff = cutoff)
```

## Exporting your mesh

To export your mesh click on the Code tab and copy and paste the code used to created the mesh.