Predict method for ratio models

Compute posterior predictions for new data from a fitted ratio model.

Usage

# S3 method for class 'ratiod_fit'
predict(
  object,
  newdata,
  type = c("response", "link"),
  component = c("ratio", "numerator", "denominator", "all"),
  summary = TRUE,
  probs = c(0.025, 0.5, 0.975),
  re_formula = NULL,
  allow_new_levels = FALSE,
  coords.0 = NULL,
  include_spatial = TRUE,
  return_spatial = FALSE,
  n_samples = NULL,
  ...
)

Arguments

object

A ratiod_fit object

newdata

Data frame with new observations. Must contain all predictor variables used in the original model.

type

Type of prediction: "response" for fitted values on the response scale, "link" for linear predictor scale.

component

Which component to predict: "ratio" (default), "numerator", "denominator", or "all".

summary

Logical; if TRUE, return summary statistics instead of full posterior draws (default TRUE).

probs

Quantiles to compute if summary = TRUE.

re_formula

Formula for random effects in prediction. Use NULL to include all random effects (if new levels match), NA or ~ 0 to exclude random effects (population-level prediction).

allow_new_levels

Logical; if TRUE, allows new group levels not in the original data (predictions use population mean).

coords.0

Matrix of spatial coordinates for new prediction locations (required for GP/HSGP spatial models). Should be N x 2 matrix with same coordinate system as training data.

include_spatial

Logical; if TRUE (default), include spatial random effects in predictions. Set to FALSE for fixed-effects-only predictions.

return_spatial

Logical; if TRUE, return spatial effect samples at new locations as w.0.samples in the output (similar to spOccupancy).

n_samples

Number of posterior samples to draw for backends that don't store samples directly (e.g., Laplace, VI). Default uses all available samples for HMC/PG.

...

Ignored

Value

If summary = TRUE, a data frame with posterior summaries. If summary = FALSE, a matrix of posterior draws (rows = draws, cols = obs). If return_spatial = TRUE, returns a list with predictions and w.0.samples.

Examples

if (FALSE) { # \dontrun{
# Generate synthetic data
set.seed(321)
n <- 50
df <- data.frame(
  count = rpois(n, lambda = 18),
  effort = rgamma(n, shape = 9, rate = 1),
  depth = rnorm(n),
  season = sample(c("summer", "winter"), n, replace = TRUE)
)

# Fit model
fit <- tratio(
  count | effort ~ depth + season,
  data = df,
  family = ratiod_poisson_gamma(),
  mode = "hmc",
  control = list(iter = 200, warmup = 100, chains = 1)
)

# Predict for new data
new_df <- data.frame(depth = c(10, 20, 30), season = "summer")
predict(fit, newdata = new_df)

# Population-level prediction (no random effects)
predict(fit, newdata = new_df, re_formula = NA)

# Get full posterior draws
predict(fit, newdata = new_df, summary = FALSE)

# --- Spatial prediction example (GP) ---
# Fit model with GP spatial effects
df$x <- runif(n)
df$y <- runif(n)
fit_gp <- tratio(
  count | effort ~ depth,
  data = df,
  spatial = spatial_gp(coords = c("x", "y")),
  family = ratiod_poisson_gamma(),
  control = list(iter = 200, warmup = 100, chains = 1)
)

# Predict at new locations (kriging)
new_coords <- matrix(runif(20), ncol = 2)
new_df <- data.frame(depth = rnorm(10))
pred <- predict(fit_gp, newdata = new_df, coords.0 = new_coords)

# Return spatial effect samples (like spOccupancy)
pred_spatial <- predict(fit_gp, newdata = new_df, coords.0 = new_coords,
                        return_spatial = TRUE)
str(pred_spatial$w.0.samples)  # [n_samples, n_new]

# --- Areal spatial prediction (ICAR/BYM2) ---
# Predict for existing regions (lookup)
new_df <- data.frame(region = c("A", "B"), depth = c(1, 2))
predict(fit_icar, newdata = new_df)
} # }