% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ratioReg.R
\name{ratioReg}
\alias{ratioReg}
\title{Estimate Population Size Using Ratio Regression}
\usage{
ratioReg(
  formula,
  data,
  ratioFormula = ~log(k + 1),
  model = c("auto", "M0", "M1"),
  criterion = c("AIC", "BIC"),
  estimator = c("SM", "HT"),
  weights = NULL,
  subset,
  confint = c("bootstrap", "none"),
  B = 1000,
  seed = NULL,
  maxCount = NULL,
  ...
)
}
\arguments{
\item{formula}{a formula identifying the observed count column. It must use
\code{~ 1}; for example \code{observed ~ 1}.}

\item{data}{a data frame or an object coercible to \code{data.frame}.}

\item{ratioFormula}{a one-sided formula used for the ratio regression on the
derived ratio-level data. The default is \code{~ log(k + 1)}.}

\item{model}{which ratio-regression model to use: \code{M0}, \code{M1}, or \code{auto} to
select between them by \code{criterion}.}

\item{criterion}{information criterion used when \code{model = "auto"}.}

\item{estimator}{which population-size estimator should be treated as the
primary one.}

\item{weights}{optional prior weights interpreted as multiplicities of
observed units.}

\item{subset}{optional logical expression selecting rows from \code{data}.}

\item{confint}{either \code{"bootstrap"} for percentile bootstrap intervals or
\code{"none"} to skip interval estimation.}

\item{B}{number of bootstrap replicates when \code{confint = "bootstrap"}.}

\item{seed}{optional random seed used for bootstrap sampling.}

\item{maxCount}{optional upper support bound. Counts larger than \code{maxCount}
are discarded before fitting.}

\item{...}{additional arguments passed to \code{\link[stats:model.frame]{stats::model.frame()}}.}
}
\value{
An object of class \code{singleRRatioReg} containing the fitted ratio-regression
models, model-selection criteria, derived ratio-level data, observed
frequencies, and population-size estimates.
}
\description{
Fits the ratio-regression approach for single-source capture-recapture
count data as a standalone estimator. The regression is performed on
neighbouring marginal-frequency ratios rather than on unit-level counts,
which is why this method is separate from the \code{singleRmodels()} family
framework used by \code{\link[=estimatePopsize]{estimatePopsize()}}.
}
\details{
Let \eqn{f_k} denote the observed frequency of units captured exactly
\eqn{k} times. Ratio regression models the neighbouring ratios
\eqn{r_k = f_{k + 1} / f_k}. The default model uses
\eqn{\log(r_k) = \beta_0 + \beta_1 \log(k + 1)} and weighted least squares
with weights \eqn{1 / (1 / f_k + 1 / f_{k + 1})}.

Two published models are supported:
\itemize{
\item \code{M0}: ratio regression without one-inflation term
\item \code{M1}: ratio regression with an additional one-inflation indicator
\code{I(k == 1)}
}

When \code{model = "auto"}, both models are fitted and compared by \code{criterion}.
Population size can then be extracted either through the Horvitz-Thompson
(\code{HT}) or semi-parametric (\code{SM}) estimator, with \code{estimator} selecting which
one is treated as primary by \code{\link[=popSizeEst]{popSizeEst()}}, \code{\link[=summary]{summary()}}, and \code{\link[=plot]{plot()}}.

Bootstrap intervals are percentile intervals. For fixed \code{model = "M0"} or
\code{model = "M1"} the bootstrap uses zero-count imputation based on the
primary estimator. For \code{model = "auto"} it uses the single-bootstrap
reselection scheme where model selection is repeated inside each bootstrap
sample.
}
\examples{
toy_counts <- data.frame(
  observed = c(rep(1, 50), rep(2, 30), rep(3, 15), rep(4, 6), rep(5, 2))
)

toy_fit <- ratioReg(
  observed ~ 1,
  data = toy_counts,
  model = "auto",
  estimator = "SM",
  confint = "none"
)

summary(toy_fit)
popSizeEst(toy_fit)
plot(toy_fit)

toy_tab <- aggregate(list(weight = rep(1, nrow(toy_counts))),
                     by = list(observed = toy_counts$observed),
                     FUN = sum)
ratioReg(
  observed ~ 1,
  data = toy_tab,
  weights = toy_tab$weight,
  model = "M0",
  confint = "none"
)

}
\seealso{
\code{\link[=estimatePopsize]{estimatePopsize()}} \code{\link[=popSizeEst]{popSizeEst()}}
}
\author{
Cyprian Jurkowski, Piotr Chlebicki, Maciej Beręsewicz
}
