# Checking a state-space movement model
# https://tidyecology.com/posts/checking-a-state-space-model/
#
# 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-01

## ---- setup ----
suppressMessages({library(ggplot2); library(dplyr); library(tidyr)})
ink<-"#16241d"; body<-"#2c3a31"; forest<-"#275139"; sage<-"#93a87f"; paper<-"#f5f4ee"
line<-"#dad9ca"; faint<-"#5d6b61"; gold<-"#cda23f"; red<-"#b5534e"
theme_te <- function(base=12){
  theme_minimal(base_size=base) +
  theme(plot.background=element_rect(fill=paper,colour=NA),
        panel.background=element_rect(fill=paper,colour=NA),
        panel.grid.minor=element_blank(),
        panel.grid.major=element_line(colour=line,linewidth=.3),
        axis.title=element_text(colour=body), axis.text=element_text(colour=faint),
        plot.title=element_text(colour=ink,face="bold",size=base+1),
        plot.subtitle=element_text(colour=faint,size=base-2),
        strip.text=element_text(colour=ink,face="bold"),
        legend.title=element_text(colour=body,size=base-2),
        legend.text=element_text(colour=faint,size=base-2))
}

## ---- 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)), "}$")
}

## ---- simulate ----
set.seed(5310)
n<-500; gamma_t<-0.7; sigma_t<-4; tau_t<-6
vx<-vy<-numeric(n)
vx[1]<-rnorm(1,0,sigma_t/sqrt(1-gamma_t^2)); vy[1]<-rnorm(1,0,sigma_t/sqrt(1-gamma_t^2))
for(t in 2:n){ vx[t]<-gamma_t*vx[t-1]+rnorm(1,0,sigma_t); vy[t]<-gamma_t*vy[t-1]+rnorm(1,0,sigma_t) }
px<-cumsum(vx); py<-cumsum(vy); ox<-px+rnorm(n,0,tau_t); oy<-py+rnorm(n,0,tau_t)

## ---- filters ----
## correct: correlated random walk (position + velocity), returns standardised innovations
kf_crw<-function(y,g,s2,h2){
  n<-length(y); Tm<-matrix(c(1,0,g,g),2,2); Q<-s2*matrix(c(1,1,1,1),2,2); Z<-matrix(c(1,0),1,2)
  a<-c(y[1],0); P<-matrix(c(h2,0,0,s2/(1-g^2)),2,2); ll<-0; r<-rep(NA,n)
  for(t in 2:n){ ap<-as.vector(Tm%*%a); Pp<-Tm%*%P%*%t(Tm)+Q
    v<-y[t]-as.vector(Z%*%ap); Ft<-as.vector(Z%*%Pp%*%t(Z))+h2; K<-as.vector(Pp%*%t(Z))/Ft
    a<-ap+K*v; P<-Pp-(K%*%Z)%*%Pp; ll<-ll-0.5*(log(2*pi)+log(Ft)+v^2/Ft); r[t]<-v/sqrt(Ft) }
  list(ll=ll, r=r) }
## wrong: random walk on position, no persistence
kf_rw<-function(y,s2,h2){
  n<-length(y); ll<-0; r<-rep(NA,n); a<-y[1]; P<-h2
  for(t in 2:n){ ap<-a; Pp<-P+s2; v<-y[t]-ap; Ft<-Pp+h2; K<-Pp/Ft
    a<-ap+K*v; P<-Pp-K*Pp; ll<-ll-0.5*(log(2*pi)+log(Ft)+v^2/Ft); r[t]<-v/sqrt(Ft) }
  list(ll=ll, r=r) }

nA<-function(p){g<-plogis(p[1]);s2<-exp(p[2]);h2<-exp(p[3]);-(kf_crw(ox,g,s2,h2)$ll+kf_crw(oy,g,s2,h2)$ll)}
fA<-optim(c(0,log(16),log(16)),nA,method="Nelder-Mead",control=list(reltol=1e-10,maxit=3000))
gA<-plogis(fA$par[1]);s2A<-exp(fA$par[2]);h2A<-exp(fA$par[3])
nB<-function(p){s2<-exp(p[1]);h2<-exp(p[2]);-(kf_rw(ox,s2,h2)$ll+kf_rw(oy,s2,h2)$ll)}
fB<-optim(c(log(16),log(16)),nB,method="Nelder-Mead",control=list(reltol=1e-10,maxit=3000))
s2B<-exp(fB$par[1]);h2B<-exp(fB$par[2])
aicA<-2*3+2*fA$value; aicB<-2*2+2*fB$value
c(gamma=round(gA,3), sigma=round(sqrt(s2A),2), tau=round(sqrt(h2A),2), dAIC=round(aicB-aicA,1))

## ---- residuals ----
rAx<-kf_crw(ox,gA,s2A,h2A)$r[-1]; rAy<-kf_crw(oy,gA,s2A,h2A)$r[-1]
rBx<-kf_rw(ox,s2B,h2B)$r[-1];     rBy<-kf_rw(oy,s2B,h2B)$r[-1]
rApool<-c(rAx,rAy); rBpool<-c(rBx,rBy)
qqcor<-function(r){q<-qqnorm(r,plot.it=FALSE); cor(q$x,q$y)}
acfA<-acf(rAx,plot=FALSE,lag.max=18); acfB<-acf(rBx,plot=FALSE,lag.max=18)
bnd<-1.96/sqrt(length(rBx))
lbA<-c(Box.test(rAx,10,"Ljung-Box")$p.value, Box.test(rAy,10,"Ljung-Box")$p.value)   # east, north
lbB<-c(Box.test(rBx,10,"Ljung-Box")$p.value, Box.test(rBy,10,"Ljung-Box")$p.value)
qq_A<-qqcor(rApool); qq_B<-qqcor(rBpool)
a234<-sprintf("%.3f", acfB$acf[3:5,1,1])   # lags 2, 3, 4 of the wrong model
c(qq_correct=round(qq_A,4), qq_wrong=round(qq_B,4), LB_correct=round(lbA,3), LB_wrong=signif(lbB,3))

## ---- fig-qq ----
qq_df<-function(r,lab){q<-qqnorm(r,plot.it=FALSE); data.frame(theo=q$x, samp=q$y, model=lab)}
qq<-bind_rows(qq_df(rApool,"Correct: CRW state-space"), qq_df(rBpool,"Wrong: random walk (no persistence)"))
ggplot(qq,aes(theo,samp))+
  geom_abline(slope=1,intercept=0,colour=faint,linetype="dashed")+
  geom_point(colour=forest,size=.7,alpha=.5)+
  facet_wrap(~model)+
  labs(title="Both models pass the marginal check",
       subtitle="Normal QQ plots of standardised one-step-ahead residuals look straight for each",
       x="Theoretical quantile", y="Sample quantile")+theme_te()

## ---- fig-acf ----
acf_df<-function(a,lab){data.frame(lag=a$lag[-1,,1], acf=a$acf[-1,,1], model=lab)}
ac<-bind_rows(acf_df(acfA,"Correct: CRW state-space"), acf_df(acfB,"Wrong: random walk (no persistence)"))
ggplot(ac,aes(lag,acf))+
  geom_hline(yintercept=0,colour=faint,linewidth=.3)+
  geom_hline(yintercept=c(-bnd,bnd),colour=red,linetype="dashed",linewidth=.4)+
  geom_segment(aes(xend=lag,yend=0),colour=forest,linewidth=.8)+
  geom_point(colour=forest,size=1.1)+
  facet_wrap(~model)+
  labs(title="Only the autocorrelation check catches the wrong model",
       subtitle="Residual ACF stays inside the bounds when correct; spikes at short lags when persistence is omitted",
       x="Lag", y="Autocorrelation")+theme_te()
