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

Go to the documentation of this file.

/*! \file ICCLogistic.h
 
 \brief
 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
 */

#ifndef ETIRM_ICCLOGISTIC_H_
#define ETIRM_ICCLOGISTIC_H_

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

#include <string>

namespace etirm
{

  /*! 
   \brief 
   Common functions and data members used for specializations of ICCLogistic. 
   */
  class ICC3PLFunc
  {

protected:

    /*!
      \brief
      Logistic response function class for dichotomous items.
      
      \section function_args Function Parameters
   
      \param[in]  nparam  Number of estimated item parameters (1, 2, or 3).
      \param[in]  D Scale constant defining the metric of the parameter estimates. 
          Typical choices are 1 (for the logistic metric) and 1.7 (for the normal-ogive metric).
     */
    ICC3PLFunc(int nparam, Real D) :
      mD(D), numParameters(nparam)
    {
    }

    /*!
      \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 ICC3PL(Real a, Real b, Real c, Real theta) const;

    /*!
      \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 OpenICC3PL(Real a, Real b, Real c, Real theta) const;

    /*!
      \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 ICC3PLDeriv1(int numParam, Real a, Real b, Real c, Real theta, RealVector &deriv) const;

    /*!
      \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 ICC3PLDeriv2(int numParam, Real a, Real b, Real c, Real theta, RealMatrix &deriv) const;

    /*!
      \brief
      Transforms the parameters of a logistic item to a different latent variable scale.
   
      \section function_args Function Parameters

      \param[in]  slope Slope parameter of linear scale transformation.
      \param[in]  intercept Intercept parameter of linear scale transformation.
      \param[in,out]  a Item slope parameter.
      \param[in,out]  b Item location parameter.
     */
    void Scale(Real slope, Real intercept, Real &a, Real &b)
    {
      a /= slope;
      b *= slope;
      b += intercept;
    }

    //! D constant in ICC, use D=1.0 for logistic metric, D=1.7 for normal-ogive metric.
    Real mD;

    //! Number of parameters in the (logistic) item response model.
    int numParameters; 

  };

  /*!
    \brief
    Class declaration of logistic item response model; specializations supplied for NPAR = 1, 2, 3.
   
    \section template_args Template Parameters
   
    \param NPAR Number of parameter used for instantiation of the dichotomous 
        IRT model. Valid options are 1, 2, or 3.
   */
    template <int NPAR> class ICCLogistic
  {

private:

    /*!
     \brief
     Private constructor prevents any objects of this type from being created with 
     NPAR not equal to one of the values for which a specilization is supplied.
     */
    ICCLogistic()
    {
    }

  };

  /*!
    \brief
    Three-parameter logistic item response model.
   */
  template <> class ICCLogistic<3> : private ICC3PLFunc
  {

public:

    /*!
      \brief 
      Instantiation of logistic item response model, fixing scale constant.
      
      \section function_args Function Parameters
   
      \param[in]  D Scale constant defining the metric of the parameter estimates. 
          Typical choices are 1 (for the logistic metric) and 1.7 (for the 
          normal-ogive metric).
     */ 
    ICCLogistic(Real D); // Corrected typo (was "ICLogistics), ww, 2-23-2008

    /*! 
      \brief
      Returns value of the 3PL item characteristic curve (ICC) for a set of item parameters 
      and theta value.
      
      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries = (a, b, c).
      \param[in]  theta Examinee ability parameter.
     */
    Real ICC(const RealVector &param, Real theta) const
    {
      return ICC3PL(param(1), param(2), ValidC(param(3)), theta);
    }

    /*! 
      \brief
      Returns value of the 3PL item characteristic curve (ICC) in open interval (0, 1); 
      for a set of item parameters and theta value.
      
      This function version 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]  &param Address of item parameter vector with entries = (a, b, c).
      \param[in]  theta Examinee ability parameter.
     */
    Real OpenICC(const RealVector &param, Real theta) const
    {
      return OpenICC3PL(param(1), param(2), ValidC(param(3)), theta);
    }

    /*!
      \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]  &param Address of item parameter vector with entries (a, b, c).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of gradient vector of length 3. 
     */
    void ICCDeriv1(const RealVector &param, Real theta, RealVector &deriv) const
    {
      ICC3PLDeriv1(3, param(1), param(2), ValidC(param(3)), theta, deriv);
    }

    /*!
      \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]  &param Address of item parameter vector with entries (a, b, c).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of 3x3 hessian matrix. Only the lower half and diagonal 
          of the matrix are populated, the upper off-diagonal entries remain undefined.
     */
    void ICCDeriv2(const RealVector &param, Real theta, RealMatrix &deriv) const
    {
      ICC3PLDeriv2(3, param(1), param(2), ValidC(param(3)), theta, deriv);
    }

    /*!
      \brief
      Function to indicate that the algebraic gradient of the item (ICCDeriv1) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool GradientDefined() const
    {
      return true;
    }

    /*!
      \brief
      Function to indicate that the algebraic hessian of the item (ICCDeriv2) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool HessianDefined() const
    {
      return true;
    }

    /*!
      \brief
      Transforms the parameters of a logistic item to a different latent variable scale.
   
      \section function_args Function Parameters

      \param[in]  slope Slope parameter of linear scale transformation.
      \param[in]  intercept Intercept parameter of linear scale transformation.
      \param[in,out]  &param Address of item parameter vector to be transformed. Only the
          first two entries (slope and location) will be transformed.
     */
    void Scale(Real slope, Real intercept, RealVector &param)
    {
      ICC3PLFunc::Scale(slope, intercept, param(1), param(2));
    }

    //! Returns scaling constant D.
    Real GetD() const
    {
      return mD;
    }

    /*!
      \brief
      Copies a, b, and c parameters from estParam into allParam.
      
      \section function_args Function Parameters

      \param[in]  &estParam Address of vector of item parameter estimates.
      \param[out]  &allParam Address of copied item parameter vector.
     */
    void GetAllParameters(const RealVector &estParam, RealVector &allParam) const;

    //! Returns number of estimated parameters.
    int NumParameters() const
    {
      return numParameters;
    }

    //! Returns sum of number of fixed and estimated parameters.
    int NumAllParameters() const
    {
      return numParameters;
    }

    /*!
      \brief
      Returns true if vector param contains valid item parameters.
      
      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector.
     */      
    bool ValidParameters(const RealVector &param) const
    {
      return (param(3) >= 0.0 && param(3) <= 1.0);
    }

    //! Returns name of model.
    std::string Name() const
    {
      return std::string("3PL");
    }
    
    //! Returns model type from enum defined in etirmtypes.h
    IRTModel Model() const
    {
      return ThreePL;
    }

    /*! 
      \brief
      Assigns all item parameters (a, b, and c), fixed and estimated.
      
      \section template_args Template Parameters
   
      \param I  Type of iterator over item parameters. 
    
      \section function_args Function Parameters
   
      \param[in]  begin_param Iterator pointing to first item parameter for the item.
      \param[in]  end_param Iterator point to one after the last parameter for the item.
      \param[out] &estParam Address to vector "all" parameters for this item.
     */
    template <class I> void SetAllParameters(I begin_param, I end_param, RealVector &estParam)
    {
      if ((end_param - begin_param) != 3 || estParam.size() != 3)
        throw InvalidArgument("Wrong number of parameters", "ICCLogistic<3>::SetAllParameters");

      if (begin_param[2] < 0.0 || begin_param[2] > 1.0)
        throw InvalidArgument("Invalid c parameter","ICCLogistic<3>::SetAllParameters");

      RealVector::iterator ie = estParam.begin();
      for (int i = 3; i--; ++ie, ++begin_param)
      {
        *ie = *begin_param;
      }
    }

private:

    /*!
      \brief
      Returns c parameter, if valid, or throws an exception otherwise.
      \section function_args Function Parameters
      
      \param[in]  c Pseudo-guessing parameter c for the item.
    */ 
    Real ValidC(Real c) const
    {
      if (c < 0.0 || c > 1.0)throw RuntimeError("Invalid c parameter","ICCLogistic<3>::ValidC"); 
    
      return c;
    }
  };

  /*!
    \brief
    Two-parameter logistic item response model.
   */
  template <>
  class ICCLogistic<2> : private ICC3PLFunc
  {

  public:

    /*!
      \brief 
      Instantiation of 2-parameter logistic item response model, fixing scale constant D and 
      pseudo-guessing parameter c.
      
      \section function_args Function Parameters
   
      \param[in]  D Scale constant defining the metric of the parameter estimates. 
          Typical choices are 1 (for the logistic metric) and 1.7 (for the 
          normal-ogive metric).
      \param[in]  c Pseudo-guessing parameter for the item.
     */ 
    ICCLogistic(Real D, Real c);

    /*! 
      \brief
      Returns value of item characteristic curve (ICC) of the 2PL model for a 
      set of item parameters and theta value.
      
      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries = (a, b).
      \param[in]  theta Examinee ability parameter.
     */
    Real ICC(const RealVector &param, Real theta) const
    {
      return ICC3PL(param(1), param(2), fixedC, theta);
    }

    /*! 
      \brief
      Returns value of item characteristic curve (ICC) of the 2PL model in the 
      open interval (0, 1), for a set of item parameters and theta value.
      
      This function version 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]  &param Address of item parameter vector with entries = (a, b).
      \param[in]  theta Examinee ability parameter.
     */
    Real OpenICC(const RealVector &param, Real theta) const
    {
      return OpenICC3PL(param(1), param(2), fixedC, theta);
    }

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

      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries (a, b).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of gradient vector of length 2. 
     */
    void ICCDeriv1(const RealVector &param, Real theta, RealVector &deriv) const
    {
      ICC3PLDeriv1(2, param(1), param(2), fixedC, theta, deriv);
    }

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

      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries (a, b).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of 2x2 hessian matrix. Only the lower half and diagonal 
          of the matrix are populated, the upper off-diagonal entries remain undefined.
     */
    void ICCDeriv2(const RealVector &param, Real theta, RealMatrix &deriv) const
    {
      ICC3PLDeriv2(2, param(1), param(2), fixedC, theta, deriv);
    }

    /*!
      \brief
      Function to indicate that the algebraic gradient of the item (ICCDeriv1) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool GradientDefined() const
    { 
      return true;
    }

    /*!
      \brief
      Function to indicate that the algebraic hessian of the item (ICCDeriv2) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool HessianDefined() const
    { 
      return true;
    }

    /*!
      \brief
      Transforms the parameters of a 2-parameter logistic item to a different latent 
      variable scale.
   
      \section function_args Function Parameters

      \param[in]  slope Slope parameter of linear scale transformation.
      \param[in]  intercept Intercept parameter of linear scale transformation.
      \param[in,out]  &param Address of item parameter vector (slope and intercept) to be 
          transformed.
     */
    void Scale(Real slope, Real intercept, RealVector &param)
    {
      ICC3PLFunc::Scale(slope, intercept, param(1), param(2));
    }

    //! Returns scaling constant D.
    Real GetD() const
    { 
      return mD;
    }

    /*!
      \brief
      Copies a, b, and c parameters from estParam into allParam.
      
      \section function_args Function Parameters

      \param[in]  &estParam Address of vector of item parameter estimates.
      \param[out]  &allParam Address of copied item parameter vector.
     */
    void GetAllParameters(const RealVector &estParam, RealVector &allParam) const;

    //! Returns number of estimated parameters.
    int NumParameters() const
    { 
      return numParameters;
    }

    //! Returns sum of number of fixed and estimated parameters.
    int NumAllParameters() const
    { 
      return numParameters+1;
    }

    /*!
      \brief
      Returns true if vector param contains valid item parameters.
      
      \section function_args Function Parameters

      \param[in]  & Address of item parameter vector (not used with this model).
     */ 
    bool ValidParameters(const RealVector &/* param */) const
    { 
      return true;
    }

    //! Returns name of model.
    std::string Name() const
    { 
      return std::string("2PL");
    }

    //! Returns model type from enum defined in etirmtypes.h
    IRTModel Model() const
    { 
      return TwoPL;
    }

    /*! 
      \brief
      Assigns all item parameters (a, b, and c), fixed and estimated.
      
      \section template_args Template Parameters
   
      \param I  Type of iterator over item parameters. 
    
      \section function_args Function Parameters
   
      \param[in]  begin_param Iterator pointing to first item parameter for the item.
      \param[in]  end_param Iterator point to one after the last parameter for the item.
      \param[out] &estParam Address to vector "all" parameters for this item.
     */
    template <class I>
    void SetAllParameters(I begin_param, I end_param, RealVector &estParam)
    {

      if ((end_param - begin_param) != 3 || estParam.size() != 2)
      throw InvalidArgument("Wrong number of parameters", "ICCLogistic<2>::SetAllParameters");

      if (begin_param[2] < 0.0 || begin_param[2]> 1.0) throw InvalidArgument("Invalid c parameter","ICCLogistic<2>::SetAllParameters");

      RealVector::iterator ie = estParam.begin();
      for (int i = 2; i--; ++ie, ++begin_param)
      {
        *ie = *begin_param;
      }

      fixedC = *begin_param;
    }

  private:
    
    //! fixed c parameter
    Real fixedC;

  };

  /*!
    \brief
    One-parameter logistic item response model.
   */
  template <>
  class ICCLogistic<1> : private ICC3PLFunc
  {

  public:

    /*!
      \brief 
      Instantiation of 1-parameter logistic item response model, fixing scale constant D,
      slope a and pseudo-guessing parameter c.
      
      \section function_args Function Parameters
   
      \param[in]  D Scale constant defining the metric of the parameter estimates. 
          Typical choices are 1 (for the logistic metric) and 1.7 (for the 
          normal-ogive metric).
      \param[in]  a Item slope parameter.
      \param[in]  c Pseudo-guessing parameter for the item.
     */ 
    ICCLogistic(Real D, Real a, Real c);

    /*! 
      \brief
      Returns value of item characteristic curve (ICC) of the 1PL model for a 
      set of item parameters and theta value.
      
      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entry = (b).
      \param[in]  theta Examinee ability parameter.
     */
    Real ICC(const RealVector &param, Real theta) const
    {
      return ICC3PL(fixedA, param(1), fixedC, theta);
    }

    /*! 
      \brief
      Returns value of item characteristic curve (ICC) of the 1PL model in the 
      open interval (0, 1), for a set of item parameters and theta value.
      
      This function version 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]  &param Address of item parameter vector with entries = (b).
      \param[in]  theta Examinee ability parameter.
     */
    Real OpenICC(const RealVector &param, Real theta) const
    {
      return OpenICC3PL(fixedA, param(1), fixedC,theta);
    }

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

      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries (b).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of gradient vector of length 1. 
     */
    void ICCDeriv1(const RealVector &param, Real theta, RealVector &deriv) const
    {
      ICC3PLDeriv1(1, fixedA, param(1), fixedC, theta, deriv);
    }

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

      \section function_args Function Parameters

      \param[in]  &param Address of item parameter vector with entries (b).
      \param[in]  theta Examinee ability parameter.
      \param[out] &deriv  Address of 1x1 hessian matrix. Only the lower half and diagonal 
          of the matrix are populated, the upper off-diagonal entries remain undefined.
     */
    void ICCDeriv2(const RealVector &param, Real theta, RealMatrix &deriv) const
    {
      ICC3PLDeriv2(1, fixedA, param(1), fixedC, theta, deriv);
    }

    /*!
      \brief
      Function to indicate that the algebraic gradient of the item (ICCDeriv1) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool GradientDefined() const
    { 
      return true;
    }

    /*!
      \brief
      Function to indicate that the algebraic hessian of the item (ICCDeriv2) is defined.
      
      This function can be used by UNCMIN++.
     */
    bool HessianDefined() const
    { 
      return true;
    }

    /*!
      \brief
      Transforms the parameters of a 1-parameter logistic item to a different latent 
      variable scale.
   
      \section function_args Function Parameters

      \param[in]  slope Slope parameter of linear scale transformation.
      \param[in]  intercept Intercept parameter of linear scale transformation.
      \param[in,out]  &param Address of item parameter vector (item location only) to be 
          transformed.
     */
    void Scale(Real slope, Real intercept, RealVector &param)
    {
      ICC3PLFunc::Scale(slope, intercept, fixedA, param(1));
    }

    //! Returns scaling constant D.
    Real GetD() const
    { 
      return mD;
    }

    /*!
      \brief
      Copies a, b, and c parameters from estParam into allParam.
      
      \section function_args Function Parameters

      \param[in]  &estParam Address of vector of item parameter estimates.
      \param[out]  &allParam Address of copied item parameter vector.
     */
    void GetAllParameters(const RealVector &estParam, RealVector &allParam) const;

    //! Returns number of estimated parameters.
    int NumParameters() const
    { 
      return numParameters;
    }

    //! Returns sum of number of fixed and estimated parameters.
    int NumAllParameters() const
    { 
      return numParameters+2;
    }

    /*!
      \brief
      Returns true if vector param contains valid item parameters.
      
      \section function_args Function Parameters

      \param[in]  & Address of item parameter vector (not used with this model).
     */ 
    bool ValidParameters(const RealVector & /* param */) const
    { 
      return true;
    }

    //! Returns name of model.
    std::string Name() const
    { 
      return std::string("1PL");
    }

    //! Returns model type from enum defined in etirmtypes.h
    IRTModel Model() const
    { 
      return OnePL;
    }

    /*! 
      \brief
      Assigns all item parameters (a, b, and c), fixed and estimated.
      
      \section template_args Template Parameters
   
      \param I  Type of iterator over item parameters. 
    
      \section function_args Function Parameters
   
      \param[in]  begin_param Iterator pointing to first item parameter for the item.
      \param[in]  end_param Iterator point to one after the last parameter for the item.
      \param[out] &estParam Address to vector "all" parameters for this item.
     */
    template <class I>
    void SetAllParameters(I begin_param, I end_param, RealVector &estParam)
    {

      if ((end_param - begin_param) != 3 || estParam.size() != 1)
      throw InvalidArgument("Wrong number of parameters", "ICCLogistic<1>::SetAllParameters");

      if (begin_param[2] < 0.0 || begin_param[2]> 1.0) throw InvalidArgument("Invalid c parameter","ICCLogistic<1>::SetAllParameters");

      fixedA = *begin_param++;
      estParam[0] = *begin_param++;
      fixedC = *begin_param;
    }

  private:

    Real fixedC; //!< fixed c parameter
    Real fixedA; //!< fixed a parameter

  };

}

#endif // ETIRM_ICCLOGISTIC_H_

---