% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fine_tuning.R
\name{fine_tuning}
\alias{fine_tuning}
\title{Fine Tune ML Model}
\usage{
fine_tuning(analysis_object, tuner, metrics = NULL, verbose = FALSE)
}
\arguments{
\item{analysis_object}{analysis_object created from build_model function.}

\item{tuner}{Name of the Hyperparameter Tuner. A string of the tuner name:
"Bayesian Optimization" or "Grid Search CV".}

\item{metrics}{Metric used for Model Selection. A string of the name of
metric (see Metrics). By default either "rmse" (regression)
or "roc_auc" (classification).}

\item{verbose}{Logical. If \code{TRUE}, progress details are printed to the
console during the tuning procedure. Defaults to \code{FALSE}.}
}
\value{
An updated analysis_object containing the fitted model with
optimized hyperparameters, the tuning results, and all relevant workflow
modifications. This object includes the final trained model, the best
hyperparameter configuration, tuning diagnostics, and, if applicable, plots
of the tuning process. It can be used for further model evaluation,
prediction, or downstream analysis within the package workflow.
}
\description{
The \strong{fine_tuning()} function performs automated hyperparameter
optimization for ML workflows encapsulated within an AnalysisObject. It
supports two tuning strategies: \strong{Bayesian Optimization} (with
cross-validation) and \strong{Grid Search Cross-Validation}, allowing the user
to specify evaluation metrics and whether to visualize tuning results. The
function first validates arguments and updates the workflow and metric
settings within the AnalysisObject. If hyperparameter tuning is enabled,
it executes the selected tuning procedure, identifies the best
hyperparameter configuration based on the specified metrics, and updates
the workflow accordingly. For neural network models, it also manages the
creation and integration of new model instances and provides additional
visualization of training dynamics. Finally, the function fits the optimized
model to the training data and updates the AnalysisObject, ensuring a
reproducible and efficient model selection process (Bartz et al., 2023).
}
\section{Tuners}{

\subsection{Bayesian Optimization (with cross-validation)}{
\itemize{
\item Number of Folds: 5
\item Initial data points: 20
\item Maximum number of iterations: 25
\item Convergence after 5 iterations without improvement
\item Train / Test : 0.75 / 0.25
}
}

\subsection{Grid Search CV}{
\itemize{
\item Number of Folds: 5
\item Maximum levels per hyperparameter: 10
\item Train / Test : 0.75 / 0.25
}
}
}

\section{Metrics}{

\subsection{Regression Metrics}{
\itemize{
\item rmse
\item mae
\item mpe
\item mape
\item ccc
\item smape
\item rpiq
\item rsq
}
}

\subsection{Classification Metrics}{
\itemize{
\item accuracy
\item bal_accuracy
\item recall
\item sensitivity
\item specificity
\item kap
\item f_meas
\item mcc
\item j_index
\item detection_prevalence
\item roc_auc
\item pr_auc
\item gain_capture
\item brier_class
\item roc_aunp
}
}
}

\examples{
# Fine tuning function applied to a regression task using Random Forest

wrap_object <- preprocessing(
           df = sim_data[1:500 ,],
           formula = psych_well ~ depression + life_sat,
           task = "regression"
           )
wrap_object <- build_model(
               analysis_object = wrap_object,
               model_name = "Random Forest",
               hyperparameters = list(
                     mtry = 2,
                     trees = 3
                     )
                 )
set.seed(123) # For reproducibility
wrap_object <- fine_tuning(wrap_object,
                tuner = "Grid Search CV",
                metrics = c("rmse")
                )
}
\references{
Bartz, E., Bartz-Beielstein, T., Zaefferer, M., & Mersmann, O. (2023).
\emph{Hyperparameter tuner for Machine and Deep Learning with R. A
Practical Guide}. Springer.
\doi{10.1007/978-981-19-5170-1}
}
