-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
193 lines (136 loc) · 7.38 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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
---
output: github_document
bibliography: inst/readme_references.bib
nocite: '@*'
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%")
Sys.setenv(LANG = "en")
```
# c3t : Clustering with Connectivity and Size Constraints <a href="dzt"><img src="man/figures/logo.png" align="right" height="139" alt="c3t website" /></a>
<!-- badges: start -->
[](https://github.com/atero18/c3t/actions/workflows/R-CMD-check.yaml)
[](https://github.com/atero18/c3t/actions/workflows/test-coverage.yaml)
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[](https://app.codecov.io/gh/atero18/c3t?branch=main)
<!-- badges: end -->
## 📒 Table of Contents
- [📒 Table of Contents](#-table-of-contents)
- [🪛 Installation](#-installation)
- [📍 Overview](#-overview)
- [🚀 Getting Started](#-getting-started)
- [✅ Conclusion](#-conclusion)
- [📚 References](#-references)
## 🪛 Installation
[](GPL 3)
You can install the development version of `c3t` from [GitHub](https://github.com/atero18/c3t) with:
``` {r install_c3t, eval=FALSE}
if (!require(devtools, quietly = TRUE))
install.packages("devtools")
devtools::install_github("atero18/c3t")
```
## 📍 Overview
[](https://lifecycle.r-lib.org/articles/stages.html#experimental)
The `c3t` package in R is a powerful tool for regionalization and clustering tasks with various constraints. It offers a range of functions to facilitate these tasks, and its capabilities include:
### 1. Hierarchical Regionalization (AHR)
- Solve regionalization problems while respecting constraints such as minimum and maximum size.
- Apply a modified [Agglomerative Hierarchical Clustering](https://www.wikiwand.com/en/Hierarchical_clustering#introduction) (AHC) algorithm.
- Choose from various linkage methods to define cluster proximity.
- Apply constraints on the merging process to ensure specific criteria are met.
### 2. Improving Feasible Solutions
- Enhance feasible solutions while preserving constraints.
- Optimize solutions according to user-defined criteria.
- Explore different linkage methods for clustering.
### 3. Addressing Unfeasible Solutions
- Convert unfeasible solutions into feasible ones.
- Adjust cluster sizes to meet constraints.
- Maintain contiguity and other specified criteria.
### 4. Flexible Parameter Customization
- Choose distance measures, such as Euclidean distance.
- Set minimum and maximum size constraints for regions.
- Specify initial partitions for improved results.
- Apply various criteria for evaluation, including Caliński-Harabasz index (CHI) [@calinski_dendrite_1974].
### 5. Versatility in Constraints
- Customize constraints based on your specific requirements.
- Ensure contiguity and size constraints are met.
- Explore different fusion constraint modes.
## 🚀 Getting Started
Before we begin, ensure you have the `c3t` package and the required dependencies installed. You can do this by running the following commands:
```{r setup, message=FALSE, warning=FALSE}
# load the c3t package
library(c3t)
```
### Creating a Grid
Let's start by creating a fictitious grid, which will serve as an example for using different functions. We can generate this grid using the `gen_grid` function. You can specify the number of individuals on the grid, empty cells, and metropolitan areas.
```{r grid_creation}
set.seed(123L)
x <- 4L
y <- 5L
nbIndividuals <- 100L
nbEmptyZones <- 3L
nbMetropolises <- 2L
nbVariablesQuant <- 2L
grid <- gen_grid(x, y, nbIndividuals = nbIndividuals,
nbMinEmptyZones = nbEmptyZones,
nbMetropolises = nbMetropolises,
nbQuantitatives = nbVariablesQuant)
data <- grid$context
individuals <- grid$repartition$nbIndividuals
contiguity <- grid$contiguity
```
### Hierarchical Regionalization (AHR)
To address regionalization problems with constraints like minimum and maximum size, you can use the `AHR` function. This function applies a modified Hierarchical Agglomerative Clustering (HAC) algorithm while respecting contiguity and size constraints.
```{r AHR}
resAHR <- AHR(contiguity = contiguity,
d = "euclidean", data = data,
sizes = individuals,
m = 5.0, M = 40.0,
criteria = "CHI",
fusionConstraints = available_fusion_constraints(),
fusionConstraintModes = available_fusion_modes(),
parallel = FALSE)
```
The function returns a list of feasible solutions, and you can select the one that best suits your needs.
### Improving Feasible Solutions
Once you have a feasible solution, you can further enhance it while preserving constraints using the `enhance_feasible` function.
```{r enchancement}
resEnhance <-
enhance_feasible(regionalisation = resAHR$results$partition[[1L]],
contiguity = contiguity,
d = "euclidean", data = data,
sizes = individuals,
m = 5.0, M = 40.0,
enhanceCriteria = c("AHC", "CHI"),
linkages = c("single", "complete"),
parallel = FALSE,
verbose = TRUE)
```
This function allows you to improve your solution according to specified criteria.
### Addressing Unfeasible Solutions
In cases where a feasible solution cannot be obtained, the `resolve_unfeasible` function attempts to provide a feasible solution from an unfeasible one.
```{r resolve_unfeasible}
unfeasibleReg <- c(1L, 2L, 3L, 2L, 2L, 2L, 2L, 2L, 2L, 4L,
4L, 2L, 4L, 4L, 4L, 4L, 4L, 4L, 4L, 4L)
resolution <- resolve_unfeasible(contiguity = contiguity,
sizes = individuals,
data = data,
d = "euclidean", m = 5.0, M = 40.0,
regionalisation = unfeasibleReg,
verbose = TRUE)
```
This function aims to transform an unfeasible solution into a feasible one while respecting constraints.
## ✅ Conclusion
The `c3t` package offers a variety of tools for regionalization and clustering with constraints. Explore the documentation and experiment with different functions to suit your specific use case.
For more details on each function and available options, refer to the package documentation :
```{r ask_help_package, eval=FALSE}
help(package = "c3t")
```
For any issue or feedback please go to the [Issue page](https://github.com/atero18/c3t/issues) of the repository. You can as well discuss about the project in the [Discussion page](https://github.com/atero18/c3t/discussions).
Please note that this project is released with a [Contributor Code of Conduct](https://atero18.github.io/c3t/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.
## 📚 References
<div id="refs"></div>