-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathREADME.Rmd
164 lines (131 loc) · 6.22 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
---
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 = "man/figures/README-"
)
```
[](https://github.com/mpadge/spatialcluster/actions?query=workflow%3AR-CMD-check)
[](http://www.repostatus.org/#wip)
[](https://codecov.io/gh/mpadge/spatialcluster)
# spatialcluster
An **R** package for spatially-constrained clustering using either distance or
covariance matrices. "*Spatially-constrained*" means that the data from which
clusters are to be formed also map on to spatial coordinates, and the
constraint is that clusters must be spatially contiguous.
The package includes both an implementation of the
REDCAP collection of efficient yet approximate algorithms described in [D. Guo's
2008 paper, "Regionalization with dynamically constrained agglomerative
clustering and
partitioning."](https://www.tandfonline.com/doi/abs/10.1080/13658810701674970)
(pdf available
[here](https://pdfs.semanticscholar.org/ead1/7df8aaa1aed0e433b3ae1ec1ec5c7e785b2b.pdf)),
with extension to covariance matrices, and a new technique for computing
clusters using complete data sets. The package is also designed to analyse
matrices of spatial interactions (counts, densities) between sets of origin and
destination points. The spatial structure of interaction matrices is able to be
statistically analysed to yield both global statistics for the overall spatial
structure, and local statistics for individual clusters.
## Installation
The easiest way to install `spatialcluster` is be enabling the [corresponding
`r-universe`](https://mpadge.r-universe.dev/):
```{r r-univ, eval = FALSE}
options (repos = c (
mpadge = "https://mpadge.r-universe.dev",
CRAN = "https://cloud.r-project.org"
))
```
The package can then be installed as usual with,
```{r install, eval = FALSE}
install.packges ("spatialcluster")
```
Alternatively, the package can also be installed using any of the following
options:
```{r gh-installation, eval = FALSE}
# install.packages("remotes")
remotes::install_git ("https://codeberg.org/mpadge/spatialcluster")
remotes::install_git ("https://git.sr.ht/~mpadge/spatialcluster")
remotes::install_bitbucket ("mpadge/spatialcluster")
remotes::install_gitlab ("mpadge/spatialcluster")
remotes::install_github ("mpadge/spatialcluster")
```
## Usage
The two main functions, `scl_redcap()` and `scl_full()`, implement different
algorithms for spatial clustering. The former implements the REDCAP collection
of efficient yet approximate algorithms described in [D. Guo's 2008 paper,
"Regionalization with dynamically constrained agglomerative clustering and
partitioning."](https://www.tandfonline.com/doi/abs/10.1080/13658810701674970)
(pdf available
[here](https://pdfs.semanticscholar.org/ead1/7df8aaa1aed0e433b3ae1ec1ec5c7e785b2b.pdf)),
with extension here to apply clustering to covariance matrices. These
algorithms are computationally efficient yet generate only *approximate*
estimates of underlying clusters. The second function, `scl_full()`, trades
computational efficiency for accuracy, through generating clustering schemes
using all available data.
In short:
- `scl_full()` should always be preferred as long as it returns results within
a reasonable amount of time
- `scl_redcap()` should be used only where data are too large for `scl_full()`
to be run in a reasonable time.
For clustering a group of `n` points, both of these functions require three
main arguments:
1. A rectangular matrix of spatial coordinates of points to be clustered (`n`
rows; at least 2 columns);
2. An `n`-by-`n` square matrix quantifying relationships between those points;
3. A single value (`ncl`) specifying the desired number of clusters.
The following code demonstrates usage with randomly-generated data:
```{r}
set.seed (1)
n <- 100
xy <- matrix (runif (2 * n), ncol = 2)
dmat <- matrix (runif (n^2), ncol = n)
```
The load the package and call the function:
```{r full-single, echo = TRUE, eval = TRUE}
library (spatialcluster)
scl <- scl_full (xy, dmat, ncl = 8)
plot (scl)
```
Both functions return a `list` with the following components:
```{r list-components}
names (scl)
```
- `tree` details distances and cluster numbers for all pairwise comparisons
between objects.
- `merges` details increasing distances at which each pair of objects was
merged into a single cluster.
- `ord` provides the order of the merges (for `scl_full()` only).
- `nodes` records the spatial coordinates of each point (node) of the input
data.
- `pars` retains the parameters used to call the clustering function.
- `statsitics` returns the clustering statistics, both for individual clusters
and an overall global statistic for the clustering scheme as a whole.
See the "_Get Started_" vignette for more details.
## A Cautionary Note
The following plot compares the results of applying four different clustering
algorithms to the same data.
```{r cautionary, eval = TRUE, fig.width = 7, fig.height = 7}
library (ggplot2)
library (gridExtra)
scl <- scl_full (xy, dmat, ncl = 8, linkage = "single")
p1 <- plot (scl) + ggtitle ("full-single")
scl <- scl_redcap (xy, dmat, ncl = 8, linkage = "single")
p2 <- plot (scl) + ggtitle ("redcap-single")
scl <- scl_redcap (xy, dmat, ncl = 8, linkage = "average")
p3 <- plot (scl) + ggtitle ("redcap-average")
scl <- scl_redcap (xy, dmat, ncl = 8, linkage = "complete")
p4 <- plot (scl) + ggtitle ("redcap-complete")
grid.arrange (p1, p2, p3, p4, ncol = 2)
```
This example illustrates the universal danger in all clustering algorithms: they
can not fail to produce results, even when the data fed to them are definitely
devoid of any information as in this example. Clustering algorithms should only
be applied to reflect a very specific hypothesis for why data should be
clustered in the first place; spatial clustering algorithms should only be
applied to reflect two very specific hypothesis for (i) why data should be
clustered at all, and (ii) why those clusters should manifest a spatial
pattern.