Model Workflow and Diagnostics

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.

This article gives a compact workflow for fitting, comparing and diagnosing fixed-effect circular regression models with CircularRegression. It is designed as a pkgdown article for users who want to move quickly from a formula to predictions and residual checks.

Prepare a reproducible example

library(CircularRegression)

wrap_angle <- function(x) atan2(sin(x), cos(x))

set.seed(20260530)
n <- 120
x1 <- runif(n, -pi, pi)
x2 <- runif(n, -pi, pi)
z2 <- runif(n, 0.2, 1.8)

mu <- atan2(
  sin(x1) + 0.35 * z2 * sin(x2),
  cos(x1) + 0.35 * z2 * cos(x2)
)
y <- wrap_angle(mu + rnorm(n, sd = 0.12))

dat <- data.frame(y = y, x1 = x1, x2 = x2, z2 = z2)

Fit the main workflow

The default circular_regression() method is "two_step". It first fits the consensus model, then fits the homogeneous angular model using the selected reference direction.

fit <- circular_regression(y ~ x1 + x2:z2, data = dat)
fit
#> Call:
#> circular_regression(formula = y ~ x1 + x2:z2, data = dat)
#> 
#> Method: two_step 
#> Number of observations: 120 
#> 
#> Call:
#> angular(formula = formula, data = data, reference = c("name", 
#>     ref_name), initbeta = initbeta, control = control_angular, 
#>     na.action = na.action)
#> 
#> Reference angle: x1 
#> Maximum cosine: 0.9919 
#> Concentration parameter: 62.3 
#> 
#> Parameters (non-reference terms):
#>       Estimate Std. Error z value  P(|z|>.)    
#> x2:z2 0.353787   0.013713    25.8 < 2.2e-16 ***
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1

For direct control, the homogeneous and consensus models can be fitted separately.

fit_hom <- circular_regression(
  y ~ x1 + x2:z2,
  data = dat,
  method = "homogeneous",
  reference = c("name", "x1")
)

fit_cons <- circular_regression(
  y ~ x1 + x2:z2,
  data = dat,
  method = "consensus"
)

coef(fit_hom)
#> [1] 0.3537878
coef(fit_cons)
#>        x1     x2:z2 
#> 14.845713  3.088462

Predict on new angular covariates

Predictions are returned as angles in radians. The component form is useful when users want to plot or average fitted directions through their sine and cosine coordinates.

new_dat <- dat[1:6, c("x1", "x2", "z2")]

predict(fit, newdata = new_dat)
#> [1] -1.9412437 -0.5287170 -0.3458637 -2.9836322  1.8172714 -0.5849534
predict(fit, newdata = new_dat, type = "components")
#>             cos        sin
#> [1,] -0.3620325 -0.9321655
#> [2,]  0.8634549 -0.5044260
#> [3,]  0.9407830 -0.3390094
#> [4,] -0.9875502 -0.1573044
#> [5,] -0.2439871  0.9697785
#> [6,]  0.8337378 -0.5521605

Check residuals

Residuals are circular differences between observed and fitted directions, wrapped to the interval implied by atan2(sin(x), cos(x)).

res <- residuals(fit)
summary(res)
#>     Min.  1st Qu.   Median     Mean  3rd Qu.     Max. 
#> -0.33809 -0.07343  0.01129  0.01466  0.10391  0.29993

A simple diagnostic plot can be produced with base R.

plot(
  fitted(fit),
  res,
  xlab = "Fitted direction",
  ylab = "Circular residual",
  pch = 19,
  col = "gray30"
)
abline(h = 0, lty = 2)

The package also supplies plot() methods for fitted model objects when ggplot2 and gridExtra are installed.

Use the article in pkgdown

The pkgdown site groups this article with the introductory simulation vignette and the applied bison vignette. The site can be rebuilt locally with:

pkgdown::build_site()

The package examples and vignettes are deterministic, so the rendered site should be reproducible across clean R sessions.

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.