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

Go to the documentation of this file.

/*! \file ICRF_PCM.cpp
  
  \brief
  Class for computing item category response function (ICRF) 
  and its derivative for the 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_PCM.h"
#else
#include "etirm/ICRF_PCM.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 
{

/*!
  ICRF_PCM::ICRF

  \brief
  Computes probability of a response in response category
  'r' for latent variable value theta.
  
  \param[in] 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[in] param  Vector containing item parameters.
  \param[in] theta  Latent variable value for which probability is calculated.
  
*/
Real ICRF_PCM::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 = mA;
  Response ir = mFirstResponse+1;
  RealVector::const_iterator ip = param.begin();
  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;

}

/*! OpenICRF
  
  \brief
  Computes 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_PCM::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
  \brief
  Computes the terms exp(sum_{k=1}^i z_k), i = 1, mNumCat-1, where
  z_k = a * (theta - b_k), a = mA, b_k = param[k-1].
  These terms are stored in the data member mExpz.
  Also store values in data members mDenom and mDenom2.
*/
void ICRF_PCM::ExpZ(const RealVector &param, Real theta)
{
  Real a = mA;
  
  
  mExpz[0] = 1.0;
  mDenom = 1.0;
  RealVector::iterator ie = mExpz.begin()+1;
  RealVector::const_iterator ip = param.begin();
  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;
}

/*!
  ICRFDeriv1
  
  \brief
  Computes 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_PCM::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 = mA;
  
  
  /* Derivatives with respect to b's. Compute derivative of parameter associated with
     the last response category first and work backward. */
  RealVector::const_iterator ie = mExpz.begin()+mNumCat-1;
  RealVector::iterator id = deriv.begin() + mNumCat-2;
  Real dderiv = 0.0;
  Real nderiv = -a * probnum;
  Response ir = mFirstResponse + mNumCat - 1;
  for (int 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
  Transforms item parameters to new IRT scale
*/
void ICRF_PCM::Scale(Real slope, Real intercept, RealVector &param)
{

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

/*! GetAllParameters
 * 
  \brief
  Takes estimate parameters (b1, b2, ...) as input, outputs allParam, the vector made up
  of fixed parameter a, and the estimated parameters b1, b2, ...
 */
void ICRF_PCM::GetAllParameters(const RealVector &estParam, RealVector &allParam) const
{
  if (estParam.size() != mNumParameters || allParam.size() != mNumParameters+1)
  {
    throw InvalidArgument("Invalid number of parameters", "ICRF_PCM::GetAllParameters");
  }
  
  allParam[0] = mA;
  RealVector::iterator ia = allParam.begin() + 1;
  RealVector::const_iterator ie = estParam.begin();
  for (int i = mNumParameters; i--; ++ia, ++ie)
  {
    *ia = *ie;
  }
}




} // namespace etirm

---