# Step selection functions for animal movement
# https://tidyecology.com/posts/step-selection-functions/
#
# The R code of this Tidy Ecology tutorial, chunk by chunk, in the order of the post.
# Run it top to bottom in a fresh R session. Code the post shows but does not run
# is commented out. The prose, and the numbers it quotes, are in the post itself.
# Post last modified: 2026-10-15

## ---- setup ----
library(ggplot2)
te_canvas <- theme(plot.background  = element_rect(fill = "#f5f4ee", colour = NA),
                   panel.background = element_rect(fill = "#f5f4ee", colour = NA))
library(grid)

res_raw <- function(x, y) {
  1.5 * exp(-((x - 38)^2 + (y - 62)^2) / (2 * 28^2)) +
  1.2 * exp(-((x - 70)^2 + (y - 40)^2) / (2 * 32^2)) +
  (-0.00030) * ((x - 50)^2 + (y - 50)^2)
}
gx <- seq(0, 100, length.out = 120)
grid_df <- expand.grid(x = gx, y = gx)
grid_df$raw <- res_raw(grid_df$x, grid_df$y)
mu_r <- mean(grid_df$raw); sd_r <- sd(grid_df$raw)
resource <- function(x, y) (res_raw(x, y) - mu_r) / sd_r
grid_df$z <- resource(grid_df$x, grid_df$y)

## ---- vonmises ----
rvm <- function(n, mu, kappa) {
  out <- numeric(n)
  a <- 1 + sqrt(1 + 4 * kappa^2)
  b <- (a - sqrt(2 * a)) / (2 * kappa)
  r <- (1 + b^2) / (2 * b)
  for (i in seq_len(n)) {
    repeat {
      u1 <- runif(1); u2 <- runif(1); u3 <- runif(1)
      z <- cos(pi * u1)
      f <- (1 + r * z) / (r + z)
      cc <- kappa * (r - f)
      if (cc * (2 - cc) - u2 > 0 || log(cc / u2) + 1 - cc >= 0) break
    }
    theta <- sign(u3 - 0.5) * acos(f)
    out[i] <- theta + mu
  }
  ((out + pi) %% (2 * pi)) - pi
}

## ---- simulate ----
sh_move <- 2.2; sc_move <- 5.5; kap_move <- 0.9   # movement kernel (truth)
beta_true <- 0.85                                  # selection strength (truth)
n <- 1200; M <- 300                                # steps; candidate pool per step

set.seed(4711)
pos <- matrix(NA_real_, n + 1, 2); pos[1, ] <- c(45, 50)
heading <- numeric(n + 1); heading[1] <- runif(1, -pi, pi)
for (i in 1:n) {
  L <- rgamma(M, shape = sh_move, scale = sc_move)
  a <- rvm(M, 0, kap_move)
  ang <- heading[i] + a
  ex <- pos[i, 1] + L * cos(ang)
  ey <- pos[i, 2] + L * sin(ang)
  w <- exp(beta_true * resource(ex, ey))
  j <- sample.int(M, 1, prob = w)
  pos[i + 1, ] <- c(ex[j], ey[j]); heading[i + 1] <- ang[j]
}
trk <- data.frame(x = pos[, 1], y = pos[, 2])

dx <- diff(pos[, 1]); dy <- diff(pos[, 2])
step_len <- sqrt(dx^2 + dy^2)
bearing <- atan2(dy, dx)
turn <- ((diff(bearing) + pi) %% (2 * pi)) - pi
mean_step <- mean(step_len); med_step <- median(step_len)

## ---- tentative ----
m1 <- mean(step_len); v1 <- var(step_len)
sh_hat <- m1^2 / v1; sc_hat <- v1 / m1
C <- mean(cos(turn)); S <- mean(sin(turn)); Rbar <- sqrt(C^2 + S^2)
mu_turn <- atan2(S, C)
kap_hat <- if (Rbar < 0.53) 2 * Rbar + Rbar^3 + 5 * Rbar^5 / 6 else
           if (Rbar < 0.85) -0.4 + 1.39 * Rbar + 0.43 / (1 - Rbar) else
           1 / (Rbar^3 - 4 * Rbar^2 + 3 * Rbar)

## ---- strata ----
K <- 10
set.seed(20260713)
use_idx <- 2:n
n_str <- length(use_idx)
Zcase <- resource(pos[use_idx + 1, 1], pos[use_idx + 1, 2])
Zctrl <- matrix(NA_real_, n_str, K)
for (s in seq_along(use_idx)) {
  i <- use_idx[s]
  Ls <- rgamma(K, shape = sh_hat, scale = sc_hat)
  as <- rvm(K, mu_turn, kap_hat)
  ang <- heading[i] + as
  Zctrl[s, ] <- resource(pos[i, 1] + Ls * cos(ang), pos[i, 2] + Ls * sin(ang))
}
Z <- cbind(Zcase, Zctrl)          # n_str x (K+1); column 1 is the used step

## ---- fig-strata ----
d2 <- (pos[use_idx, 1] - 40)^2 + (pos[use_idx, 2] - 60)^2
ex_s <- which.min(d2); i_ex <- use_idx[ex_s]
set.seed(77)
Le <- rgamma(K, shape = sh_hat, scale = sc_hat)
ae <- rvm(K, mu_turn, kap_hat)
ange <- heading[i_ex] + ae
fan <- data.frame(x0 = pos[i_ex, 1], y0 = pos[i_ex, 2],
                  x1 = pos[i_ex, 1] + Le * cos(ange), y1 = pos[i_ex, 2] + Le * sin(ange))
used_seg <- data.frame(x0 = pos[i_ex, 1], y0 = pos[i_ex, 2],
                       x1 = pos[i_ex + 1, 1], y1 = pos[i_ex + 1, 2])
ggplot() +
  geom_raster(data = grid_df, aes(x, y, fill = z)) +
  scale_fill_gradient(low = "#f5f4ee", high = "#275139", name = "resource\n(SD)") +
  geom_path(data = trk, aes(x, y), colour = "#16241d", linewidth = 0.3, alpha = 0.7) +
  geom_segment(data = fan, aes(x0, y0, xend = x1, yend = y1),
               colour = "#5d6b61", linewidth = 0.4, alpha = 0.9) +
  geom_point(data = fan, aes(x1, y1), colour = "#5d6b61", size = 1.3) +
  geom_segment(data = used_seg, aes(x0, y0, xend = x1, yend = y1), colour = "#b5534e",
               linewidth = 0.9, arrow = arrow(length = unit(0.16, "cm"), type = "closed")) +
  geom_point(data = fan, aes(x0, y0), colour = "#16241d", size = 1.8) +
  coord_equal(xlim = c(0, 100), ylim = c(0, 100), expand = FALSE) +
  labs(x = "easting", y = "northing") +
  theme_minimal(base_size = 11) + te_canvas +
  theme(panel.grid = element_blank(), axis.text = element_text(colour = "#46604a"),
        legend.title = element_text(size = 8, colour = "#46604a"))

## ---- fit ----
clogit_nll <- function(b) {
  eta <- Z * b
  -sum(eta[, 1] - log(rowSums(exp(eta))))
}
opt <- optim(0, clogit_nll, method = "BFGS", hessian = TRUE,
             control = list(reltol = 1e-10))
b_hat <- opt$par
se_hat <- sqrt(1 / opt$hessian[1, 1])
ci <- b_hat + c(-1, 1) * 1.96 * se_hat
rss <- exp(b_hat)

## ---- pooled ----
long_z <- as.vector(t(Z))
long_y <- rep(c(1, rep(0, K)), n_str)
g_pool <- glm(long_y ~ long_z, family = binomial)
b_pool <- unname(coef(g_pool)[2]); se_pool <- summary(g_pool)$coefficients[2, 2]

## ---- recovery ----
set.seed(424242)
Zctrl_true <- matrix(NA_real_, n_str, K)
for (s in seq_along(use_idx)) {
  i <- use_idx[s]
  Ls <- rgamma(K, shape = sh_move, scale = sc_move)
  as <- rvm(K, 0, kap_move)
  ang <- heading[i] + as
  Zctrl_true[s, ] <- resource(pos[i, 1] + Ls * cos(ang), pos[i, 2] + Ls * sin(ang))
}
Zt <- cbind(Zcase, Zctrl_true)
clogit_nll_t <- function(b) { eta <- Zt * b; -sum(eta[, 1] - log(rowSums(exp(eta)))) }
opt_t <- optim(0, clogit_nll_t, method = "BFGS", hessian = TRUE, control = list(reltol = 1e-10))
b_hat_true <- opt_t$par; se_hat_true <- sqrt(1 / opt_t$hessian[1, 1])

## ---- fig-coef ----
dens_df <- rbind(data.frame(kind = "used steps", z = Zcase),
                 data.frame(kind = "available steps", z = as.vector(Zctrl)))
pa <- ggplot(dens_df, aes(z, fill = kind, colour = kind)) +
  geom_density(alpha = 0.45, linewidth = 0.5) +
  scale_fill_manual(values = c("used steps" = "#275139", "available steps" = "#93a87f")) +
  scale_colour_manual(values = c("used steps" = "#275139", "available steps" = "#93a87f")) +
  labs(x = "resource at step endpoint (SD)", y = "density", fill = NULL, colour = NULL) +
  theme_minimal(base_size = 11) + te_canvas +
  theme(panel.grid.minor = element_blank(), legend.position = "inside", legend.position.inside = c(0.72, 0.85),
        legend.background = element_rect(fill = "#ffffff", colour = NA))
coef_df <- data.frame(
  model = factor(c("conditional: movement kernel", "conditional: fitted kernel",
                   "pooled: strata ignored"),
                 levels = c("pooled: strata ignored", "conditional: fitted kernel",
                            "conditional: movement kernel")),
  est = c(b_hat_true, b_hat, b_pool), se = c(se_hat_true, se_hat, se_pool))
pb <- ggplot(coef_df, aes(est, model)) +
  geom_vline(xintercept = beta_true, linetype = "dashed", colour = "#b5534e") +
  geom_errorbar(aes(xmin = est - 1.96 * se, xmax = est + 1.96 * se),
                orientation = "y", width = 0.16, colour = "#275139", linewidth = 0.6) +
  geom_point(colour = "#275139", size = 2.6) +
  annotate("text", x = beta_true, y = 3.44, label = "true beta",
           colour = "#b5534e", size = 3, hjust = 1.1) +
  labs(x = "selection coefficient", y = NULL) +
  theme_minimal(base_size = 11) + te_canvas + theme(panel.grid.minor = element_blank(),
                                                     plot.margin = margin(5.5, 12, 5.5, 5.5))
grid.newpage()
pushViewport(viewport(layout = grid.layout(1, 2, widths = unit(c(1, 1), "null"))))
print(pa, vp = viewport(layout.pos.row = 1, layout.pos.col = 1))
print(pb, vp = viewport(layout.pos.row = 1, layout.pos.col = 2))

## ---- rsf ----
set.seed(999)
used_pts <- trk[-1, ]
n_av <- nrow(used_pts) * K
av_pts <- data.frame(x = runif(n_av, 0, 100), y = runif(n_av, 0, 100))
rsf_y <- c(rep(1, nrow(used_pts)), rep(0, n_av))
rsf_z <- c(resource(used_pts$x, used_pts$y), resource(av_pts$x, av_pts$y))
g_rsf <- glm(rsf_y ~ rsf_z, family = binomial)
b_rsf <- unname(coef(g_rsf)[2])

## ---- herd-sim ----
# within-stratum variance of the resource on this track, and its total variance
vw_host <- mean(rowMeans((Z - rowMeans(Z))^2))
var_host <- var(as.vector(Z))
vw_iid <- K / (K + 1)            # K + 1 independent standard normal candidates
herd_de <- function(sig_b, steps, vw) 1 + sig_b^2 * steps * vw
herd_rej <- function(de) 2 * pnorm(-qnorm(0.975) / sqrt(de))

# n_anim animals with slopes N(mu_b, sig_b); each step reuses one stratum of Z
draw_herd <- function(n_anim, steps, mu_b, sig_b) {
  if (length(steps) == 1) steps <- rep(steps, n_anim)
  b_anim <- rnorm(n_anim, mu_b, sig_b)
  who <- rep(seq_len(n_anim), steps)
  zz <- Z[sample.int(nrow(Z), length(who), replace = TRUE), , drop = FALSE]
  gumbel <- -log(-log(matrix(runif(length(zz)), nrow(zz))))
  pick <- max.col(zz * b_anim[who] + gumbel, ties.method = "first")
  rc <- cbind(seq_len(nrow(zz)), pick)
  used <- zz[rc]; zz[rc] <- zz[, 1]; zz[, 1] <- used   # used step to column 1
  list(z = zz, who = who, steps = steps)
}

# the conditional likelihood of this post, maximised by Newton steps,
# one slope per group (a single group is the pooled fit)
clogit_newton <- function(zz, grp, n_grp) {
  bb <- numeric(n_grp)
  for (it in 1:40) {
    ee <- exp(zz * bb[grp]); pr <- ee / rowSums(ee)
    m1 <- rowSums(pr * zz); m2 <- rowSums(pr * zz^2)
    stp <- unname(rowsum(zz[, 1] - m1, grp)[, 1] / rowsum(m2 - m1^2, grp)[, 1])
    bb <- bb + stp
    if (max(abs(stp)) < 1e-10) break
  }
  ee <- exp(zz * bb[grp]); pr <- ee / rowSums(ee)
  m1 <- rowSums(pr * zz); m2 <- rowSums(pr * zz^2)
  list(b = bb, info = unname(rowsum(m2 - m1^2, grp)[, 1]), score = zz[, 1] - m1)
}

# inverse-variance weights plus a between-animal variance (DerSimonian-Laird)
dl_pool <- function(b_i, se_i) {
  w0 <- 1 / se_i^2; b_fix <- sum(w0 * b_i) / sum(w0)
  q_stat <- sum(w0 * (b_i - b_fix)^2)
  tau2 <- max(0, (q_stat - (length(b_i) - 1)) / (sum(w0) - sum(w0^2) / sum(w0)))
  w1 <- 1 / (se_i^2 + tau2)
  c(est = sum(w1 * b_i) / sum(w1), se = 1 / sqrt(sum(w1)), tau2 = tau2)
}

herd_rep <- function(n_anim, steps, sig_b) {
  hd <- draw_herd(n_anim, steps, 0, sig_b)
  pf <- clogit_newton(hd$z, rep(1L, nrow(hd$z)), 1)
  se_rob <- sqrt(sum(rowsum(pf$score, hd$who)^2)) / pf$info
  af <- clogit_newton(hd$z, hd$who, n_anim)
  dl <- dl_pool(af$b, 1 / sqrt(af$info))
  c(b = pf$b, z_pool = pf$b * sqrt(pf$info), z_rob = pf$b / se_rob,
    t_two = mean(af$b) / (sd(af$b) / sqrt(n_anim)), z_dl = dl[["est"]] / dl[["se"]],
    inv_info = 1 / pf$info, s_eff = sum(hd$steps^2) / sum(hd$steps))
}

herd_rates <- function(n_rep, n_anim, steps, sig_b) {
  rr <- t(replicate(n_rep, herd_rep(n_anim, if (is.function(steps)) steps() else steps, sig_b)))
  zc <- qnorm(0.975)
  data.frame(n_anim = n_anim, steps = mean(rr[, "s_eff"]), sig_b = sig_b, n_rep = n_rep,
             pool = mean(abs(rr[, "z_pool"]) > zc), rob = mean(abs(rr[, "z_rob"]) > zc),
             two = mean(abs(rr[, "t_two"]) > qt(0.975, n_anim - 1)),
             dl = mean(abs(rr[, "z_dl"]) > zc),
             de_var = var(rr[, "b"]) / mean(rr[, "inv_info"]),
             formula = mean(herd_rej(herd_de(sig_b, rr[, "s_eff"], vw_host))))
}

set.seed(26092601)
herd_plan <- data.frame(n_anim = c(5, 5, 20, 5, 5, 5, 5, 20),
                        steps  = c(100, 100, 100, 25, 50, 200, 400, 25),
                        sig_b  = c(0.5, 0, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5),
                        n_rep  = c(2000, 2000, 1000, 1000, 1000, 1000, 1000, 1000))
herd_tab <- do.call(rbind, lapply(seq_len(nrow(herd_plan)), function(r)
  with(herd_plan[r, ], herd_rates(n_rep, n_anim, steps, sig_b))))
herd_uneq <- herd_rates(2000, 5, function() sample(20:200, 5, replace = TRUE), 0.5)
herd_tab$mc_se <- sqrt(herd_tab$pool * (1 - herd_tab$pool) / herd_tab$n_rep)

herd_cell <- function(a, s, g) herd_tab[herd_tab$n_anim == a & herd_tab$steps == s & herd_tab$sig_b == g, ]
h_main <- herd_cell(5, 100, 0.5); h_null <- herd_cell(5, 100, 0); h_20 <- herd_cell(20, 100, 0.5)
h_25a <- herd_cell(5, 25, 0.5); h_25b <- herd_cell(20, 25, 0.5); h_400 <- herd_cell(5, 400, 0.5)
h_sig <- herd_tab[herd_tab$sig_b == 0.5 & herd_tab$n_anim == 5, ]
rej_sand <- function(n_anim) 2 * pt(-qnorm(0.975) * sqrt((n_anim - 1) / n_anim), n_anim - 1)
rej_zt <- function(n_anim) 2 * pt(-qnorm(0.975), n_anim - 1)
# Monte Carlo standard error of the measured variance design effect (normal theory)
de_var_se <- h_main$de_var * sqrt(2 / (h_main$n_rep - 1))
de_gap <- abs(h_main$de_var - herd_de(0.5, 100, vw_host))
stopifnot(de_gap < de_var_se)

## ---- fig-herd ----
curve_df <- data.frame(steps = exp(seq(log(20), log(450), length.out = 120)))
curve_df$this_track <- herd_rej(herd_de(0.5, curve_df$steps, vw_host))
curve_df$independent <- herd_rej(herd_de(0.5, curve_df$steps, vw_iid))
sig_tab <- herd_tab[herd_tab$sig_b == 0.5, ]
pts_df <- rbind(
  data.frame(steps = sig_tab$steps * ifelse(sig_tab$n_anim == 20, 1.06, 1),  # nudge right
             rate = sig_tab$pool, se = sig_tab$mc_se,
             test = ifelse(sig_tab$n_anim == 5, "pooled, 5 animals", "pooled, 20 animals")),
  data.frame(steps = h_sig$steps, rate = h_sig$rob, se = NA, test = "sandwich, 5 animals"),
  data.frame(steps = h_sig$steps, rate = h_sig$two, se = NA, test = "two-stage t, 5 animals"))
pts_df$test <- factor(pts_df$test, levels = c("pooled, 5 animals", "pooled, 20 animals",
                                              "sandwich, 5 animals", "two-stage t, 5 animals"))
ggplot() +
  geom_hline(yintercept = 0.05, colour = "#2c3a31", linetype = "dotted", linewidth = 0.5) +
  geom_line(data = curve_df, aes(steps, independent), colour = "#8a9a8f",
            linetype = "dashed", linewidth = 0.6) +
  geom_line(data = curve_df, aes(steps, this_track), colour = "#275139", linewidth = 0.8) +
  geom_errorbar(data = pts_df[!is.na(pts_df$se), ],
                aes(steps, ymin = rate - 2 * se, ymax = rate + 2 * se, colour = test),
                width = 0.04, linewidth = 0.5) +
  geom_point(data = pts_df, aes(steps, rate, colour = test, shape = test), size = 2.4) +
  annotate("text", x = 150, y = herd_rej(herd_de(0.5, 150, vw_iid)) + 0.06,
           label = "independent candidates", colour = "#5d6b61", size = 3, hjust = 1) +
  annotate("text", x = 140, y = herd_rej(herd_de(0.5, 140, vw_host)) - 0.07,
           label = "this track", colour = "#275139", size = 3, hjust = 0) +
  scale_x_log10(breaks = c(25, 50, 100, 200, 400)) +
  scale_colour_manual(values = c("#275139", "#b5534e", "#c9b458", "#16241d"), name = NULL) +
  scale_shape_manual(values = c(16, 17, 15, 18), name = NULL) +
  scale_y_continuous(limits = c(0, 0.9), breaks = seq(0, 0.9, 0.1)) +
  labs(x = "steps per animal (log scale)", y = "false positive rate") +
  theme_minimal(base_size = 11) + te_canvas +
  theme(panel.grid.minor = element_blank(), legend.position = "bottom",
        axis.text = element_text(colour = "#46604a")) +
  guides(colour = guide_legend(nrow = 2), shape = guide_legend(nrow = 2))

## ---- herd-mgcv ----
library(mgcv)
set.seed(26092602)
demo_steps <- c(30, 60, 100, 160, 250)
demo <- draw_herd(5, demo_steps, beta_true, 0.5)
n_demo <- nrow(demo$z)
demo_long <- data.frame(stratum = rep(seq_len(n_demo), times = K + 1),
                        used = rep(c(1, rep(0, K)), each = n_demo),
                        x = as.vector(demo$z),
                        id = factor(rep(demo$who, times = K + 1)),
                        one = 1)

# pooled: this post's likelihood with optim, and the Newton version used above
clogit_nll_herd <- function(b, zz) { eta <- zz * b; -sum(eta[, 1] - log(rowSums(exp(eta)))) }
opt_demo <- optim(0, clogit_nll_herd, zz = demo$z, method = "BFGS", hessian = TRUE,
                  control = list(reltol = 1e-10))
nt_demo <- clogit_newton(demo$z, rep(1L, n_demo), 1)
stopifnot(abs(opt_demo$par - nt_demo$b) < 1e-5)

# mgcv: the second response column is read as the stratum index
gam_strat <- gam(cbind(one, stratum) ~ x, family = cox.ph(), weights = used, data = demo_long)
gam_flat <- gam(one ~ x, family = cox.ph(), weights = used, data = demo_long)
stopifnot(abs(coef(gam_strat)[["x"]] - nt_demo$b) < 1e-6,
          abs(sqrt(vcov(gam_strat)["x", "x"]) - 1 / sqrt(nt_demo$info)) < 1e-6)

# a random slope for each animal
gam_re <- gam(cbind(one, stratum) ~ x + s(x, id, bs = "re"), family = cox.ph(),
              weights = used, data = demo_long, method = "REML")
re_row <- summary(gam_re)$p.table["x", ]
invisible(capture.output(re_vc <- gam.vcomp(gam_re)))
# gam.vcomp() returns the standard deviations with intervals as a matrix (mgcv 1.9-1), as the
# vc element of a list (mgcv 1.9-4), or as a plain vector when it cannot form intervals
re_vm <- if (is.list(re_vc)) re_vc$vc else re_vc
re_sd <- as.numeric(if (is.matrix(re_vm)) re_vm[1, "std.dev"] else re_vm[1])
af_demo <- clogit_newton(demo$z, demo$who, 5)
dl_demo <- dl_pool(af_demo$b, 1 / sqrt(af_demo$info))
two_demo <- c(est = mean(af_demo$b), se = sd(af_demo$b) / sqrt(5))
demo_w <- 1 / (1 / af_demo$info + dl_demo[["tau2"]]); demo_w <- demo_w / sum(demo_w)
stopifnot(abs(re_row[["Pr(>|z|)"]] - 2 * pnorm(-abs(re_row[["z value"]]))) < 1e-10,
          which.min(af_demo$b) == 1)
# the weighted standard error with the REML between-animal variance plugged in
se_w_reml <- 1 / sqrt(sum(1 / (1 / af_demo$info + re_sd^2)))
stopifnot(abs(se_w_reml - re_row[["Std. Error"]]) < 5e-4)
p_t4 <- 2 * pt(-abs(re_row[["z value"]]), 4)
