# Brownian motion or Ornstein-Uhlenbeck?
# https://tidyecology.com/posts/brownian-motion-versus-ou/
#
# 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-08

## ---- setup ----
library(ggplot2)

te_paper  <- "#f5f4ee"
te_ink    <- "#16241d"
te_body   <- "#2c3a31"
te_forest <- "#275139"
te_rust   <- "#b5534e"
te_gold   <- "#c9b458"
te_line   <- "#dad9ca"

theme_datasheet <- function() {
  theme_minimal(base_size = 12) +
    theme(plot.background  = element_rect(fill = te_paper, colour = NA),
          panel.background = element_rect(fill = te_paper, colour = NA),
          panel.grid.major = element_line(colour = te_line, linewidth = 0.3),
          panel.grid.minor = element_blank(),
          text             = element_text(colour = te_body),
          plot.title       = element_text(colour = te_ink, face = "bold"),
          plot.subtitle    = element_text(colour = te_body),
          axis.text        = element_text(colour = te_body))
}

## ---- sci-tex-helper ----
sci_tex <- function(x, digits = 2) {
  s <- formatC(x, format = "e", digits = digits)
  paste0("$", sub("e.*", "", s), " \\times 10^{", as.integer(sub(".*e", "", s)), "}$")
}

## ---- trees ----
sim_tree <- function(n_tip, shape = c("yule", "coalescent")) {
  shape     <- match.arg(shape)
  clades    <- as.list(seq_len(n_tip))
  split_age <- matrix(0, n_tip, n_tip)
  age <- 0
  k   <- n_tip
  while (k > 1L) {
    rate_k <- if (shape == "yule") k else k * (k - 1) / 2
    age    <- age + rexp(1, rate = rate_k)
    pick   <- sample.int(k, 2)
    g1 <- clades[[pick[1]]]
    g2 <- clades[[pick[2]]]
    split_age[g1, g2] <- age
    split_age[g2, g1] <- age
    clades[[pick[1]]] <- c(g1, g2)
    clades[[pick[2]]] <- NULL
    k <- k - 1L
  }
  shared <- (age - split_age) / age
  diag(shared) <- 1
  shared
}

ou_vcv <- function(shared, alpha) {
  exp(-2 * alpha * (1 - shared)) * (-expm1(-2 * alpha * shared)) / (2 * alpha)
}

set.seed(4127)
tree_demo <- sim_tree(30, "yule")
gap_1e3 <- max(abs(ou_vcv(tree_demo, 1e-3) - tree_demo))
gap_1e6 <- max(abs(ou_vcv(tree_demo, 1e-6) - tree_demo))

## ---- forwardcheck ----
alpha_chk <- 2
s_node    <- 0.6
n_draw    <- 200000
ou_step <- function(x_from, len, alpha) {
  x_from * exp(-alpha * len) +
    sqrt(-expm1(-2 * alpha * len) / (2 * alpha)) * rnorm(length(x_from))
}
set.seed(8830)
x_node <- ou_step(rep(0, n_draw), s_node, alpha_chk)
x_tip1 <- ou_step(x_node, 1 - s_node, alpha_chk)
x_tip2 <- ou_step(x_node, 1 - s_node, alpha_chk)
x_tip3 <- ou_step(rep(0, n_draw), 1, alpha_chk)
emp_cov <- cov(cbind(x_tip1, x_tip2, x_tip3))
shared_chk <- matrix(c(1, s_node, 0, s_node, 1, 0, 0, 0, 1), 3, 3)
thy_cov <- ou_vcv(shared_chk, alpha_chk)
cov_gap <- max(abs(emp_cov - thy_cov))
cov_se  <- sqrt(2 * max(thy_cov)^2 / n_draw)

## ---- fig-cov ----
alpha_show <- c(0.25, 1, 4)
s_seq <- seq(0, 1, length.out = 101)
cov_df <- rbind(
  data.frame(s = s_seq, v = s_seq, model = "Brownian motion"),
  do.call(rbind, lapply(alpha_show, function(a_val) {
    data.frame(s = s_seq, v = ou_vcv(s_seq, a_val),
               model = sprintf("OU, alpha = %g", a_val))
  })))
cov_df$model <- factor(cov_df$model, levels = unique(cov_df$model))
ggplot(cov_df, aes(s, v, colour = model)) +
  geom_line(linewidth = 0.9) +
  scale_colour_manual(values = c(te_ink, te_forest, te_gold, te_rust), name = NULL) +
  labs(x = "shared path from the root (tree height = 1)",
       y = "covariance of the two tips",
       title = "The pull flattens the covariance",
       subtitle = "sigma squared = 1, fixed root at the optimum") +
  theme_datasheet() +
  theme(legend.position = "bottom")

## ---- fitting ----
alpha_min <- 1e-3
alpha_max <- log(2) / 0.01
n_coarse  <- 20

prof_ll <- function(y, r_mat) {
  n_obs <- length(y)
  ch  <- chol(r_mat)
  y_w <- backsolve(ch, y, transpose = TRUE)
  o_w <- backsolve(ch, rep(1, n_obs), transpose = TRUE)
  mu_hat <- sum(o_w * y_w) / sum(o_w^2)
  s2_hat <- sum((y_w - mu_hat * o_w)^2) / n_obs
  -n_obs / 2 * (log(2 * pi * s2_hat) + 1) - sum(log(diag(ch)))
}

aicc <- function(loglik, n_par, n_obs) {
  -2 * loglik + 2 * n_par + 2 * n_par * (n_par + 1) / (n_obs - n_par - 1)
}

fit_bm_ou <- function(y, shared) {
  n_obs <- length(y)
  ll_bm <- prof_ll(y, shared)
  ll_a  <- function(log_a) prof_ll(y, ou_vcv(shared, exp(log_a)))
  la_grid <- seq(log(alpha_min), log(alpha_max), length.out = n_coarse)
  ll_grid <- vapply(la_grid, ll_a, 0)
  i_best  <- which.max(ll_grid)
  bracket <- la_grid[c(max(1, i_best - 1), min(n_coarse, i_best + 1))]
  opt <- optimize(ll_a, bracket, maximum = TRUE)
  if (opt$objective < ll_grid[i_best]) {
    opt <- list(maximum = la_grid[i_best], objective = ll_grid[i_best])
  }
  c(ll_bm = ll_bm, ll_ou = opt$objective, alpha = exp(opt$maximum),
    pick_ou = aicc(opt$objective, 3, n_obs) < aicc(ll_bm, 2, n_obs))
}

sim_fit <- function(n_tip, n_rep, shape = "yule", alpha_true = 0, me_var = 0) {
  out <- t(replicate(n_rep, {
    shared <- sim_tree(n_tip, shape)
    v_true <- if (alpha_true == 0) shared else ou_vcv(shared, alpha_true)
    y <- drop(crossprod(chol(v_true), rnorm(n_tip))) + rnorm(n_tip, 0, sqrt(me_var))
    fit_bm_ou(y, shared)
  }))
  as.data.frame(out)
}

set.seed(5511)
one_fit <- fit_bm_ou(drop(crossprod(chol(tree_demo), rnorm(30))), tree_demo)

## ---- nullrates ----
tip_grid <- c(25, 50, 100)
n_rep_bm <- 1000
n_rep_sh <- 500

set.seed(20260825)
null_yule <- lapply(tip_grid, function(n_tip) sim_fit(n_tip, n_rep_bm, "yule"))
set.seed(20260826)
null_coal <- lapply(tip_grid, function(n_tip) sim_fit(n_tip, n_rep_sh, "coalescent"))

rate_tab <- function(fits, lab) {
  p_hat <- vapply(fits, function(f) mean(f$pick_ou), 0)
  n_r   <- vapply(fits, nrow, 0)
  data.frame(n_tip = tip_grid, rate = p_hat,
             se = sqrt(p_hat * (1 - p_hat) / n_r), tree = lab)
}
rates_null <- rbind(rate_tab(null_yule, "Yule-like tree"),
                    rate_tab(null_coal, "coalescent-like tree"))

chibar_rate <- vapply(tip_grid, function(n_tip) {
  lr_cut <- aicc(0, 3, n_tip) - aicc(0, 2, n_tip)
  0.5 * pchisq(lr_cut, df = 1, lower.tail = FALSE)
}, 0)
lr_cut_25 <- aicc(0, 3, 25) - aicc(0, 2, 25)

ry  <- rates_null[rates_null$tree == "Yule-like tree", ]
rc  <- rates_null[rates_null$tree == "coalescent-like tree", ]
ratio_y <- ry$rate / chibar_rate
diff_y  <- ry$rate[3] - ry$rate[1]
diff_se <- sqrt(ry$se[3]^2 + ry$se[1]^2)
ratio_c <- rc$rate / ry$rate
at_floor <- vapply(null_yule, function(f) mean(f$alpha < alpha_min * 1.01), 0)
at_ceil  <- vapply(null_yule, function(f) mean(f$alpha > alpha_max * 0.99), 0)
interior <- 1 - at_floor

## ---- fig-rates ----
bench_df <- data.frame(n_tip = tip_grid, rate = chibar_rate)
ggplot(rates_null, aes(n_tip, rate, colour = tree)) +
  geom_line(data = bench_df, aes(n_tip, rate), inherit.aes = FALSE,
            linetype = "dashed", colour = te_body, linewidth = 0.6) +
  geom_errorbar(aes(ymin = rate - 1.96 * se, ymax = rate + 1.96 * se),
                width = 3, linewidth = 0.5) +
  geom_line(linewidth = 0.9) +
  geom_point(size = 2.4) +
  scale_colour_manual(values = c("coalescent-like tree" = te_rust, "Yule-like tree" = te_forest),
                      name = NULL) +
  scale_x_continuous(breaks = tip_grid) +
  scale_y_continuous(limits = c(0, NA)) +
  labs(x = "number of tips", y = "share of Brownian datasets where AICc picks OU",
       title = "More tips do not cure the false pull",
       subtitle = "dashed: the large-sample boundary benchmark; bars: 95% Monte Carlo intervals") +
  theme_datasheet() +
  theme(legend.position = "bottom")

## ---- falsealpha ----
alpha_true <- log(2) / 0.5
set.seed(7731)
pos_yule <- lapply(tip_grid, function(n_tip) sim_fit(n_tip, n_rep_sh, "yule",
                                                     alpha_true = alpha_true))
pos_rate <- vapply(pos_yule, function(f) mean(f$pick_ou), 0)
pos_se   <- sqrt(pos_rate * (1 - pos_rate) / n_rep_sh)


hl_false <- lapply(null_yule, function(f) log(2) / f$alpha[f$pick_ou == 1])
hl_med   <- vapply(hl_false, median, 0)
hl_below <- vapply(hl_false, function(h) mean(h < 1), 0)
hl_true  <- lapply(pos_yule, function(f) log(2) / f$alpha[f$pick_ou == 1])
hl_true_med <- vapply(hl_true, median, 0)
i50 <- which(tip_grid == 50)
hl_max_50  <- max(hl_false[[i50]])
hl_half_50 <- mean(hl_false[[i50]] < 0.5)

## ---- fig-halflife ----
hl_df <- rbind(
  data.frame(hl = hl_false[[i50]], source = "Brownian data, OU picked"),
  data.frame(hl = hl_true[[i50]], source = "OU data (half-life 0.5), OU picked"))
ggplot(hl_df, aes(hl, fill = source)) +
  geom_histogram(aes(y = after_stat(density)), bins = 30, position = "identity",
                 alpha = 0.6, colour = NA) +
  geom_vline(xintercept = 0.5, linetype = "dashed", colour = te_ink, linewidth = 0.6) +
  scale_x_log10(breaks = c(0.05, 0.1, 0.2, 0.3, 0.5, 1)) +
  scale_fill_manual(values = c("Brownian data, OU picked" = te_rust,
                               "OU data (half-life 0.5), OU picked" = te_forest),
                    name = NULL) +
  labs(x = "fitted phylogenetic half-life, log(2) / alpha (tree height = 1)",
       y = "density",
       title = "False and real pulls overlap in half-life",
       subtitle = "50 tips, Yule-like trees; dashed: the true half-life of the OU data") +
  theme_datasheet() +
  theme(legend.position = "bottom")

## ---- measerror ----
me_var <- 0.05
set.seed(3390)
me_yule <- lapply(tip_grid, function(n_tip) sim_fit(n_tip, n_rep_sh, "yule",
                                                    me_var = me_var))
me_rate <- vapply(me_yule, function(f) mean(f$pick_ou), 0)
me_se   <- sqrt(me_rate * (1 - me_rate) / n_rep_sh)
me_hl   <- vapply(me_yule, function(f) median(log(2) / f$alpha[f$pick_ou == 1]), 0)
me_vs_pos <- me_rate - pos_rate
me_share  <- me_var / (1 + me_var)

## ---- fig-me ----
me_df <- rbind(
  data.frame(n_tip = tip_grid, rate = ry$rate, se = ry$se,
             data = "Brownian motion"),
  data.frame(n_tip = tip_grid, rate = me_rate, se = me_se,
             data = "Brownian motion + tip error (variance 0.05)"),
  data.frame(n_tip = tip_grid, rate = pos_rate, se = pos_se,
             data = "OU, half-life 0.5"))
ggplot(me_df, aes(n_tip, rate, colour = data)) +
  geom_errorbar(aes(ymin = rate - 1.96 * se, ymax = rate + 1.96 * se),
                width = 3, linewidth = 0.5) +
  geom_line(linewidth = 0.9) +
  geom_point(size = 2.4) +
  scale_colour_manual(values = c("Brownian motion" = te_ink,
                                 "Brownian motion + tip error (variance 0.05)" = te_rust,
                                 "OU, half-life 0.5" = te_gold),
                      name = NULL) +
  scale_x_continuous(breaks = tip_grid) +
  scale_y_continuous(limits = c(0, 1)) +
  guides(colour = guide_legend(ncol = 1)) +
  labs(x = "number of tips", y = "share of datasets where AICc picks OU",
       title = "Tip error looks like a pull, and more tips make it louder",
       subtitle = "Yule-like trees; bars: 95% Monte Carlo intervals") +
  theme_datasheet() +
  theme(legend.position = "bottom")
