Arguments
This function has \(11\) arguments,
which can be divided into four categories:
1. specifications of the dataset
hotspots |
the object that contains the dataset |
lon |
the name of the longitude column |
lat |
the name of the latitude column |
obsTime |
the name of the observed time column |
The first four arguments are pretty straight forward, you only need
to provide the dataset object and its corresponding column names.
2. specifications of the parameters of the clustering algorithm
activeTime |
the time tolerance |
adjDist |
the distance tolerance |
minPts |
the minimum number of hot spots |
minTime |
the minimum length of time |
These four arguments control the clustering process.
activeTime could be interpreted as the time
a fire can stay smouldering but undetectable by satellite before flaring
up again. For example, if activeTime \(= 24\), then the time tolerance is \(24\) time indexes.
adjDist could be interpreted as the maximum
intra-cluster distance between a hot spot and its nearest hot
spot. For example, if adjDist \(= 3\), then the distance tolerance is \(3\) km. However, in some very special
cases, the intra-cluster distance between a hot spot and its nearest hot
spot will exceed this threshold. You can learn more about this
parameter and the algorithm by using the
help(hotspot_cluster) function.
minPts is the minimum number of hot spots in
a cluster. For example, if minPts is \(4\), then any cluster with less than \(4\) hot spots will be treated as
noise.
minTime is the minimum length of time of a
cluster. For example, if minTime is \(3\), then any cluster lasts shorter than
\(3\) time indexes will be treated as
noise.
In practice, we usually don’t have knowledge about the parameters
activeTime and adjDist, but in general, the
number of clusters will decrease when you increase these two
parameters.
Comparing the clustering results under different settings is an
available method to determine these two parameters. We will show how to
do this in the section Additional topic: Choice
of parameters.
In terms of minPts and minTime, they depend
on your personal preference of noise reduction. And, the number of
clusters will often decrease when you increase these two parameters.
A sensible choice of these two parameters is minPts
\(\in [3,10]\) and minTime
\(\in [1~hour, 12~hours]\)
3. specification of the calculation of the ignition points
ignitionCenter |
method of the calculation of the ignition points |
For a cluster, if ignitionCenter is “mean”, the centroid
of the earliest hot spots will be used as the ignition point, if
ignitionCenter is “median”, the median longitude and the
median latitude of these hot spots will be used as the ignition
point.
In usual, there is no significant difference between these two
methods, so we recommend to set
ignitionCenter = "mean".
Usage
With specifications of all the arguments, the
hotspot_cluster() can be used as below. Generally, you need
to use an object to catch the return.
result <- hotspot_cluster(hotspots = hotspots,
lon = "lon",
lat = "lat",
obsTime = "obsTime",
activeTime = 24,
adjDist = 3000,
minPts = 4,
minTime = 3,
ignitionCenter = "mean",
timeUnit = "h",
timeStep = 1)
#>
#> ──────────────────────────────── SPOTOROO 0.1.4 ────────────────────────────────
#>
#> ── Calling Core Function : `hotspot_cluster()` ──
#>
#> ── "1" time index = 1 hour
#> ✔ Transform observed time → time indexes
#> ℹ 970 time indexes found
#>
#> ── activeTime = 24 time indexes | adjDist = 3000 meters
#> ✔ Cluster
#> ℹ 16 clusters found (including noise)
#>
#> ── minPts = 4 hot spots | minTime = 3 time indexes
#> ✔ Handle noise
#> ℹ 6 clusters left
#> ℹ noise proportion : 0.935 %
#>
#> ── ignitionCenter = "mean"
#> ✔ Compute ignition points for clusters
#> ℹ average hot spots : 176.7
#> ℹ average duration : 131.9 hours
#>
#> ── Time taken = 0 mins 1 sec for 1070 hot spots
#> ℹ 0.001 secs per hot spot
#>
#> ────────────────────────────────────────────────────────────────────────────────
Messages produced by this function tell you some important
information of the clustering results such as the number of discrete
time indexes, the number of clusters and the proportion of noise. If you
would like to silent this function, you could wrap this function with
the suppressMessages() function like the example given
below.
# NOT RUN
suppressMessages(hotspot_cluster())
Returns
The hotspot_cluster() function returns a
spotoroo object, which is actually a list
contains a data.frame called hotpsots, a
data.frame called ignition and a
list called setting.
If you evaluate the result or print it, you will get a
concise description of the clustering results. Here, according to the
output, we know there are \(6\)
clusters in the clustering results.
result
#> ℹ spotoroo object: 6 clusters | 1070 hot spots (including noise points)
You can access these two data.frames in the usual
way.
head(result$hotspots, 2)
#> lon lat obsTime timeID membership noise distToIgnition
#> 1 147.46 -37.46000 2020-02-01 05:20:00 809 -1 TRUE 0
#> 2 146.48 -37.93999 2020-01-02 06:30:00 90 -1 TRUE 0
#> distToIgnitionUnit timeFromIgnition timeFromIgnitionUnit
#> 1 m 0 hours h
#> 2 m 0 hours h
head(result$ignition, 2)
#> membership lon lat obsTime timeID obsInCluster
#> 1 1 149.30 -37.77 2019-12-29 13:10:00 1 146
#> 2 2 146.72 -36.84 2020-01-08 01:40:00 229 165
#> clusterTimeLen clusterTimeLenUnit
#> 1 116.1667 hours h
#> 2 148.3333 hours h
The hotspots dataset contains information of each hot
spot. Particularly, the membership column is the membership
label column. \(-1\) represents
noise.
The ignition dataset contains information of each
cluster. Similarly, the membership column is the membership
label column. And the lon and lat are the
coordinate information of the ignition points.
Additional topic: Choice of parameters
In principal, the parameters activeTime and
adjDist are determined using the professional knowledge of
fire behaviour, but in practice, we generally don’t know much about
them.
In the rest of the section, we will show one of the methods to choose
proper values for these two parameters.
We first set minPts = 4 and minTime = 3.
You could set different values for minPts and
minTime if you like.
We then could do a grid search for activeTime and
adjDist in a sensible range. Here, we set
adjDist \(\in\)
[500,1000,1500,2000,2500,3000,3500,4000] and
activeTime \(\in\)
[6,12,18,24,30,36,42,48]. For each pair of
activeTime and adjDist, we record the
proportion of noise as the metric for comparison.
The following code does the calculation. It may takes around 10
minutes to run. You could have a try if you like.
# NOT RUN
# NOTICE: MAY TAKE AROUND 10 MINS TO RUN THIS CODE BLOCK
noise_prop <- c()
for (adjDist in seq(500, 4000, 500)) {
for (activeTime in seq(6, 48, 6)) {
result <- suppressMessages(hotspot_cluster(hotspots = hotspots,
lon = "lon",
lat = "lat",
obsTime = "obsTime",
activeTime = activeTime,
adjDist = adjDist,
minPts = 4,
minTime = 3,
ignitionCenter = "mean",
timeUnit = "h",
timeStep = 1))
noise_prop <- c(noise_prop, mean(result$hotspots$noise))
}
}
tab <- expand.grid(activeTime = seq(6, 48, 6),
adjDist = seq(500, 4000, 500))
tab$noise_prop <- noise_prop
With the proportion of noise, we could make two line plots to reveal
the relationships between proportion of noise, adjDist and
activeTime.
It works like the scree plot used in
principal component analysis. We want to keep clusters separate without
introducing too much noise.
In the first plot, most of the significant drops of proportion of
noise are observed when adjDist less than 2500 metres.
Therefore, adjDist = 2500 is a reasonable choice.
ggplot(tab) +
geom_line(aes(adjDist, noise_prop, color = as.factor(activeTime))) +
ylab("Noise Propotion") +
labs(col = "activeTime") +
theme_minimal() +
scale_x_continuous(breaks = seq(500, 4000, 500))
In the second plot, most of the significant drops of proportion of
noise are observed when activeTime less than 24 hours.
Therefore, activeTime = 24 is a reasonable choice.
ggplot(tab) +
geom_line(aes(activeTime, noise_prop, color = as.factor(adjDist))) +
ylab("Noise Propotion") +
labs(col = "adjDist") +
theme_minimal() +
scale_x_continuous(breaks = seq(6, 48, 6))
