\name{cerardat_estim_nf}
\alias{cerardat_estim_nf}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
Number of axes to keep
}
\description{
Estimate the correct number of axes to keep in the regression model (see \link[SPARTAAS]{cerardat}). We use a resampling procedure see \link[caret]{train}.
}
\usage{
cerardat_estim_nf(df, row.sup, date, option=list(method = "LOOCV"))
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{df}{
The data (data.frame) is a contingency table with the observations in rows and the technical groups in columns.
}
  \item{row.sup}{
Index of supplementary rows in df (vector).
}
  \item{date}{
The dates of each observation or NA (vector).
}
  \item{option}{
A list of values that define how the resampling method acts. See detail.
}
}

\details{
We implement a resampling procedure (see \link[caret]{train}) and calculate several metrics in order to determine the number of axes to retain (nf).

The metrics are: PRESS (always use LOOCV for calculations), RMSE, MAE, and adjusted R².
In addition, hypothesis tests for normality (\link[stats]{shapiro.test}), heteroscedasticity (\link[lmtest]{bptest}) and autocorrelation (\link[lmtest]{dwtest}) are carried out for each value of nf.

You can give a list of options, there are 3 diffrents way of resampling implemented :

Leave-One-Out: `option=list(method="LOOCV")` (Default)

K-fold cross-validation: `option=list(method="cv", number=5)`

repeated K-fold cross-validation: `option=list(method="repeatedcv", number=5, repeats=10)`

Warning: For the CV and repeated CV methods, ensure you have sufficient data per fold. These approaches are particularly useful when the computation time for LOOCV becomes too long (For small datasets, they may generate warnings).

Note: when using the LOOCV method, the values for the Root Mean Square Error (RMSE) are essentially the same as those for PRESS, with the difference that RMSE is the mean rather than the sum.
}

\value{
\item{nf }{Number of axes to keep (default minimal PRESS value)}
\item{PRESS }{plot of the Predicted Residual Error Sum of Squares.}
\item{RMSE }{plot of the Root Mean Squared Error.}
\item{MAE }{plot of the Mean Absolute Error.}
\item{adj.R_sq }{plot of the Coefficient of determination R².}
\item{Pvalue }{plot of p-values from statistical tests on the hypotheses.}
\item{data }{data frame of MSE, PRESS and R_sq values.}
\item{data_stat }{data frame of the p-values.}

}

\references{
Bellanger L. and Husi P. (2012) Statistical tool for dating and interpreting archaeological contexts using pottery. Journal of Archaeological Science, Elsevier, 39 (4), pp.777-790. doi:10.1016/j.jas.2011.06.031.
}
\author{
A. COULON

L. BELLANGER

P. HUSI
}


\examples{
\donttest{
data(datacerardat)
res = cerardat_estim_nf(datacerardat$df, datacerardat$row.sup, datacerardat$date)

#Number of axes to keep (minimal PRESS value)
res$nf

#the plots
res$PRESS
res$MAE
res$adj.R_sq

#p-value
res$Pvalue
}
}

