README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "images/"
)
```

# speCluster

[![Project Status: WIP - Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](http://www.repostatus.org/badges/latest/wip.svg)](http://www.repostatus.org/#wip)

This package wraps the code at: 

https://github.com/cont-limno/SpectralClustering4Regions

## Installation

You can install speCluster from github with:

```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("cont-limno/speCluster")
```

## Usage

### Load package

```{r eval=TRUE}
library(speCluster)
```

### Read data

```{r ,eval=TRUE}
dt     <- read.csv("data-raw/dataTerrFW.csv", header = T)
coords <- read.csv("data-raw/latLong18876.csv", header = T)
```

### Prep Input

Here we create a data matrix `dt` where each row is an observation and each column is a variable. In this example, we subset a larger matrix to focus on the US State of Missouri. Uninformative (constant) variables are removed with `rm_constant_columns`. Next, we create a constraint matrix that incorporates information on the spatial dependence among observations.

```{r ,eval=TRUE}
# Create data matrix
in_state <- as.character(dt$hu12_states) == "MO"
dt <- dt[in_state, -c(1,2)]
dt <- as.matrix(rm_constant_columns(dt))
colnames(dt) <- NULL

# Create constraint matrix
coords <- as.matrix(coords[in_state,])
colnames(coords) <- NULL
nb <- spdep::dnearneigh(coords, 0, 0.192)
nb <- nb_collapse(nb)
cmat <- neighborMatrix(nb, conFactor = 1)
```

### Generate Clusters

```{r }
results <- speCluster(data = dt, conMatrix = cmat, 
                      cluster.number = 10)
summary(results)
results$SS
head(results$clusters)
mapping(lat = coords[,1], long = coords[,2],
         clusters = results$clusters)

```

### Generate Hierarchical Clusters

```{r }
results <- hspeCluster(data = dt, conMatrix = cmat, 
                      cluster.number = 10)
summary(results)
results$SS
head(results$clusters)
mapping(lat = coords[,1], long = coords[,2],
         clusters = results$clusters[,ncol(results$clusters)])

```

## Citation

_Creating Multithemed Ecological Regions for Macroscale Ecology_ ([Cheruvelil et al. 2017](https://dx.doi.org/10.1002/ece3.2884))