Fitting Step-Selection Functions with amt

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Fitting Step-Selection Functions with amt

Johannes Signer

2024-04-01

About

This vignette briefly introduces how one can fit a Step-Selection Function (SSF) with the amt package. We will be using the example data of one red deer from northern Germany and one covariate: a forest cover map. For a more through discussion see also Fieberg et al. 2020¹ and supplement B.

Getting the data ready

First we load the required libraries and the relocation data (called deer)

library(lubridate)
library(amt)
data("deer")
deer

## # A tibble: 826 × 4
##          x_       y_ t_                  burst_
##  *    <dbl>    <dbl> <dttm>               <dbl>
##  1 4314068. 3445807. 2008-03-30 00:01:47      1
##  2 4314053. 3445768. 2008-03-30 06:00:54      1
##  3 4314105. 3445859. 2008-03-30 12:01:47      1
##  4 4314044. 3445785. 2008-03-30 18:01:24      1
##  5 4313015. 3445858. 2008-03-31 00:01:23      1
##  6 4312860. 3445857. 2008-03-31 06:01:45      1
##  7 4312854. 3445856. 2008-03-31 12:01:11      1
##  8 4312858. 3445858. 2008-03-31 18:01:55      1
##  9 4312745. 3445862. 2008-04-01 00:01:24      1
## 10 4312651. 3446024. 2008-04-01 06:00:54      1
## # ℹ 816 more rows

In order to continue, we need a regular sampling rate. To check the current sampling rate, we use summarize_sampling_rate:

summarize_sampling_rate(deer)

## # A tibble: 1 × 9
##     min    q1 median  mean    q3   max    sd     n unit 
##   <dbl> <dbl>  <dbl> <dbl> <dbl> <dbl> <dbl> <int> <chr>
## 1  5.96  6.00   6.01  11.5  6.02 3924.  137.   825 hour

The median sampling rate is 6h, which is what we aimed for.

Next, we have to get the environmental covariates. A forest layer is included in the package. Note, that this a regular SpatRast.

sh_forest <- get_sh_forest()
sh_forest

## class       : SpatRaster 
## dimensions  : 720, 751, 1  (nrow, ncol, nlyr)
## resolution  : 25, 25  (x, y)
## extent      : 4304725, 4323500, 3437725, 3455725  (xmin, xmax, ymin, ymax)
## coord. ref. : +proj=laea +lat_0=52 +lon_0=10 +x_0=4321000 +y_0=3210000 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs 
## source(s)   : memory
## name        : forest 
## min value   :      0 
## max value   :      1

Prepare Data for SSF

Steps

Before fitting a SSF we have to do some data preparation. First, we change from a point representation to a step representation, using the function steps_by_burst, which in contrast to the steps function accounts for bursts.

ssf1 <- deer |> steps_by_burst()

Control/random steps

The generic function random_steps provides a methods for a track_xy*, where each observed step is paired with n_control control steps (i.e., steps that share the same starting location but have different turn angles and step lengths). The distributions for drawing step lengths and turning angles are usually obtained by fitting known parametric distribution to the observed step length and turn angles.

The function random_steps has seven arguments. For most use cases the defaults are just fine, but there might situation where the user wants to adjust some of the arguments. The arguments are:

x: This is the track_xy* for which the random steps are created. That is, for each step in x n_control random steps are created.
n_control: The number of random steps that should be created for each observed step.
sl_distr: This is the distribution of the step lengths. By default a gamma distribution is fit to the observed step lengths of the x. But any amt_distr is suitable here. ²
ta_distr: This is the turn angle distribution, with the default being a von Mises distribution.
rand_sl: These are the random step lengths, by default 1e5 random numbers from the distribution fitted in 3³.
rand_ta: These are the random turn angles, by default 1e4 random numbers from the distribution fitted in 4.
include_observed: This argument is by default TRUE and indicates if the observed steps should be included or not.

The default situation

In most situations the following code snippet should work⁴.

ssf1 <- ssf1 |> random_steps(n_control = 15)

A exponential distribution for step lengths

todo

Extract covariates

As a last step, we have to extract the covariates at the end point of each step. We can do this with extract_covariates.

ssf1 <- ssf1 |> extract_covariates(sh_forest)

Since the forest layers is coded as 1 = forest and 2 != forest, we create a factor with appropriate levels. We also calculate the log of the step length and the cosine of the turn angle, which we may use later for a integrated step selection function.

ssf1 <- ssf1 |> 
  mutate(forest = factor(forest, levels = 1:0, labels = c("forest", "non-forest")), 
         cos_ta = cos(ta_), 
        log_sl = log(sl_))

Fitting SSF

Now all pieces are there to fit a SSF. We will use fit_clogit, which is a wrapper around survival::clogit.

m0 <- ssf1 |> fit_clogit(case_ ~ forest + strata(step_id_))
m1 <- ssf1 |> fit_clogit(case_ ~ forest + forest:cos_ta + forest:log_sl + log_sl * cos_ta + strata(step_id_))
m2 <- ssf1 |> fit_clogit(case_ ~ forest + forest:cos_ta + forest:log_sl + log_sl + cos_ta + strata(step_id_))
summary(m0)

## Call:
## coxph(formula = Surv(rep(1, 12096L), case_) ~ forest + strata(step_id_), 
##     data = data, method = "exact")
## 
##   n= 12096, number of events= 756 
## 
##                     coef exp(coef) se(coef)      z Pr(>|z|)    
## forestnon-forest -0.5145    0.5978   0.1088 -4.727 2.28e-06 ***
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
## 
##                  exp(coef) exp(-coef) lower .95 upper .95
## forestnon-forest    0.5978      1.673     0.483      0.74
## 
## Concordance= 0.529  (se = 0.007 )
## Likelihood ratio test= 21.65  on 1 df,   p=3e-06
## Wald test            = 22.34  on 1 df,   p=2e-06
## Score (logrank) test = 22.44  on 1 df,   p=2e-06

summary(m1)

## Call:
## coxph(formula = Surv(rep(1, 12096L), case_) ~ forest + forest:cos_ta + 
##     forest:log_sl + log_sl * cos_ta + strata(step_id_), data = data, 
##     method = "exact")
## 
##   n= 12096, number of events= 756 
## 
##                             coef exp(coef) se(coef)      z Pr(>|z|)    
## forestnon-forest         0.83934   2.31483  0.32799  2.559 0.010497 *  
## log_sl                   0.17416   1.19025  0.04958  3.513 0.000443 ***
## cos_ta                  -0.20329   0.81604  0.20531 -0.990 0.322092    
## forestnon-forest:cos_ta -0.31159   0.73228  0.11769 -2.648 0.008106 ** 
## forestnon-forest:log_sl -0.25554   0.77450  0.05786 -4.416    1e-05 ***
## log_sl:cos_ta            0.01656   1.01669  0.03450  0.480 0.631313    
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
## 
##                         exp(coef) exp(-coef) lower .95 upper .95
## forestnon-forest           2.3148     0.4320    1.2171    4.4026
## log_sl                     1.1902     0.8402    1.0800    1.3117
## cos_ta                     0.8160     1.2254    0.5457    1.2203
## forestnon-forest:cos_ta    0.7323     1.3656    0.5814    0.9223
## forestnon-forest:log_sl    0.7745     1.2912    0.6915    0.8675
## log_sl:cos_ta              1.0167     0.9836    0.9502    1.0878
## 
## Concordance= 0.609  (se = 0.013 )
## Likelihood ratio test= 90.25  on 6 df,   p=<2e-16
## Wald test            = 88.38  on 6 df,   p=<2e-16
## Score (logrank) test = 90.65  on 6 df,   p=<2e-16

summary(m2)

## Call:
## coxph(formula = Surv(rep(1, 12096L), case_) ~ forest + forest:cos_ta + 
##     forest:log_sl + log_sl + cos_ta + strata(step_id_), data = data, 
##     method = "exact")
## 
##   n= 12096, number of events= 756 
## 
##                             coef exp(coef) se(coef)      z Pr(>|z|)    
## forestnon-forest         0.84859   2.33635  0.32724  2.593 0.009510 ** 
## log_sl                   0.17369   1.18969  0.04956  3.505 0.000457 ***
## cos_ta                  -0.11644   0.89008  0.09693 -1.201 0.229614    
## forestnon-forest:cos_ta -0.31497   0.72981  0.11750 -2.681 0.007348 ** 
## forestnon-forest:log_sl -0.25707   0.77331  0.05776 -4.451 8.56e-06 ***
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
## 
##                         exp(coef) exp(-coef) lower .95 upper .95
## forestnon-forest           2.3363     0.4280    1.2302    4.4370
## log_sl                     1.1897     0.8406    1.0796    1.3111
## cos_ta                     0.8901     1.1235    0.7361    1.0763
## forestnon-forest:cos_ta    0.7298     1.3702    0.5797    0.9188
## forestnon-forest:log_sl    0.7733     1.2931    0.6905    0.8660
## 
## Concordance= 0.609  (se = 0.013 )
## Likelihood ratio test= 90.02  on 5 df,   p=<2e-16
## Wald test            = 87.6  on 5 df,   p=<2e-16
## Score (logrank) test = 89.63  on 5 df,   p=<2e-16

Interpretation of coefficients

See the discussion in Fieberg et al 2021.

A note on piping

All steps described above, could easily be wrapped into one piped workflow:

m1 <- deer |> 
  steps_by_burst() |> random_steps(n = 15) |> 
  extract_covariates(sh_forest) |> 
  mutate(forest = factor(forest, levels = 1:0, labels = c("forest", "non-forest")), 
         cos_ta = cos(ta_), 
         log_sl = log(sl_)) |> 
  fit_clogit(case_ ~ forest + forest:cos_ta + forest:sl_ + sl_ * cos_ta + strata(step_id_))

summary(m1)

## Call:
## coxph(formula = Surv(rep(1, 12096L), case_) ~ forest + forest:cos_ta + 
##     forest:sl_ + sl_ * cos_ta + strata(step_id_), data = data, 
##     method = "exact")
## 
##   n= 12096, number of events= 756 
## 
##                               coef  exp(coef)   se(coef)      z Pr(>|z|)    
## forestnon-forest        -0.1036793  0.9015144  0.1407961 -0.736  0.46150    
## sl_                      0.0006758  1.0006760  0.0001538  4.394 1.11e-05 ***
## cos_ta                  -0.3355283  0.7149603  0.1098064 -3.056  0.00225 ** 
## forestnon-forest:cos_ta -0.2134928  0.8077580  0.1183237 -1.804  0.07118 .  
## forestnon-forest:sl_    -0.0009751  0.9990253  0.0001986 -4.909 9.14e-07 ***
## sl_:cos_ta               0.0003849  1.0003850  0.0001271  3.027  0.00247 ** 
## ---
## Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
## 
##                         exp(coef) exp(-coef) lower .95 upper .95
## forestnon-forest           0.9015     1.1092    0.6841    1.1880
## sl_                        1.0007     0.9993    1.0004    1.0010
## cos_ta                     0.7150     1.3987    0.5765    0.8866
## forestnon-forest:cos_ta    0.8078     1.2380    0.6406    1.0186
## forestnon-forest:sl_       0.9990     1.0010    0.9986    0.9994
## sl_:cos_ta                 1.0004     0.9996    1.0001    1.0006
## 
## Concordance= 0.603  (se = 0.013 )
## Likelihood ratio test= 105.2  on 6 df,   p=<2e-16
## Wald test            = 107.8  on 6 df,   p=<2e-16
## Score (logrank) test = 116.5  on 6 df,   p=<2e-16

Session

sessioninfo::session_info()

## ─ Session info ───────────────────────────────────────────────────────────────
##  setting  value
##  version  R version 4.3.2 (2023-10-31)
##  os       macOS Sonoma 14.4
##  system   aarch64, darwin20
##  ui       X11
##  language (EN)
##  collate  C
##  ctype    en_US.UTF-8
##  tz       Europe/Berlin
##  date     2024-04-01
##  pandoc   3.1.11.1 @ /usr/local/bin/ (via rmarkdown)
## 
## ─ Packages ───────────────────────────────────────────────────────────────────
##  package      * version    date (UTC) lib source
##  amt          * 0.2.2.0    2024-04-01 [1] local
##  backports      1.4.1      2021-12-13 [3] CRAN (R 4.3.0)
##  boot           1.3-28.1   2022-11-22 [3] CRAN (R 4.3.2)
##  bslib          0.6.1      2023-11-28 [3] CRAN (R 4.3.1)
##  cachem         1.0.8      2023-05-01 [3] CRAN (R 4.3.0)
##  checkmate      2.3.1      2023-12-04 [3] CRAN (R 4.3.1)
##  circular       0.5-0      2023-09-05 [3] CRAN (R 4.3.0)
##  class          7.3-22     2023-05-03 [3] CRAN (R 4.3.2)
##  classInt       0.4-10     2023-09-05 [3] CRAN (R 4.3.0)
##  cli            3.6.2      2023-12-11 [3] CRAN (R 4.3.1)
##  codetools      0.2-19     2023-02-01 [3] CRAN (R 4.3.2)
##  colorspace     2.1-0      2023-01-23 [3] CRAN (R 4.3.0)
##  data.table     1.15.2     2024-02-29 [3] CRAN (R 4.3.1)
##  DBI            1.2.2      2024-02-16 [3] CRAN (R 4.3.1)
##  digest         0.6.35     2024-03-11 [3] CRAN (R 4.3.1)
##  dplyr        * 1.1.4      2023-11-17 [3] CRAN (R 4.3.1)
##  e1071          1.7-14     2023-12-06 [3] CRAN (R 4.3.1)
##  evaluate       0.23       2023-11-01 [3] CRAN (R 4.3.1)
##  fansi          1.0.6      2023-12-08 [3] CRAN (R 4.3.1)
##  farver         2.1.1      2022-07-06 [3] CRAN (R 4.3.0)
##  fastmap        1.1.1      2023-02-24 [3] CRAN (R 4.3.0)
##  fitdistrplus   1.1-11     2023-04-25 [3] CRAN (R 4.3.0)
##  generics       0.1.3      2022-07-05 [3] CRAN (R 4.3.0)
##  ggforce        0.4.1      2022-10-04 [3] CRAN (R 4.3.0)
##  ggplot2      * 3.4.4      2023-10-12 [3] CRAN (R 4.3.1)
##  ggraph       * 2.1.0      2022-10-09 [3] CRAN (R 4.3.0)
##  ggrepel        0.9.5      2024-01-10 [3] CRAN (R 4.3.1)
##  glue           1.7.0      2024-01-09 [3] CRAN (R 4.3.1)
##  graphlayouts   1.1.0      2024-01-19 [3] CRAN (R 4.3.1)
##  gridExtra      2.3        2017-09-09 [3] CRAN (R 4.3.0)
##  gtable         0.3.4      2023-08-21 [3] CRAN (R 4.3.0)
##  highr          0.10       2022-12-22 [3] CRAN (R 4.3.0)
##  htmltools      0.5.7      2023-11-03 [3] CRAN (R 4.3.1)
##  igraph         2.0.1.1    2024-01-30 [3] CRAN (R 4.3.1)
##  jquerylib      0.1.4      2021-04-26 [3] CRAN (R 4.3.0)
##  jsonlite       1.8.8      2023-12-04 [3] CRAN (R 4.3.1)
##  KernSmooth     2.23-22    2023-07-10 [3] CRAN (R 4.3.2)
##  knitr        * 1.45       2023-10-30 [3] CRAN (R 4.3.1)
##  labeling       0.4.3      2023-08-29 [3] CRAN (R 4.3.0)
##  lattice        0.22-5     2023-10-24 [3] CRAN (R 4.3.1)
##  lifecycle      1.0.4      2023-11-07 [3] CRAN (R 4.3.1)
##  lubridate    * 1.9.3      2023-09-27 [3] CRAN (R 4.3.1)
##  magrittr       2.0.3      2022-03-30 [3] CRAN (R 4.3.0)
##  MASS           7.3-60.0.1 2024-01-13 [3] CRAN (R 4.3.1)
##  Matrix         1.6-5      2024-01-11 [3] CRAN (R 4.3.2)
##  munsell        0.5.0      2018-06-12 [3] CRAN (R 4.3.0)
##  mvtnorm        1.2-4      2023-11-27 [3] CRAN (R 4.3.1)
##  pillar         1.9.0      2023-03-22 [3] CRAN (R 4.3.0)
##  pkgconfig      2.0.3      2019-09-22 [3] CRAN (R 4.3.0)
##  polyclip       1.10-6     2023-09-27 [3] CRAN (R 4.3.1)
##  proxy          0.4-27     2022-06-09 [3] CRAN (R 4.3.0)
##  purrr          1.0.2      2023-08-10 [3] CRAN (R 4.3.0)
##  R6             2.5.1      2021-08-19 [3] CRAN (R 4.3.0)
##  rbibutils      2.2.16     2023-10-25 [3] CRAN (R 4.3.1)
##  Rcpp           1.0.12     2024-01-09 [3] CRAN (R 4.3.1)
##  Rdpack         2.6        2023-11-08 [3] CRAN (R 4.3.1)
##  rlang          1.1.3      2024-01-10 [3] CRAN (R 4.3.1)
##  rmarkdown      2.25       2023-09-18 [3] CRAN (R 4.3.1)
##  rstudioapi     0.15.0     2023-07-07 [3] CRAN (R 4.3.0)
##  sass           0.4.8      2023-12-06 [3] CRAN (R 4.3.1)
##  scales         1.3.0      2023-11-28 [3] CRAN (R 4.3.1)
##  sessioninfo    1.2.2      2021-12-06 [3] CRAN (R 4.3.0)
##  sf             1.0-16     2024-03-24 [3] CRAN (R 4.3.1)
##  survival       3.5-7      2023-08-14 [3] CRAN (R 4.3.2)
##  terra          1.7-71     2024-01-31 [3] CRAN (R 4.3.1)
##  tibble         3.2.1      2023-03-20 [3] CRAN (R 4.3.0)
##  tidygraph    * 1.3.1      2024-01-30 [3] CRAN (R 4.3.1)
##  tidyr          1.3.1      2024-01-24 [3] CRAN (R 4.3.1)
##  tidyselect     1.2.1      2024-03-11 [3] CRAN (R 4.3.1)
##  timechange     0.3.0      2024-01-18 [3] CRAN (R 4.3.1)
##  tweenr         2.0.2      2022-09-06 [3] CRAN (R 4.3.0)
##  units          0.8-5      2023-11-28 [3] CRAN (R 4.3.1)
##  utf8           1.2.4      2023-10-22 [3] CRAN (R 4.3.1)
##  vctrs          0.6.5      2023-12-01 [3] CRAN (R 4.3.1)
##  viridis        0.6.4      2023-07-22 [3] CRAN (R 4.3.0)
##  viridisLite    0.4.2      2023-05-02 [3] CRAN (R 4.3.0)
##  withr          3.0.0      2024-01-16 [3] CRAN (R 4.3.1)
##  xfun           0.41       2023-11-01 [3] CRAN (R 4.3.1)
##  yaml           2.3.8      2023-12-11 [3] CRAN (R 4.3.1)
## 
##  [1] /private/var/folders/ln/h3zng0fs2pq7mhn_hzn0d8x00000gn/T/Rtmphl5CVm/Rinst6cb5562535ee
##  [2] /private/var/folders/ln/h3zng0fs2pq7mhn_hzn0d8x00000gn/T/RtmpgKr8k0/temp_libpath6a0129d1adcf
##  [3] /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/library
## 
## ──────────────────────────────────────────────────────────────────────────────

https://www.biorxiv.org/content/10.1101/2020.11.12.379834v4 ↩︎
See also ?fit_distr.↩︎
Note, this possible because of the Glivenko-Cantelli theorem and works as long as the sample from the original distribution (the sample you provide here) is large enough.↩︎
And how it was implemented in amt up to version 0.0.6. This should be backward compatible and not break existing code.↩︎

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.