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

Go to the documentation of this file.

/*! \file ICCLogistic.cpp

  \brief 
  ICCLogistic class for computing item characteristic curve (ICC) of 1, 
  2, and 3-parameter logistic models, as well as first and second derivatives of 
  ICC.

  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 "ICCLogistic.h" 
#else 
#include 
"etirm/ICCLogistic.h"
#endif

#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

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

namespace etirm
{

  /*
    \brief
    Returns the probability of a correct response for the 3PL item with parameters 
    a, b, c, and ability value theta.
    
    \section function_args Function Parameters
 
    \param[in]  a Item slope parameter.
    \param[in]  b Item location parameter.
    \param[in]  c Item pseudo-guessing parameter.
    \param[in]  theta Examinee ability parameter.
   */
  Real ICC3PLFunc::ICC3PL(Real a, Real b, Real c, Real theta) const
  {

    Real prob = std::exp(-mD * a * (theta - b));
    prob += 1.0;
    prob = (1.0-c) / prob;
    prob += c;

    return prob;
  }

  /*
    \brief
    Returns the probability in the open interval (0, 1) of a correct response for 
    the 3PL item with parameters a, b, c, and ability value theta.
    
    This function can be used when the logarithm of the probability or logit of 
    the probability needs to be taken.

    \section function_args Function Parameters
 
    \param[in]  a Item slope parameter.
    \param[in]  b Item location parameter.
    \param[in]  c Item pseudo-guessing parameter.
    \param[in]  theta Examinee ability parameter.
   */
  Real ICC3PLFunc::OpenICC3PL(Real a, Real b, Real c, Real theta) const
  {
    double prob = ICC3PL(a, b, c, 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;
  }

  /*
    \brief
    Computes (gradient) vector of first partial derivatives of the 3PL model with respect to item parameters.
    
    Returns results in deriv vector.

    \section function_args Function Parameters

    \param[in]  numParam Number of parameters (1, 2, or 3) of Logistic IRT model.   
    \param[in]  a Item slope parameter.
    \param[in]  b Item location parameter.
    \param[in]  c Item pseudo-guessing parameter.
    \param[in]  theta Examinee ability parameter.
    \param[out] &deriv  Address of gradient vector of length numParam. 
   */
  void ICC3PLFunc::ICC3PLDeriv1(int numParam, Real a, Real b, Real c, Real theta, RealVector &deriv) const
  {
    Real t = std::exp(-a*mD * (theta - b));
    Real onept2 = 1.0 + t;
    onept2 *= onept2;

    // derivative with respect to the b parameter   
    Real derivb = -a * (1.0 -c) * mD * t;
    derivb /= onept2;

    if (numParam == 1)
    {
      deriv(1) = derivb;
      return;
    }

    deriv(2) = derivb;

    // derivative with respect to the a parameter   
    deriv(1) = (1.0 - c) * (theta - b) * mD * t;
    deriv(1) /= onept2;

    // derivative with respect to the c parameter   
    if (numParam == 3)
    {
      deriv(3) = - 1.0 / (1.0 + t);
      deriv(3) += 1.0;
    }
  }

  /*!
    \brief
    Computes (hessian) matrix of second partial derivatives of the 3PL model with respect to item parameters.
    
    Returns results in deriv matrix.

    \section function_args Function Parameters

    \param[in]  numParam Number of parameters (1, 2, or 3) of Logistic IRT model.   
    \param[in]  a Item slope parameter.
    \param[in]  b Item location parameter.
    \param[in]  c Item pseudo-guessing parameter.
    \param[in]  theta Examinee ability parameter.
    \param[out] &deriv  Address of hessian matrix of dimension numParam. Only the lower half and diagonal 
        of the matrix are populated, the upper off-diagonal entries remain undefined.
   */
  void ICC3PLFunc::ICC3PLDeriv2(int numParam, Real a, Real b, Real c, Real theta, RealMatrix &deriv) const
  {

    Real e = std::exp(a*mD * (theta - b));
    Real onepe3 = 1.0 + e;
    Real onepe2 = onepe3 * onepe3;
    onepe3 *= onepe2;
    Real d2 = mD * mD;
    Real cm1 = c - 1.0;
    Real em1 = e - 1.0;

    // second derivative with respect to the b parameter  
    Real derivt = a * a;
    derivt *= cm1 * d2;
    derivt *= e * em1;
    derivt /= onepe3;

    if (numParam == 1)
    {
      deriv(1, 1) = derivt;
      return;
    }

    deriv(2, 2) = derivt;

    Real bmt = b - theta;

    // second derivative with respect to the a parameter  
    derivt = cm1 * d2;
    derivt *= e * em1;
    derivt *= bmt * bmt;
    deriv(1, 1) = derivt / onepe3;

    // second derivative with respect to a and b 
    Real t2 = 1 + e;
    t2 += a * mD * em1 * bmt;
    derivt = t2 * cm1;
    derivt *= mD * e;
    deriv(2, 1) = derivt / onepe3;

    if (numParam == 3)
    { // second derivative with respect to the c parameter 
      deriv(3, 3) = 0.0;

      Real einv = 1.0 / e;
      Real onepeinv2 = 1.0 + einv;
      onepeinv2 *= onepeinv2;

      // second derivative with respect to a and c    
      derivt = mD * einv;
      derivt *= bmt;
      deriv(3, 1) = derivt / onepeinv2;

      // second derivative with respect to b and c    
      derivt = a * mD * einv;
      deriv(3, 2) = derivt / onepeinv2;
    }
  }

  /*! Constructor for three-parameter logistic ICC object */
  ICCLogistic<3>::ICCLogistic(Real D) :
    ICC3PLFunc(3, D)
  {
  }

  /*! Constructor for two-parameter logistic ICC object */
  ICCLogistic<2>::ICCLogistic(Real D, Real c) :
    ICC3PLFunc(2, D)
  {
    if (c < 0.0 || c> 1.0)throw InvalidArgument("Invalid c parameter",
        "ICCLogistic<2>::ICCLogistic");
    fixedC = c;
  }

  /*! Constructor for one-parameter logistic ICC object */
  ICCLogistic<1>::ICCLogistic(Real D, Real a, Real c) :
  ICC3PLFunc(1, D)
  {
    if (c < 0.0 || c> 1.0)throw InvalidArgument("Invalid c parameter",
        "ICCLogistic<1>::ICCLogistic");

    fixedC = c; fixedA = a;}

  //! Method to return allParam for 3PL item 
  void ICCLogistic<3>::GetAllParameters(const RealVector &estParam,
      RealVector &allParam) const
  {
    allParam = estParam;
  }

  /*! Method to return allParam for 2PL item (estParam contains estimated 
   parameters a and b, allParam is assigned to contain a, b, c). */
  void ICCLogistic<2>::GetAllParameters(const RealVector &estParam,
      RealVector &allParam) const
  {
    if (estParam.size() != 2 || allParam.size() != 3)
    {
      throw
      InvalidArgument("Invalid number of parameters",
          "ICCLogistic<2>::GetAllParameters");
    }
    allParam[0] = estParam[0];
    allParam[1] = estParam[1];
    allParam[2] = fixedC;
  }

  /*! Method to return allParam for 1PL item (estparam contains estimated 
   parameter b, allParam is assigned to contain a, b, c). */
  void ICCLogistic<1>::GetAllParameters(const RealVector &estParam, RealVector
      &allParam) const
  {
    if (estParam.size() != 1 || allParam.size() != 3)
    {
      throw
      InvalidArgument("Invalid number of parameters",
          "ICCLogistic<1>::GetAllParameters");
    }
    allParam[0] = fixedA;
    allParam[1] = estParam[0];
    allParam[2] = fixedC;
  }

} // namespace etirm

---