% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sm_coords.R
\name{sm.coords}
\alias{sm.coords}
\title{Calculate diagnostic performance and cutoff estimates from smoothed ROC curves.}
\usage{
sm.coords(
  smooth.roc,
  type = c("best", "specificity", "sensitivity"),
  target.value = NULL,
  method = c("continuous", "grid"),
  quiet = FALSE
)
}
\arguments{
\item{smooth.roc}{A \code{smooth.roc} object generated by \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} using \code{method = "fitdistr"}.}

\item{type}{Character string specifying the criterion used to define the diagnostic cutoff to return estimates for. If \code{"best"}, estimates for the cutoff that maximizes the Youden index are calculated and returned. If \code{"specificity"}, estimates for the cutoff that achieves a target specificity value specified by \code{target.value} are calculated and returned. If \code{"sensitivity"}, estimates for the cutoff that achieves a target sensitivity value specified by \code{target.value} are calculated and returned.}

\item{target.value}{Numeric value ranging between 0 and 1 that specifies the target sensitivity or specificity value defining the cutoff to calculate estimates for when \code{type} is not \code{"best"}.}

\item{method}{Character string specifying the methodology used to generate estimates. If \code{"continuous"}, values are estimated via continuous optimization of the smoothed ROC curve using the fitted case and control population probability density functions. If \code{"grid"}, cutoff values are selected via optimization over the grid-discretized operating points of the smoothed ROC curve, matching the internal behavior of the native \ifelse{html}{\code{\link[pROC:coords]{coords()}}}{\code{coords()}}  function of the ‘pROC’ package. \code{"continuous"} provides finer resolution and potentially more accurate estimates; however, sensitivity and specificity values will not perfectly match those returned by the \ifelse{html}{\code{\link[pROC:coords]{coords()}}}{\code{coords()}}  function. \code{"continuous"} is default.}

\item{quiet}{Specifies whether to silence messages generated during estimate calculation. Default value is \code{FALSE}.}
}
\value{
A named numeric vector containing the estimated diagnostic performance and cutoff values:

\item{\code{threshold}}{ The estimated diagnostic cutoff value.}
\item{\code{specificity}}{The estimated specificity at the cutoff value.}
\item{\code{sensitivity}}{The estimated sensitivity at the cutoff value.}
}
\description{
Calculates population-level sensitivity, specificity, and diagnostic cutoff estimates from smoothed ROC curves generated using the \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} function of the ‘pROC’ package via the \verb{“fitdist”} method. A \code{smooth.roc} object is provided as input, and metrics can be calculated for the estimated diagnostic cutoff that maximizes the Youden index, or for the estimated diagnostic cutoff that achieves a user specified sensitivity or specificity value.
}
\examples{
# 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)

# 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
)

# calculate sensitivity, specificity, and cutoff
# estimates for the max Youden cutoff

sm.coords(smooth_roc, type = "best")

# calculate sensitivity, specificity, and cutoff estimates
# for the cutoff that yields 90\% sensitivity

sm.coords(
  smooth_roc,
  type = "sensitivity",
  target.value = 0.9
)

# calculate sensitivity, specificity, and cutoff estimates
# for the cutoff that yields 75\% specificity

sm.coords(
  smooth_roc,
  type = "specificity",
  target.value = 0.75
)

}
\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[pROC:coords]{coords()}}}{\code{pROC::coords()}} \cr
\link{rocTools-package} \cr
\code{\link[=find.distr]{find.distr()}} \cr
\code{\link{blood_data}}
}
