% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/preparation.R
\name{rankByGroup}
\alias{rankByGroup}
\title{Determine the norm scores of the participants in each subsample}
\usage{
rankByGroup(
  data = NULL,
  group = "group",
  raw = "raw",
  weights = NULL,
  method = 4,
  scale = "T",
  descend = FALSE,
  descriptives = TRUE,
  na.rm = TRUE,
  silent = FALSE
)
}
\arguments{
\item{data}{data.frame with norm sample data. If no data.frame is provided, the raw score
and group vectors are directly used}

\item{group}{name of the grouping variable (default 'group') or numeric vector, e. g. grade, setting
group to FALSE cancels grouping (data is treated as one group)}

\item{raw}{name of the raw value variable (default 'raw') or numeric vector}

\item{weights}{Vector or variable name in the dataset with weights for each individual case. It can be used
to compensate for moderate imbalances due to insufficient norm data stratification. Weights should be numerical
and positive.  Please use the 'computeWeights' function for this purpose.}

\item{method}{Ranking method in case of bindings, please provide an index,
choosing from the following methods: 1 = Blom (1958), 2 = Tukey (1949),
3 = Van der Warden (1952), 4 = Rankit (default), 5 = Levenbach (1953),
6 = Filliben (1975), 7 = Yu & Huang (2001)}

\item{scale}{type of norm scale, either T (default), IQ, z or percentile (= no
transformation); a double vector with the mean and standard deviation can as well,
be provided f. e. c(10, 3) for Wechsler scale index points}

\item{descend}{ranking order (default descent = FALSE): inverses the
ranking order with higher raw scores getting lower norm scores; relevant
for example when norming error scores, where lower scores mean higher
performance}

\item{descriptives}{If set to TRUE (default), information in n, mean, median and
standard deviation per group is added to each observation}

\item{na.rm}{remove values, where the percentiles could not be estimated,
most likely happens in the context of weighting}

\item{silent}{set to TRUE to suppress messages}
}
\value{
the dataset with the percentiles and norm scales per group
}
\description{
This is the initial step, usually done in all kinds of test norming projects,
after the scale is constructed and the norm sample is established. First,
the data is grouped according to a grouping variable and afterwards, the percentile
for each raw value is retrieved. The percentile can be used for the modeling
procedure, but in case, the samples to not deviate too much from normality,
T, IQ or z scores can be computed via a normal rank procedure based on the
inverse cumulative normal distribution. In case of bindings, we use the medium rank
and there are different methods for estimating the percentiles (default RankIt).
}
\section{Remarks on using covariates}{

So far the inclusion of a binary covariate is experimental and far from optimized.
The according variable name has to be specified in the ranking procedure
and the modeling includes this in the further process. At the moment, during ranking
the data are split into the according cells group x covariate, which leads to small
sample sizes. Please take care to have enough cases in each combination. Additionally,
covariates can lead to unstable modeling solutions. The question, if it is really
reasonable to include covariates when norming a test is a decision beyond the pure data
modeling. Please use with care or alternatively split the dataset into the two groups
beforehand and model them separately.

The functions \code{rankBySlidingWindow}, \code{rankByGroup}, \code{bestModel},
\code{computePowers} and \code{prepareData} are usually not called directly, but accessed
through other functions like \code{cnorm}.
}

\examples{
\dontrun{
# Transformation with default parameters: RankIt and converting to T scores
data.elfe <- rankByGroup(elfe, group = "group") # using a data frame with vector names
data.elfe2 <- rankByGroup(raw=elfe$raw, group=elfe$group) # use vectors for raw score and group

# Transformation into Wechsler scores with Yu & Huang (2001) ranking procedure
data.elfe <- rankByGroup(raw = elfe$raw, group = elfe$group, method = 7, scale = c(10, 3))

# cNORM can as well be used for conventional norming, in case no group is given
d <- rankByGroup(raw = elfe$raw)
d <- computePowers(d)
m <- bestModel(d)
rawTable(0, m) # please use an arbitrary value for age when generating the tables
}

}
\seealso{
rankBySlidingWindow, computePowers, computeWeights, weighted.rank

Other prepare:
\code{\link[=computePowers]{computePowers()}},
\code{\link[=prepareData]{prepareData()}},
\code{\link[=rankBySlidingWindow]{rankBySlidingWindow()}}
}
\concept{prepare}
