% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/compare_forecasts.R
\name{compare_forecasts}
\alias{compare_forecasts}
\title{Compare Two Sequential Forecasters}
\usage{
compare_forecasts(
  p,
  q,
  y,
  scoring_rule = c("brier", "spherical", "log"),
  alpha = 0.05,
  cs_type = NULL,
  compute_cs = TRUE,
  compute_e = TRUE,
  v_opt = 10,
  boundary = "mixture",
  lcb_only = FALSE,
  ucb_only = FALSE,
  eps = 1e-15,
  clip_max = 1e+07
)
}
\arguments{
\item{p}{Forecasts from forecaster 1. For binary outcomes, a numeric vector
of probabilities for event \code{y = 1}. For categorical outcomes, a numeric
matrix whose rows are probability vectors.}

\item{q}{Forecasts from forecaster 2, in the same format as \code{p}.}

\item{y}{Outcomes. For binary vector forecasts, a numeric vector in \verb{\{0, 1\}}.
For categorical matrix forecasts, integer class labels in \verb{\{1, ..., K\}}.}

\item{scoring_rule}{Character. Scoring rule used to compare forecasts.
Currently supports \code{"brier"}, \code{"spherical"}, and \code{"log"}.}

\item{alpha}{Numeric in \verb{(0, 1)}. Significance level. Default is \code{0.05}.}

\item{cs_type}{Character or \code{NULL}. Confidence sequence type:
\code{"bernstein"}, \code{"hoeffding"}, \code{"asymptotic"}, or \code{"none"}.
If \code{NULL}, the wrapper uses \code{"bernstein"} for bounded scoring rules
(\code{"brier"} and \code{"spherical"}) and \code{"asymptotic"} for \code{"log"}.}

\item{compute_cs}{Logical. If \code{TRUE}, compute a confidence sequence.
Default is \code{TRUE}.}

\item{compute_e}{Logical. If \code{TRUE}, compute two one-sided e-processes.
Default is \code{TRUE}. This is only allowed for bounded score differences
under the current wrapper, namely \code{"brier"} and \code{"spherical"}.}

\item{v_opt}{Numeric > 0. Intrinsic time at which the mixture boundary or
e-process is tuned to be tightest. Default is \code{10}.}

\item{boundary}{Character. Boundary type passed to \code{\link[=cs_hoeffding]{cs_hoeffding()}} or
\code{\link[=cs_bernstein]{cs_bernstein()}}. Default is \code{"mixture"}.}

\item{lcb_only}{Logical. If \code{TRUE}, compute a lower one-sided empirical
Bernstein CS. Only used when \code{cs_type = "bernstein"}.}

\item{ucb_only}{Logical. If \code{TRUE}, compute an upper one-sided empirical
Bernstein CS. Only used when \code{cs_type = "bernstein"}.}

\item{eps}{Numeric. Probability floor passed to \code{\link[=log_score]{log_score()}} when
\code{scoring_rule = "log"}. Default is \code{1e-15}.}

\item{clip_max}{Numeric. Maximum e-process value before clipping. Passed to
\code{\link[=eprocess]{eprocess()}}. Default is \code{1e7}.}
}
\value{
A \code{data.frame} with one row per time point and columns:
\describe{
\item{\code{t}}{Time index.}
\item{\code{score_p}}{Pointwise score of forecaster \code{p}.}
\item{\code{score_q}}{Pointwise score of forecaster \code{q}.}
\item{\code{delta}}{Pointwise score difference, \code{score_p - score_q}.}
\item{\code{estimate}}{Running mean score difference. Positive values favour
forecaster \code{p}; negative values favour forecaster \code{q}.}
\item{\code{lower}, \code{upper}}{Confidence sequence bounds. These are \code{NA} if
\code{compute_cs = FALSE} or \code{cs_type = "none"}.}
\item{\code{e_pq}, \code{e_qp}}{One-sided e-processes. \code{e_pq} tests whether
forecaster \code{p} outperforms \code{q}; \code{e_qp} tests the reverse direction.
These are \code{NA} if \code{compute_e = FALSE}.}
}
}
\description{
Computes pointwise scores for two probabilistic forecasters and compares
them sequentially using confidence sequences and, when valid finite-sample
bounds are available, e-processes.
}
\details{
This is a convenience wrapper around \code{\link[=brier_score]{brier_score()}}, \code{\link[=spherical_score]{spherical_score()}},
\code{\link[=log_score]{log_score()}}, \code{\link[=cs_hoeffding]{cs_hoeffding()}}, \code{\link[=cs_bernstein]{cs_bernstein()}}, \code{\link[=cs_asymptotic]{cs_asymptotic()}}, and
\code{\link[=eprocess]{eprocess()}}. It is designed for the common workflow where the user has two
forecast streams \code{p} and \code{q}, an outcome stream \code{y}, and wants a single tidy
output object.

All scoring rules in \code{seqcomp} are positively oriented: higher scores are
better. Therefore
\deqn{\hat{\delta}_t = S(p_t, y_t) - S(q_t, y_t)}
is positive when forecaster \code{p} performs better than forecaster \code{q} at time
\code{t}.

For \code{"brier"} and \code{"spherical"}, score differences are bounded in \verb{[-1, 1]}.
The wrapper therefore uses \code{c = 1} for Hoeffding-style confidence sequences
and \code{c = 2} for empirical Bernstein confidence sequences and e-processes.

For \code{"log"}, score differences are unbounded. The wrapper therefore defaults
to \code{\link[=cs_asymptotic]{cs_asymptotic()}} and refuses to compute finite-sample e-processes. For
binary log-score comparisons where the Winkler construction is appropriate,
use \code{\link[=winkler_compare]{winkler_compare()}} instead.
}
\section{Interpretation}{

The confidence sequence estimates the running average score advantage of
\code{p} over \code{q}. If the whole interval lies above zero, the data favour \code{p};
if the whole interval lies below zero, the data favour \code{q}.

The e-processes are evidence processes for one-sided null hypotheses. At
level \code{alpha}, the two-sided rejection threshold used by \code{\link[=eprocess]{eprocess()}} is
\code{2 / alpha}.
}

\examples{
set.seed(1)
y <- rbinom(200, 1, 0.5)
p <- rep(0.5, 200)
q <- runif(200)

out <- compare_forecasts(p, q, y, scoring_rule = "brier")
tail(out)

}
