Calculating home-range overlaps with amt

Johannes Signer and John Fieberg

2023-03-28

Background

Several different indices have been proposed for measuring home-range overlap. These are reviewed by Fieberg & Kochanny (2005). There are two general approaches used to calculate home-range overlap: 1) calculate the percentage overlap at a given isopleth level (this works for geometric and probabilistic home ranges) or 2) calculate an index of similarity between the two utilization distributions (UD; this only works for probabilistic estimators)1.

Implementation in amt

amt currently implements all methods to calculate overlaps that were reviewed by Fieberg and Kochany (2005). These are:

These overlap indices can be calculated with the function hr_overlap. The type of overlap measure an be controlled with the argument type.

All of these estimators can be calculated for a given home-range level (i.e., using conditional UDs). Whether or not a conditional overlap is desired or not, can be controlled with the argument conditional. For hr, the argument conditional has no effect and the isopleths used for home-range estimation will always be used for the overlap calculation.

The function hr_overlap() can also be provided with a list of home-range estimates in situations when overlap between many different instances are required. Currently, there are three options for calculating overlap among multiple instances: which = "all" calculates overlap for each pair of home ranges, which = "one_to_all" calculates overlap between the first element in the list and all others, and which = "consecutive" will calculate overlap between consecutive elements in the list.

Examples

First we need to load the required packages:

library(amt)
library(ggplot2)
library(tidygraph)
library(ggraph)

Two instances

We will use tracking data from Fishers from New York State, USA.

leroy <- amt_fisher |> filter(name == "Leroy")
lupe <- amt_fisher |> filter(name == "Lupe")

Create a template raster for the KDE

trast <- make_trast(amt_fisher |> filter(name %in% c("Leroy", "Lupe")), res = 50)

And estimate home-ranges for both fishers

hr_leroy <- hr_kde(leroy, trast = trast, levels = c(0.5, 0.9))
hr_lupe <- hr_kde(lupe, trast = trast, levels = c(0.5, 0.9))

hr and phr are directional, this means the order matters. For all other overlap measures the order does not matter.

hr_overlap(hr_leroy, hr_lupe, type = "hr") 
## # A tibble: 2 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1    0.9   0.310
## 2    0.5   0.192
hr_overlap(hr_lupe, hr_leroy, type = "hr")
## # A tibble: 2 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1    0.9   0.986
## 2    0.5   0.577

By default conditional = FALSE and the full UD is used.

hr_overlap(hr_leroy, hr_lupe, type = "phr", conditional = FALSE) 
## # A tibble: 1 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1      1       1
hr_overlap(hr_lupe, hr_leroy, type = "phr", conditional = FALSE)
## # A tibble: 1 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1      1   0.786

If we set conditional = TRUE, the overlap is measured at home-range levels that were specified during estimation.

hr_overlap(hr_leroy, hr_lupe, type = "phr", conditional = TRUE) 
## # A tibble: 2 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1    0.5   0.577
## 2    0.9   0.993
hr_overlap(hr_lupe, hr_leroy, type = "phr", conditional = TRUE)
## # A tibble: 2 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1    0.5   0.220
## 2    0.9   0.401

Note, for the remaining overlap measures the order does not matter. Below we show this for the volumnic intersection (type = "vi") as an example.

hr_overlap(hr_lupe, hr_leroy, type = "vi", conditional = FALSE)
## # A tibble: 1 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1      1   0.440
hr_overlap(hr_leroy, hr_lupe, type = "vi", conditional = FALSE)
## # A tibble: 1 × 2
##   levels overlap
##    <dbl>   <dbl>
## 1      1   0.440

\(> 2\) instances

Lets calculate daily ranges for Lupe and then and then see how different ranges overlap with each other.

We have to use the same template raster in order to make ranges comparable.

trast <- make_trast(lupe, res = 50)

Then we add a new column with day and calculate for each day a KDE home range.

dat <- lupe |> 
  mutate(week = lubridate::floor_date(t_, "week")) |> 
  nest(data = -week) |> 
  mutate(kde = map(data, hr_kde, trast = trast, levels = c(0.5, 0.95, 0.99)))

Now we can use the list column with the home-range estimates to calculate overlap between the different home-ranges. By default which = "consecutive", this means for each list entry (= home-range estimate) the overlap to the next entry will be calculated.

hr_overlap(dat$kde, type = "vi")
## # A tibble: 3 × 4
##    from    to levels overlap
##   <int> <int>  <dbl>   <dbl>
## 1     1     2      1  0.0427
## 2     2     3      1  0.551 
## 3     3     4      1  0.612

This works as well, if we set conditional = TRUE:

hr_overlap(dat$kde, type = "vi", conditional = TRUE)
## # A tibble: 9 × 4
##    from    to levels overlap
##   <int> <int>  <dbl>   <dbl>
## 1     1     2   0.5   0     
## 2     1     2   0.95  0.0259
## 3     1     2   0.99  0.0350
## 4     2     3   0.5   0.262 
## 5     2     3   0.95  0.528 
## 6     2     3   0.99  0.547 
## 7     3     4   0.5   0.318 
## 8     3     4   0.95  0.592 
## 9     3     4   0.99  0.608

Sometimes it can be useful to provide meaningful labels. We can do this with the labels argument.

hr_overlap(dat$kde, type = "vi", labels = dat$week)
## # A tibble: 3 × 4
##   from       to         levels overlap
##   <chr>      <chr>       <dbl>   <dbl>
## 1 2010-12-12 2010-12-19      1  0.0427
## 2 2010-12-19 2010-12-26      1  0.551 
## 3 2010-12-26 2011-01-02      1  0.612

Different options exist for the argument which. For example, which = "one_to_all" calculates the overlap between the first and all other home ranges.

Overlap between a home range and a simple feature

The function hr_overlap_feature allows to calculate percentage overlap (\(HR\) index) between a home. To illustrate this feature, we will use again the data from lupe and calculate the intersection with an arbitrary polygon.

poly <- amt::bbox(lupe, buffer = -500, sf = TRUE)
poly1 <- amt::bbox(lupe, sf = TRUE)
hr <- hr_mcp(lupe)
ggplot() + geom_sf(data = hr_isopleths(hr)) + 
  geom_sf(data = poly, fill = NA, col = "red") +
  geom_sf(data = poly1, fill = NA, col = "blue")

hr_overlap_feature(hr, poly, direction = "hr_with_feature")
## # A tibble: 1 × 3
##    from    to overlap
##   <dbl> <int>   <dbl>
## 1  0.95     1   0.828
hr_overlap_feature(hr, poly1, direction = "hr_with_feature")
## # A tibble: 1 × 3
##    from    to overlap
##   <dbl> <int>   <dbl>
## 1  0.95     1    1.00
hr_overlap_feature(hr, poly, direction = "feature_with_hr")
## # A tibble: 1 × 3
##    from    to overlap
##   <int> <dbl>   <dbl>
## 1     1  0.95   0.854
hr_overlap_feature(hr, poly1, direction = "feature_with_hr")
## # A tibble: 1 × 3
##    from    to overlap
##   <int> <dbl>   <dbl>
## 1     1  0.95   0.542

The same work with several home-range levels:

hr <- hr_mcp(lupe, levels = c(0.5, 0.9, 0.95))
hr_overlap_feature(hr, poly, direction = "hr_with_feature")
## # A tibble: 3 × 3
##    from    to overlap
##   <dbl> <int>   <dbl>
## 1  0.5      1   0.828
## 2  0.9      1   0.860
## 3  0.95     1   0.990

References

Session

sessioninfo::session_info()
## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value
##  version  R version 4.2.2 Patched (2022-11-10 r83330)
##  os       Ubuntu 22.04.2 LTS
##  system   x86_64, linux-gnu
##  ui       X11
##  language (EN)
##  collate  C
##  ctype    en_US.UTF-8
##  tz       Europe/Berlin
##  date     2023-03-28
##  pandoc   2.19.2 @ /usr/lib/rstudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package      * version  date (UTC) lib source
##  amt          * 0.2.1.0  2023-03-28 [1] local
##  backports      1.4.1    2021-12-13 [5] CRAN (R 4.2.0)
##  bslib          0.4.2    2022-12-16 [3] CRAN (R 4.2.2)
##  cachem         1.0.7    2023-02-24 [5] CRAN (R 4.2.2)
##  checkmate      2.1.0    2022-04-21 [5] CRAN (R 4.2.0)
##  class          7.3-21   2023-01-23 [6] CRAN (R 4.2.2)
##  classInt       0.4-9    2023-02-28 [3] CRAN (R 4.2.2)
##  cli            3.6.0    2023-01-09 [5] CRAN (R 4.2.2)
##  codetools      0.2-19   2023-02-01 [6] CRAN (R 4.2.2)
##  colorspace     2.1-0    2023-01-23 [5] CRAN (R 4.2.2)
##  data.table     1.14.8   2023-02-17 [3] CRAN (R 4.2.2)
##  DBI            1.1.3    2022-06-18 [5] CRAN (R 4.2.1)
##  digest         0.6.31   2022-12-11 [3] CRAN (R 4.2.2)
##  dplyr        * 1.1.0    2023-01-29 [5] CRAN (R 4.2.2)
##  e1071          1.7-13   2023-02-01 [3] CRAN (R 4.2.2)
##  evaluate       0.20     2023-01-17 [5] CRAN (R 4.2.2)
##  fansi          1.0.4    2023-01-22 [5] CRAN (R 4.2.2)
##  farver         2.1.1    2022-07-06 [5] CRAN (R 4.2.1)
##  fastmap        1.1.1    2023-02-24 [5] CRAN (R 4.2.2)
##  generics       0.1.3    2022-07-05 [5] CRAN (R 4.2.1)
##  ggforce        0.4.1    2022-10-04 [3] CRAN (R 4.2.2)
##  ggplot2      * 3.4.1    2023-02-10 [3] CRAN (R 4.2.2)
##  ggraph       * 2.1.0    2022-10-09 [3] CRAN (R 4.2.2)
##  ggrepel        0.9.3    2023-02-03 [3] CRAN (R 4.2.2)
##  glue           1.6.2    2022-02-24 [5] CRAN (R 4.2.0)
##  graphlayouts   0.8.4    2022-11-24 [3] CRAN (R 4.2.2)
##  gridExtra      2.3      2017-09-09 [3] CRAN (R 4.2.2)
##  gtable         0.3.1    2022-09-01 [5] CRAN (R 4.2.1)
##  highr          0.10     2022-12-22 [3] CRAN (R 4.2.2)
##  htmltools      0.5.4    2022-12-07 [5] CRAN (R 4.2.2)
##  igraph         1.4.0    2023-02-10 [3] CRAN (R 4.2.2)
##  jquerylib      0.1.4    2021-04-26 [3] CRAN (R 4.2.2)
##  jsonlite       1.8.4    2022-12-06 [3] CRAN (R 4.2.2)
##  KernSmooth     2.23-20  2021-05-03 [6] CRAN (R 4.2.0)
##  knitr          1.42     2023-01-25 [5] CRAN (R 4.2.2)
##  labeling       0.4.2    2020-10-20 [5] CRAN (R 4.2.0)
##  lattice        0.20-45  2021-09-22 [6] CRAN (R 4.2.0)
##  lifecycle      1.0.3    2022-10-07 [5] CRAN (R 4.2.1)
##  lubridate      1.9.2    2023-02-10 [3] CRAN (R 4.2.2)
##  magrittr       2.0.3    2022-03-30 [5] CRAN (R 4.2.0)
##  MASS           7.3-58.2 2023-01-23 [6] CRAN (R 4.2.2)
##  Matrix         1.5-3    2022-11-11 [6] CRAN (R 4.2.2)
##  munsell        0.5.0    2018-06-12 [3] CRAN (R 4.2.2)
##  pillar         1.8.1    2022-08-19 [5] CRAN (R 4.2.1)
##  pkgconfig      2.0.3    2019-09-22 [3] CRAN (R 4.2.2)
##  polyclip       1.10-4   2022-10-20 [3] CRAN (R 4.2.2)
##  proxy          0.4-27   2022-06-09 [3] CRAN (R 4.2.2)
##  purrr          1.0.1    2023-01-10 [5] CRAN (R 4.2.2)
##  R6             2.5.1    2021-08-19 [5] CRAN (R 4.2.0)
##  rbibutils      2.2.13   2023-01-13 [3] CRAN (R 4.2.2)
##  Rcpp           1.0.10   2023-01-22 [5] CRAN (R 4.2.2)
##  Rdpack         2.4      2022-07-20 [3] CRAN (R 4.2.2)
##  rlang          1.0.6    2022-09-24 [5] CRAN (R 4.2.1)
##  rmarkdown      2.20     2023-01-19 [5] CRAN (R 4.2.2)
##  rstudioapi     0.14     2022-08-22 [5] CRAN (R 4.2.1)
##  sass           0.4.5    2023-01-24 [5] CRAN (R 4.2.2)
##  scales         1.2.1    2022-08-20 [5] CRAN (R 4.2.1)
##  sessioninfo    1.2.2    2021-12-06 [3] CRAN (R 4.2.2)
##  sf             1.0-9    2022-11-08 [3] CRAN (R 4.2.2)
##  survival       3.5-3    2023-02-12 [3] CRAN (R 4.2.2)
##  terra          1.7-12   2023-02-21 [3] Github (rspatial/terra@b79b4b0)
##  tibble         3.1.8    2022-07-22 [5] CRAN (R 4.2.2)
##  tidygraph    * 1.2.3    2023-02-01 [3] CRAN (R 4.2.2)
##  tidyr          1.3.0    2023-01-24 [5] CRAN (R 4.2.2)
##  tidyselect     1.2.0    2022-10-10 [5] CRAN (R 4.2.1)
##  timechange     0.2.0    2023-01-11 [5] CRAN (R 4.2.2)
##  tweenr         2.0.2    2022-09-06 [3] CRAN (R 4.2.2)
##  units          0.8-1    2022-12-10 [3] CRAN (R 4.2.2)
##  utf8           1.2.3    2023-01-31 [5] CRAN (R 4.2.2)
##  vctrs          0.5.2    2023-01-23 [5] CRAN (R 4.2.2)
##  viridis        0.6.2    2021-10-13 [5] CRAN (R 4.2.0)
##  viridisLite    0.4.1    2022-08-22 [5] CRAN (R 4.2.1)
##  withr          2.5.0    2022-03-03 [5] CRAN (R 4.2.0)
##  xfun           0.37     2023-01-31 [5] CRAN (R 4.2.2)
##  yaml           2.3.7    2023-01-23 [5] CRAN (R 4.2.2)
## 
##  [1] /tmp/RtmpEE1aXl/Rinst11aff69feb4c3
##  [2] /tmp/RtmpTZF65G/temp_libpathf4f475febbc9
##  [3] /home/jsigner/R/x86_64-pc-linux-gnu-library/4.2
##  [4] /usr/local/lib/R/site-library
##  [5] /usr/lib/R/site-library
##  [6] /usr/lib/R/library
## 
## ──────────────────────────────────────────────────────────────────────────────

  1. For a discussion of geometric vs. probabilistic estimators see here: https://www.biorxiv.org/content/10.1101/2020.08.19.256859v2↩︎