C:/programs/etirm/src/ICRF_GPCM.cpp

Go to the documentation of this file.

/*! \file ICRF_GPCM.cpp
 
  \brief
  Class for computing item category response function (ICRF) 
  and its derivative for the generalized partial credit model.

  Estimation Toolkit for Item Response Models (ETIRM)
  http://www.smallwaters.com/software/cpp/etirm.html

  Author(s): 
  Werner Wothke, maintenance (http://www.smallwaters.com)
  Brad Hanson (http://www.b-a-h.com/)
  See the file LICENSE for information on usage and redistribution.

  Copyright (C) 2008, Werner Wothke
  Copyright (c) 2000-2002, Bradley A. Hanson
 */

#ifdef ETIRM_NO_DIR_PREFIX
#include "ICRF_GPCM.h"
#else
#include "etirm/ICRF_GPCM.h"
#endif

#include <cmath> // for exp
#if defined(ETIRM_USE_BOOST_CONFIG) || defined(BOOST_NO_LIMITS)
// If no <limits> header use Boost (http://www.boost.org)
// workaround. This assumes the Boost library is available.
#include <boost/detail/limits.hpp>
#else
#include <limits>
#endif

#ifdef BOOST_NO_STDC_NAMESPACE
// for compilers which do not put C library functions in std namespace
namespace std
{ using ::exp;}
#endif

namespace etirm
{

  /* \brief
   ICRF_GPCM, compute probability of a response in response category
   'r' for latent variable value theta.
   
   \param r   Response category, where a response in the first
   response category is mFirstResponse, the response
   in the second response category is mFirstResponse+1,
   etc.
   \param param Vector containing item parameters.
   \param theta Latent variable value for which probability is calculated.
   
   */
  Real ICRF_GPCM::ICRF(Response r, const RealVector &param, Real theta) const
  {

    Real z = 0.0;
    Real num = (r == mFirstResponse) ? 1.0 : -1.0;
    Real sum = 1.0;
    Real a = param[0];
    Response ir = mFirstResponse+1;
    RealVector::const_iterator ip = param.begin()+1;
    for (int i = mNumCat-1; i--; ++ir, ++ip)
    {
      z += a * (theta - *ip);
      Real ez = std::exp(z);
      if (ir == r)
        num = ez;

      sum += ez;
    }

    return num/sum;

  }

  /*! \brief
   OpenICC, compute probability of a correct response for latent
   variable value theta, where probability must be in the
   open interval (0, 1). This function can be used when the 
   logarithm of the probability or logit of the probability
   needs to be taken.
   
   */
  Real ICRF_GPCM::OpenICRF(Response r, const RealVector &param, Real theta) const
  {

    double prob = ICRF(r, param, theta);

    /* Make sure probability is between 0 and 1 */
    if (prob <= 0.0)
    {
      prob = std::numeric_limits<Real>::min();
    }
    else if (prob >= 1.0)
    {
      prob = 1.0 - std::numeric_limits<Real>::epsilon();
    }

    return prob;
  }

  /*!
   ExpZ, compute the terms exp(sum_{k=1}^i z_k), i = 1, mNumCat-1, where
   z_k = a * (theta - b_k), a = param[0], b_k = param[k].
   These terms are stored in the data member mExpz.
   Also store values in data members mDenom and mDenom2.
   */
  void ICRF_GPCM::ExpZ(const RealVector &param, Real theta)
  {
    Real a = param[0];

    mExpz[0] = 1.0;
    mDenom = 1.0;
    RealVector::iterator ie = mExpz.begin()+1;
    RealVector::const_iterator ip = param.begin() + 1;
    Real num = 0.0;
    for (int i = mNumCat-1; i--; ++ip, ++ie)
    {
      num += a * (theta - *ip);
      *ie = std::exp(num);
      mDenom += *ie;
    }

    mDenom2 = mDenom * mDenom;
  }

  /*! 
   \brief
   ICRFDeriv1, compute first derivatives of ICRF with respect to all parameters.
   
   Returns derivative with respect to item parameters in
   vector deriv.
   
   The derivative is obtained by computing the derivative of the numerator and
   denominator of the ICRF probability separately, and using the formula
   for the derivative of a quotient of functions.
   
   */
  void ICRF_GPCM::ICRFDeriv1(Response r, const RealVector &param, Real theta, RealVector &deriv)
  {
    ExpZ(param, theta);

    Real probnum = mExpz[r - mFirstResponse]; // numerator of ICRF for this response
    Real a = param[0];

    /* Derivative with respect to a */
    Real du = 0.0;
    Real nderiv = 0.0; // derivative of numerator of ICRF
    Real dderiv = 0.0; // derivative of denominator of ICRF
    RealVector::const_iterator ip = param.begin()+1;
    RealVector::const_iterator ie = mExpz.begin()+1;
    Response ir = mFirstResponse + 1;
    int i;
    for (i = mNumCat-1; i--; ++ip, ++ie, ++ir)
    {
      du += theta - *ip;
      dderiv += du * *ie;
      if (ir == r)
        nderiv = du * *ie;
    }
    deriv[0] = nderiv * mDenom;
    deriv[0] -= probnum * dderiv;
    deriv[0] /= mDenom2;

    /* Derivatives with respect to b's. Compute derivative of parameter associated with
     the last response category first and work backward. */
    ie = mExpz.begin()+mNumCat-1;
    RealVector::iterator id = deriv.begin() + mNumCat-1;
    dderiv = 0.0;
    nderiv = -a * probnum;
    ir = mFirstResponse + mNumCat - 1;
    for (i = mNumCat-1; i--; --ir, --ie, --id)
    {
      dderiv += -a * *ie;

      if (ir <= r)
        *id = nderiv * mDenom;
      else
        *id = 0.0;
      *id -= probnum * dderiv;
      *id /= mDenom2;
    }

  }

  /*!
   \brief Scale, transform item parameters to new IRT scale
   */
  void ICRF_GPCM::Scale(Real slope, Real intercept, RealVector &param)
  {

    /* Transform the slope parameter */
    param[0] /= slope;

    /* Transform intercept parameters */
    RealVector::iterator ip = param.begin() + 1;
    for (int i = mNumParameters-1; i--; ++ip)
    {
      *ip *= slope;
      *ip += intercept;
    }
  }

  //! \brief GetAllParameters, copy parameters from estParam to allParam.
  void ICRF_GPCM::GetAllParameters(const RealVector &estParam, RealVector &allParam) const
  {
    if (estParam.size() != mNumParameters || allParam.size() != mNumParameters)
    {
      throw InvalidArgument("Invalid number of parameters", "ICRF_GPCM::GetAllParameters");
    }

    RealVector::iterator ia = allParam.begin();
    RealVector::const_iterator ie = estParam.begin();
    for (int i = mNumParameters; i--; ++ia, ++ie)
    {
      *ia = *ie;
    }
  }

} // namespace etirm

---