% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/find_distr.R
\name{find.distr}
\alias{find.distr}
\title{Automatically select distribution families to be used for ROC smoothing.}
\usage{
find.distr(
  roc,
  candidates = c("normal", "gamma", "lognormal", "weibull"),
  search.mode = c("all_pairs", "per_group"),
  quiet = FALSE
)
}
\arguments{
\item{roc}{A \code{roc} object generated by the \ifelse{html}{\code{\link[pROC:roc]{roc()}}}{\code{roc()}} function.}

\item{candidates}{A character vector specifying the candidate distribution families to be tested. Options include \verb{“normal”}, \verb{“lognormal”}, \verb{“gamma”}, and \verb{“weibull”}. If \code{NULL}, all four families will be tested by default.}

\item{search.mode}{Character string specifying what search mode to use to select the best fitting distribution families. One of \code{"all_pairs"} or \code{"per_group"}. If \code{"all_pairs"}, all possible case and control distribution family combinations are tested jointly, and the pair that minimizes the combined AIC across both groups is selected and returned. If \code{"per_group"}, distribution families are tested independently for the case and control groups, and the distribution families that respectively minimize AIC within each group are selected and returned. Default is \code{"all_pairs"}. If  \code{"all_pairs"}mode fails, \code{"per_group"} mode is used as a fallback with warning message.}

\item{quiet}{Specifies whether to silence messages generated during distribution selection. Default value is \code{TRUE}.}
}
\value{
A named list containing the parameters associated with the best fitting case and control distribution families. The returned list can be passed directly to \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} for generation of a smooth ROC curve using the \code{"fitdistr"} method, and has the following elements:

\item{\code{density.controls}}{A character string specifying the distribution family selected for the control group.}
\item{\code{density.cases}}{A character string specifying the distribution family selected for the case group.}
\item{\code{start.controls}}{An optional named list of starting values for fitting the control distribution. Returned only for distribution families that require explicit starting values.}
\item{\code{start.cases}}{An optional named list of starting values for fitting the case distribution. Returned only for distribution families that require explicit starting values.}

Diagnostic information associated with model selection process is attached attributes, including all calculated AIC values and the final search mode.
}
\description{
Automatically selects the best fitting distribution families to be used when smoothing ROC curves via population probability density function estimation. It takes a raw \code{roc} object generated by the \ifelse{html}{\code{\link[pROC:roc]{roc()}}}{\code{roc()}} function of the ‘pROC’ package as input, fits up to four different candidate distribution families to both the case and control data, and then uses AIC to select and return the best fitting distribution types along with any associated start values. These returned parameters can then be directly passed to the \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} function of the ‘pROC’ package for generation of a smoothed ROC curve that approximates population-level diagnostic performance using the \code{"fitdistr"} method.
}
\details{
Similar to \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}}, all fits are internally performed using the \ifelse{html}{\code{\link[MASS:fitdistr]{fitdistr()}}}{\code{fitdistr()}} function of the ‘MASS’ package.  Method of moments is used to establish starting values for distribution types where they are explicitly needed. When using \code{\link[=find.distr]{find.distr()}} in tandem with \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}}, \code{\link[=get.fits]{get.fits()}} can be used to retrieve the final fits ultimate used by \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} for generation of the smooth ROC curve. Furthermore, \code{\link[=sm.coords]{sm.coords()}} can be used to calculate population-level diagnostic performance and cutoff estimates from the smoothed curve.
}
\examples{
# EXAMPLE USING LONG CALLS

# load packages and example blood biomarker data

library(pROC)
library(rocTools)
data(blood_data)

# build raw ROC curve

raw_roc <- roc(
  blood_data,
  response = "Diagnosis",
  predictor = "NfL"
)

# find best fitting case and control distribution
# families to use for ROC smoothing

best_fits <- find.distr(
  raw_roc,
  candidates = c("normal", "gamma", "lognormal", "weibull"),
  search.mode = "all_pairs",
  quiet = FALSE
)

# use best fitting families to build smooth ROC curve

smooth_roc <- smooth(
  raw_roc,
  method = "fitdistr",
  density.controls = best_fits$density.controls,
  density.cases = best_fits$density.cases,
  start.controls = best_fits$start.controls,
  start.cases = best_fits$start.cases
)

# EXAMPLE USING COMPACT CALLS

# load packages and example blood biomarker data

library(pROC)
library(rocTools)
data(blood_data)

# build raw ROC curve

raw_roc <- roc(blood_data$Diagnosis, blood_data$NfL)

# find best fitting case and controls distribution families
# and build smooth ROC curve in single call

smooth_roc <- do.call(
  smooth,
  c(list(raw_roc, method = "fitdistr"), find.distr(raw_roc))
)

}
\seealso{
\ifelse{html}{\link[pROC]{pROC-package}}{pROC-package} \cr
\ifelse{html}{\code{\link[pROC:roc]{roc()}}}{\code{pROC::roc()}} \cr
\ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{pROC::smooth()}} \cr
\ifelse{html}{\code{\link[MASS:fitdistr]{fitdistr()}}}{\code{MASS::fitdistr()}} \cr
\link{rocTools-package} \cr
\code{\link[=get.fits]{get.fits()}} \cr
\code{\link[=sm.coords]{sm.coords()}} \cr
\code{\link{blood_data}}
}
