#' Tools for Distribution-Based ROC Smoothing Using ‘pROC’
#'
#' Receiver operating characteristic (ROC) analysis is widely used in studies of diagnostic performance to generate key metrics such as sensitivity and specificity estimates, as well as establish candidate diagnostic cutoffs. However, population sample measures have a finite number of possible diagnostic cutoffs, which can result in raw ROC curves that appear jagged or stepped. This stepping phenomenon can inflate diagnostic performance estimates and reduce the accuracy of diagnostic cutoff estimates, particularly in small to modestly sized samples (Linnet and Brandt, 1986). One strategy to reduce this bias and increase generalizability is to carry out ROC smoothing using population probability density function estimation. While this solution is robust when properly implemented, smoothing using poorly fit distributions can unintentionally increase bias (Leeflang et al., 2008). To that end, the ‘rocTools’ package provides a set of functions that extend the functionality of the ‘pROC’ package for carrying out population probability density function estimation-based ROC smoothing and associated analyses. These functions enable automated selection of the case and control distribution families to be fit for smoothing, as well as generation of population-level diagnostic performance and diagnostic cutoff estimates from the resultant smoothed curves.
#'
#' The ‘rocTools’ package contains three user facing functions that can be used in combination with the core functions of the ‘pROC’ package to build and analyze smoothed ROC curves via population probability density function estimation methods.
#'
#' The [find.distr()] function performs automated selection of the distribution families to be fit when generating smoothed ROC curves using the ` “fitdistr” ` method of the \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} function of the ‘pROC’ package. It takes a raw `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 distribution families to both the case and control data, and then uses Akaike information criterion (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 \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} to be used for ROC smoothing.
#'
#' The [get.fits()] function retrieves and returns the final case and control distribution fits from `smooth.roc` objects generated using the ` “fitdistr” ` method of the \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} function.  It can be used downstream of [find.distr()] and \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} to evaluate the final distribution fits used for ROC smoothing.  The returned values include the distribution types, the distribution parameters, and the associated AIC values. The extracted values can either be printed in console as a human readable summary or stored as a new object.
#'
#' The [sm.coords()] function calculates population-level sensitivity, specificity, and diagnostic cutoff estimates from smoothed ROC curves generated using the ` “fitdist” ` method of the \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} function. A `smooth.roc` object is provided as input, and these 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.  This function works analogously to the \ifelse{html}{\code{\link[pROC:coords]{coords()}}}{\code{coords()}} function of the ‘pROC’ package, but produces more precise sensitivity and specificity estimates for smoothed curves through continuous optimization as opposed to grid-based optimization, and has the added functionality of producing diagnostic cutoff estimates.
#'
#' From an implementation perspective, this collection of functions can be called in the following order to create a seamless workflow to generate population-level diagnostic performance and cutoff estimates from case-control population sample measures: \ifelse{html}{\code{\link[pROC:roc]{roc()}}}{\code{roc()}} to build a raw ROC curve for the population sample data, [find.distr()] to select the best case and control distribution families to fit for roc smoothing, \ifelse{html}{\code{\link[pROC:smooth]{smooth()}}}{\code{smooth()}} to build a smooth ROC curve approximating population-level diagnostic performance using said distribution families, and [sm.coords()] to calculate population-level sensitivity, specificity, and diagnostic cutoff estimates associated with said smooth curve. [get.fits()] can be used as needed to retrieve the final distribution fits generated as part of this workflow.
#'
#' A real-world dataset containing blood biomarker measures is also included and is used throughout the documentation examples. The \code{\link{blood_data}} dataset contains plasma neurofilament-light chain (NfL) levels measured in 33 neurologically normal controls and 14 patients diagnosed with ischemic stroke as described by O'Connell et al. (2020).
#'
#' @section Main functions:
#'
#' \describe{
#'   \item{[find.distr()]}{Automatically selects distribution families to be used for ROC smoothing.}
#'   \item{[get.fits()]}{Returns distribution fits for smoothed ROC curves.}
#'   \item{[sm.coords()]}{Calculates diagnostic performance and cutoff estimates from smoothed ROC curves.}
#' }
#'
#' @section Datasets:
#' \describe{
#'   \item{\code{\link{blood_data}}}{Example blood biomarker dataset.}
#' }
#'
#' @section Citation:
#' If you use the ‘rocTools’ package in published work, please cite:
#'
#' O'Connell, GC. (2026).
#' \emph{rocTools}.
#' R package version 0.1.3.
#' Available from \url{https://CRAN.R-project.org/package=rocTools}.
#'
#' @references
#' Linnet, K. & Brandt, E. (1986).
#' Assessing diagnostic tests once an optimal cutoff point has been selected.
#' \emph{Clinical Chemistry}, 32, 7.
#' \doi{10.1093/clinchem/32.7.1341}
#'
#' Leeflang, MMG., Moons, KGM., Reitsma, JB., & Zwinderman, AH. (2008).
#' Bias in Sensitivity and Specificity Caused by Data-Driven Selection of Optimal Cutoff Values: Mechanisms, Magnitude, and Solutions.
#' \emph{Clinical Chemistry}, 54, 4.
#' \doi{10.1373/clinchem.2007.096032}
#'
#' Robin, X., Turck, N., Hainard, A., Tiberti, N., Lisacek, F., Sanchez, JC., & Müller, M. (2011).
#' pROC: an open-source package for R and S+ to analyze and compare ROC curves.
#' \emph{BMC Bioinformatics}, 12, 77.
#' \doi{10.1186/1471-2105-12-7}
#'
#' O'Connell, GC., Alder, ML., Smothers, CG., Still, CH., Webel, AR., & Moore, S.M. (2020).
#' Diagnosis of ischemic stroke using circulating levels of brain-specific proteins measured via high-sensitivity digital ELISA.
#' \emph{Brain Research}, 15, 1739.
#' \doi{10.1016/j.brainres.2020.146861}
#'
#' @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
#' [find.distr()] \cr
#' [get.fits()] \cr
#' [sm.coords()] \cr
#' \code{\link{blood_data}}
#'
#' @name rocTools-package

NULL
