% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/grmp.R
\name{rpf.grmp}
\alias{rpf.grmp}
\title{Create monotonic polynomial graded response (GR-MP) model}
\usage{
rpf.grmp(outcomes = 2, q = 0, multidimensional = FALSE)
}
\arguments{
\item{outcomes}{The number of possible response categories. When equal to 2, the model reduces
to the logistic function of a monotonic polynomial (LMP).}

\item{q}{a non-negative integer that controls the order of the
polynomial (2q+1) with a default of q=0 (1st order polynomial = graded response model).}

\item{multidimensional}{whether to use a multidimensional model.
Defaults to \code{FALSE}. The multidimensional version is not yet
available.}
}
\value{
an item model
}
\description{
The GR-MP model replaces the linear predictor of the graded
response model (Samejima, 1969, 1972) with a monotonic polynomial (Falk, conditionally accepted).
}
\details{
Given its relationship to the graded response model, the GR-MP
is constructed in an analogous way:

\deqn{\mathrm P(\mathrm{pick}=0|\lambda,\alpha,\tau,\theta) = 1- \frac{1}{1+\exp(-(\xi_1 + m(\theta;\lambda,\mathbf{\alpha},\mathbf{\tau})))}
}{P(pick=0|a,c,theta) = 1-1/(1+exp(-(xi_1 + m(theta;lambda,alpha,tau)))}
\deqn{\mathrm P(\mathrm{pick}=k|\lambda,\alpha,\tau,\theta) = \frac{1}{1+\exp(-(\xi_k + m(\theta;\lambda,\mathbf{\alpha},\mathbf{\tau})))} - \frac{1}{1+\exp(-(\xi_{k+1} + m(\theta,\lambda,\mathbf{\alpha},\mathbf{\tau}))}
}{P(pick=k|a,c,theta) = 1/(1+exp(-(xi_k + m(theta;lambda,alpha,tau))) - 1/(1+exp(-(xi_(k+1) + m(theta;lambda,alpha,tau))))}
\deqn{\mathrm P(\mathrm{pick}=K|\lambda,\alpha,\tau,\theta) = \frac{1}{1+\exp(-(\xi_K + m(\theta;\lambda,\mathbf{\alpha},\mathbf{\tau}))}
}{P(pick=K|\lambda,\alpha,\tau,theta) = 1/(1+exp(-(xi_K + m(theta;lambda,alpha,tau))))}

The order of the polynomial is always odd and is controlled by
the user specified non-negative integer, q. The model contains
1+(outcomtes-1)+2*q parameters and are used as input to the \code{\link{rpf.prob}}
or \code{\link{rpf.dTheta}} functions in the following order:
\eqn{\lambda}{lambda} - slope of the item model when q=0,
\eqn{\xi}{xi} - a (outcomes-1)-length vector of intercept parameters,
\eqn{\alpha}{alpha} and \eqn{\tau}{tau} - two parameters that control bends in
the polynomial. These latter parameters are repeated in the same order for
models with q>0.  For example, a q=2 polynomial with 3 categories will have an item
parameter vector of: \eqn{\lambda, \xi_1, \xi_2, \alpha_1, \tau_1, \alpha_2, \tau_2}{
lambda, xi1, xi2, alpha1, tau1, alpha2, tau2}.

As with other monotonic polynomial-based item models
(e.g., \code{\link{rpf.lmp}}), the polynomial looks like the
following:

\deqn{m(\theta;\lambda,\alpha,\tau) = b_1\theta + b_2\theta^2 + \dots + b_{2q+1}\theta^{2q+1}
}{m(theta) = b_1*theta + b_2*theta^2 + \dots + b_(2q+1)*theta^{2q+1}}

However, the coefficients, b, are not directly estimated, but are a function of the
item parameters, and the parameterization of the GR-MP is different than
that currently appearing for the logistic function of a monotonic
polynomial (LMP; \code{\link{rpf.lmp}}) and monotonic polynomial generalized partial credit
(GPC-MP; \code{\link{rpf.gpcmp}}) models. In particular, the polynomial is
parameterized such that boundary descrimination functions for the GR-MP will
be all monotonically increasing or decreasing for any given item. This allows
the possibility of items that load either negatively or positively on the latent
trait, as is common with reverse-worded items in non-cognitive tests (e.g., personality).

The derivative \eqn{m'(\theta;\lambda,\alpha,\tau)}{m'(theta;lambda,alpha,tau)} is
parameterized in the following way:

\deqn{ m'(\theta;\lambda,\alpha,\tau) = \left\{\begin{array}{ll}\lambda \prod_{u=1}^q(1-2\alpha_{u}\theta + (\alpha_{u}^2 + \exp(\tau_{u}))\theta^2) &  \mbox{if } q > 0 \\
 \lambda & \mbox{if } q = 0\end{array} \right.}{m'(theta) = m'(theta;lambda,alpha,tau) = lambda \prod_{u=1}^q (1-2*alpha_u*theta + (alpha_u^2 + exp(tau_u))*theta^2) (if q > 0) \\
 lambda (if q = 0)}

Note that the only difference between the GR-MP and these other models
is that \eqn{\lambda}{lambda} is not re-parameterized and may take on
negative values. When \eqn{\lambda}{lambda} is negative, it is analogous
to having a negative loading or a monotonically decreasing function.
}
\examples{
spec <- rpf.grmp(5,2) # 5-category, 3rd order polynomial
theta<-seq(-3,3,.1)
p<-rpf.prob(spec, c(2.77,2,1,0,-1,.89,-8.7,-.74,-8.99),theta)
}
\references{
Falk, C. F. (conditionally accepted). The monotonic polynomial
graded response model: Implementation and a comparative study. \emph{Applied Psychological
Measurement}.

Samejima, F. (1969). Estimation of latent ability using a response pattern of graded scores. \emph{Psychometric Monographs}, 17.

Samejima, F. (1972). A general model of free-response data. \emph{Psychometric Monographs}, 18.
}
\seealso{
Other response model: 
\code{\link{rpf.drm}()},
\code{\link{rpf.gpcmp}()},
\code{\link{rpf.grm}()},
\code{\link{rpf.lmp}()},
\code{\link{rpf.mcm}()},
\code{\link{rpf.nrm}()}
}
\concept{response model}
