# Model Workflow and Diagnostics

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.