% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/forder.r
\name{forder}
\alias{forder}
\title{Functional ordering}
\usage{
forder(
  curve_sets,
  measure = "erl",
  scaling = "qdir",
  alternative = c("two.sided", "less", "greater"),
  use_theo = TRUE,
  probs = c(0.025, 0.975),
  quantile.type = 7
)
}
\arguments{
\item{curve_sets}{A \code{curve_set} object or a list of \code{curve_set} objects.}

\item{measure}{The measure to use to order the functions from the most extreme to the least extreme
one. Must be one of the following: 'rank', 'erl', 'cont', 'area', 'max', 'int', 'int2'. Default is 'erl'.}

\item{scaling}{The name of the scaling to use if measure is 'max', 'int' or 'int2'.
Options include 'none', 'q', 'qdir' and 'st', where 'qdir' is the default.}

\item{alternative}{A character string specifying the alternative hypothesis.
Must be one of the following: "two.sided" (default), "less" or "greater".
The last two options only available for types \code{'rank'}, \code{'erl'},
\code{'cont'} and \code{'area'}.}

\item{use_theo}{Logical. When calculating the measures 'max', 'int', 'int2',
should the theoretical function from \code{curve_set} be used (if 'theo' provided),
see \code{\link{deviation_test}}.}

\item{probs}{A two-element vector containing the lower and upper
quantiles for the measure 'q' or 'qdir', in that order and on the interval [0, 1].
The default values are 0.025 and 0.975, suggested by Myllymäki et al. (2015, 2017).}

\item{quantile.type}{As type argument of \code{\link[stats]{quantile}}, how to
calculate quantiles for 'q' or 'qdir'.}
}
\value{
A vector containing one of the above mentioned measures k for each of the functions
in the curve set. If the component \code{obs} in the curve set is a vector, then its measure
will be the first component (named 'obs') in the returned vector.
}
\description{
Calculates different measures for ordering the functions (or vectors)
from the most extreme to least extreme one
}
\details{
Given a \code{curve_set} (see \code{\link{create_curve_set}} for how to create such an object)
or an \code{envelope} object of \pkg{spatstat},
which contains curves \eqn{T_1(r),\dots,T_s(r)}{T_1(r),...,T_s(r)},
the functions are ordered from the most extreme one to the least extreme one
by one of the following measures (specified by the argument \code{measure}).
Note that \code{'erl'}, \code{'cont'} and \code{'area'} were proposed as a refinement to
the extreme ranks \code{'rank'}, because the extreme ranks can contain many ties.
All of these completely non-parametric measures are smallest for the most extreme functions
and largest for the least extreme ones,
whereas the deviation measures (\code{'max'}, \code{'int'} and \code{'int2'}) obtain largest values
for the most extreme functions.
\itemize{
 \item \code{'rank'}: extreme rank (Myllymäki et al., 2017).
The extreme rank \eqn{R_i}{R_i} is defined as the minimum of pointwise ranks of the curve
\eqn{T_i(r)}{T_i(r)}, where the pointwise rank is the rank of the value of the curve for a
specific r-value among the corresponding values of the s other curves such that the lowest
ranks correspond to the most extreme values of the curves. How the pointwise ranks are determined
exactly depends on the whether a one-sided (\code{alternative} is "less" or "greater") or the
two-sided test (\code{alternative="two.sided"}) is chosen.
 \item \code{'erl'}: extreme rank length (Myllymäki et al., 2017).
 Considering the vector of pointwise ordered ranks \eqn{\mathbf{R}_i}{RP_i} of the ith curve,
 the extreme rank length measure \eqn{R_i^{erl}}{Rerl_i} is equal to
\deqn{R_i^{erl} = \frac{1}{s}\sum_{j=1}^{s} \mathbf{1}(\mathbf{R}_j "<" \mathbf{R}_i)}{Rerl_i = \sum_{j=1}^{s} 1(RP_j "<" RP_i) / s}
where \eqn{\mathbf{R}_j "<" \mathbf{R}_i}{RP_j "<" RP_i} if and only if
there exists \eqn{n\leq d}{n<=d} such that for the first k, \eqn{k<n}{k<n}, pointwise ordered
ranks of \eqn{\mathbf{R}_j}{RP_j} and \eqn{\mathbf{R}_i}{RP_i} are equal and the n'th rank of
\eqn{\mathbf{R}_j}{RP_j} is smaller than that of \eqn{\mathbf{R}_i}{RP_i}.
The scaling by \deqn{s}{s} is applied to normalize the ranks following Mrkvička et al. (2019)
and Narisetty and Nair (2016).

 \item \code{'cont'}: continuous rank (Hahn, 2015; Mrkvička et al., 2019)
based on minimum of continuous pointwise ranks
 \item \code{'area'}: area rank (Mrkvička et al., 2019) based on area between continuous
 pointwise ranks and minimum pointwise ranks for those argument (r) values for which pointwise
 ranks achieve the minimum (it is a combination of erl and cont)
 \item \code{'max'} and \code{'int'} and \code{'int2'}:
Further options for the \code{measure} argument that can be used together with \code{scaling}.
See the help in \code{\link{deviation_test}} for these options of \code{measure} and \code{scaling}.
These measures are largest for the most extreme functions and smallest for the least extreme ones.
The arguments \code{use_theo} and \code{probs} are relevant for these measures only (otherwise ignored).
}
For details see Myllymäki and Mrkvička et al. (2020, Section 2)
}
\examples{
if(requireNamespace("fda", quietly = TRUE)) {
  # Consider ordering of the girls in the Berkeley Growth Study data
  # available from the R package fda, see ?growth, according to their
  # annual heights or/and changes within years.
  # First create sets of curves (vectors), for raw heights and
  # for the differences within the years
  years <- paste(1:18)
  curves <- fda::growth[['hgtf']][years,]
  cset1 <- create_curve_set(list(r = as.numeric(years),
                                 obs = curves))
  cset2 <- create_curve_set(list(r = as.numeric(years[-1]),
                                 obs = curves[-1,] - curves[-nrow(curves),]))

  # Order the girls from most extreme one to the least extreme one, below using the 'area' measure
  # a) according to their heights
  forder(cset1, measure = 'area')
  # Print the 10 most extreme girl indices
  order(forder(cset1, measure = 'area'))[1:10]
  # b) according to the changes (print indices)
  order(forder(cset2, measure = 'area'))[1:10]
  # c) simultaneously with respect to heights and changes (print indices)
  csets <- list(Height = cset1, Change = cset2)
  order(forder(csets, measure = 'area'))[1:10]
}
}
\references{
Hahn U (2015). “A note on simultaneous Monte Carlo tests.” Technical report, Centre for Stochastic Geometry and advanced Bioimaging, Aarhus University.

Mrkvička, T., Myllymäki, M., Jilek, M. and Hahn, U. (2020) A one-way ANOVA test for functional data with graphical interpretation. Kybernetika 56(3), 432-458. doi: 10.14736/kyb-2020-3-0432

Mrkvička, T., Myllymäki, M., Kuronen, M. and Narisetty, N. N. (2022) New methods for multiple testing in permutation inference for the general linear model. Statistics in Medicine 41(2), 276-297. doi: 10.1002/sim.9236

Myllymäki, M., Grabarnik, P., Seijo, H. and Stoyan. D. (2015). Deviation test construction and power comparison for marked spatial point patterns. Spatial Statistics 11, 19-34. doi: 10.1016/j.spasta.2014.11.004

Myllymäki, M., Mrkvička, T., Grabarnik, P., Seijo, H. and Hahn, U. (2017). Global envelope tests for spatial point patterns. Journal of the Royal Statistical Society: Series B (Statistical Methodology) 79, 381-404. doi: 10.1111/rssb.12172

Narisetty, N. N. and Nair, V. J. (2016) Extremal depth for functional data and applications. Journal of the American Statistical Association 111, 1705-1714.
}
\seealso{
\code{\link{partial_forder}}
}
