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

Go to the documentation of this file.

/*! \file ItemDichotomous.h

  \brief
  Class representing a dichotomously scored item derived from ItemNR.
 
  Defines functions used in M-step of EM algorithm to compute item parameter estimates.

  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_ITEMDICHOTOMOUS_H_
#define ETIRM_ITEMDICHOTOMOUS_H_

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

#include <cmath> // for log
#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

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

namespace etirm
{
  /*! 
    \brief
    Class representing a dichotomously scored item derived from ItemNR.
    
    Defines functions used in M-step of EM algorithm to compute item parameter estimates. 

    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
    \param ICC  Type containing functions defining the item characteristic curve (ICC)
        and derivatives of the ICC.
   */
  template<class D, class ICC> class ItemDichotomous : public ItemNR<D>
  {

public:
    /*!
     \brief
     Class constructor.
     
     \section template_args Template Parameters
   
     \param D  Class for discrete latent variable distribution.
     \param ICC  Type containing functions defining the item characteristic curve (ICC)
         and derivatives of the ICC.

     \section function_args Function Parameters
     
     \param index  Zero-offset index of the item in the vector of all item responses.
     \param icc  Item characteristic curve for the model.
     \param dist Object containing information about the number of latent variable 
         points used in calculating the n and r.
     */
    ItemDichotomous(int index, ICC &icc, D *dist);

    /*! 
      \brief
      Class destructor. 
     */
    virtual ~ItemDichotomous();

    /*!
     \brief
     Returns a vector of estimated and fixed parameters. 
     
     The order of the parameters in the vector is determined by the 
     GetAllParameters member function of mICC.
     */
    virtual RealVector GetAllParameters() const
    {
      RealVector allParam(mICC.NumAllParameters());
      mICC.GetAllParameters(ItemNR<D>::mParameterEstimates, allParam); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
      return allParam;
    }

    /*!
      \brief
      Assigns values of fixed and estimated parameters.
    
      \section function_args Function Parameters
   
      \param[in] &allParam  Address of vector containing all parameters of the item.
     */           
    virtual void SetAllParameters(const RealVector &allParam)
    {
      mICC.SetAllParameters(allParam.begin(), allParam.end(), ItemNR<D>::mParameterEstimates);
    } // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    /*!
      \brief
      Returns probablity of response "r".

      \section function_args Function Parameters
   
      \param[in]  r  Item response.
      \param[in]  &parameters Address of item parameter vector.
      \param[in]  theta Latent ability theta value.
     */
    virtual Real ICRF(Response r, const RealVector &parameters, const Real &theta) const;

    //! TODO: Document NormalizingConstant
    virtual Real NormalizingConstant() const
    {
      return mICC.GetD();
    }

    virtual int ScaleParameters(Real slope, Real intercept, bool ignorePrior = false);

    //! Returns string containing name of model used for item
    virtual std::string ModelName() const
    {
      return mICC.Name();
    }

    //! Returns type of model used for item.
    virtual IRTModel Model() const
    {
      return mICC.Model();
    }

    /*!
      \brief
      Assigns values of both mFirstResponse and mCorrectResponse.
    
      \section function_args Function Parameters
   
      \param[in] r  Code of incorrect item score. (r+1) is assumed to be the correct item score.
     */
    virtual void SetFirstResponse(Response r)
    {
      ItemNR<D>::mFirstResponse = r;
      mCorrectResponse = r+1;
    } // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    /*!
      \brief
      Returns the correct response category.
      
      For dichotomous items, the response to the second response category is 
      considered correct.
     */ 
    virtual Response CorrectResponse()
    {
      return mCorrectResponse;
    }
    
    /*!
      \brief
      Returns the incorrect response category.
      
      For dichotomous items, the response to the first response category 
      is considered incorrect.
     */
    Response IncorrectResponse()
    {
      return mCorrectResponse-1;
    }
    
    /*  The following functions provide an interface to minimization routines (such as UNCMIN)
     that are used in the M-step to estimates parameters for one item. */

    virtual double f_to_minimize(RealVector &p);

    virtual void gradient(RealVector &p, RealVector &g);

    virtual void hessian(RealVector &x, RealMatrix &h);

    virtual int HasAnalyticGradient() const;

    virtual int HasAnalyticHessian() const;

    virtual int ValidParameters(const RealVector &p, bool ignorePriors = false) const;

protected:

    ICC mICC;
    //!< Object for calculating ICC and its derivatives

    /*!
      \brief
      The response associated with the correct answer.
       
      Stored as a data member to avoid overhead of 
      falling CorrectResponse() for member functions.
     */
    Response mCorrectResponse;

  };

  /*!
    \brief
    Class constructor.
      
    The first response category is assumed to correspond to an incorrect
    response and the second response category is assumed to correspond
    to a correct response.
    
    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
    \param ICC  Type containing functions defining the item characteristic curve (ICC)
        and derivatives of the ICC.

    \section function_args Function Parameters

    \param[in] index  Zero-offset index of the item in the vector of all item responses.
    \param[in] icc  Item characteristic curve for the model.
    \param[in] dist Object containing information about the number of latent variable 
        points used in calculating the n and r.
   */
  template<class D, class ICC> ItemDichotomous<D, ICC>::ItemDichotomous(int index, ICC &icc,
      D *dist) :
    ItemNR<D>(icc.NumParameters(), index, 2, dist), mICC(icc),
        mCorrectResponse(ItemNR<D>::mFirstResponse+1) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
  {

  }

  template<class D, class ICC> ItemDichotomous<D, ICC>::~ItemDichotomous()
  {
  }

  template<class D, class ICC> inline Real ItemDichotomous<D, ICC>::ICRF(Response r,
      const RealVector &parameters, const Real &theta) const
  {
    return (r == mCorrectResponse) ? mICC.ICC(parameters, theta) : (1.0 - mICC.ICC(parameters,
        theta));
  }

  /*! 
    \brief
    Function to maximize in M-step. 
   
    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
    \param ICC  Type containing functions defining the item characteristic curve (ICC)
        and derivatives of the ICC.

    \section function_args Function Parameters

    \param[in] &param Address of item parameter vector.
    
    Note: Technically, the negative value of the function is to be minimized by UNCMIN++,
         see inline comments in function code.
   */
  template<class D, class ICC> double ItemDichotomous<D, ICC>::f_to_minimize(RealVector &param)
  {
    Real value = 0.0;
    int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    /* Compute loglikelihood */
    for (int grp=1; grp<=ngroups; ++grp)
    {
      typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::point_iterator it = ItemNR<D>::mLatentDist->begin_points(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      for (int i = ItemNR<D>::mNumLatentVarCat; i--; ++in, ++ir, ++it) // Added "ItemNR<D>::" references. ww, 1/12/2008.
      {
        Real prob = mICC.OpenICC(param, *it);

        Real t = std::log(prob) * *ir;
        t += (*in - *ir) * std::log((1.0 - prob));
        value += t;
      }
    }

    /* Add priors */
    PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
    RealVector::iterator iparam = param.begin();
    for (int j = ItemNR<D>::NumParameters(); j--; ++iprior, ++iparam) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
    {
      if (*iprior)
      {
        if ((*iprior)->ZeroDensity(*iparam))
        {
          // If the prior density is zero then the log of prior density is
          // minus infinity (negative of minus infinity is returned
          // because the function is being minimized)
          if (std::numeric_limits<Real>::has_infinity)
          {
            return std::numeric_limits<Real>::infinity();
          }
          else
          {
            return std::numeric_limits<Real>::max();
          }
        }
        else
        {
          value += (*iprior)->LogDensity(*iparam);
        }
      }
    }

    return -value; // return negative value to find minimum rather than maximum
  }

  /*!
    \brief
    Gradient of function to maximize in M-step. 
    
    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
    \param ICC  Type containing functions defining the item characteristic curve (ICC)
        and derivatives of the ICC.

    \section function_args Function Parameters

    \param[in] &param Address of item parameter vector.
    \param[out] &g  Address of gradient with respect to item parameters. 

    Note: Technically, the negative value of the function is to be minimized by UNCMIN++,
         see inline comments in function code.
   */
  template<class D, class ICC> void ItemDichotomous<D, ICC>::gradient(RealVector &param,
      RealVector &g)
  {
    g = 0.0;
    RealVector deriv(ItemNR<D>::NumParameters()); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
    int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    int i;

    for (int grp=1; grp<=ngroups; ++grp)
    {
      typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::point_iterator itheta = ItemNR<D>::mLatentDist->begin_points(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
      for (i = ItemNR<D>::mNumLatentVarCat; i--; ++in, ++ir, ++itheta) // Added "ItemNR<D>::" references. ww, 1/12/2008.
      {
        Real prob = mICC.OpenICC(param, *itheta);

        Real t = *ir - *in * prob;
        t /= (1.0 - prob) * prob;

        mICC.ICCDeriv1(param, *itheta, deriv);

        // use -t since function is to be minimized, not maximized
        deriv *= -t;
        g += deriv;

      }
    }

    /* Add priors */
    PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" references. ww, 1/12/2008.
    RealVector::iterator iparam = param.begin();
    RealVector::iterator ig = g.begin();
    for (int j = ItemNR<D>::NumParameters(); j--; ++iprior, ++iparam, ++ig) // Added "ItemNR<D>::" references. ww, 1/12/2008.
    {
      // subtract because function is to be minimized
      if (*iprior)
        *ig -= (*iprior)->DerivLogDensity1(*iparam);
    }

  }

  /*!
    \brief
    Hessian of function to maximize in M-step.
    
    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
    \param ICC  Type containing functions defining the item characteristic curve (ICC)
        and derivatives of the ICC.

    \section function_args Function Parameters

    \param[in] &param Address of item parameter vector.
    \param[out] &h  Address of hessian with respect to item parameters. 

    Note: Technically, the negative value of the function is to be minimized by UNCMIN++,
         see inline comments in function code.
    
    Note: The hessian is stored in the lower trangle of h.
   */
  template<class D, class ICC> void ItemDichotomous<D, ICC>::hessian(RealVector &param,
      RealMatrix &h)
  {
    int numParameters = ItemNR<D>::NumParameters(); // Added "ItemNR<D>::" references. ww, 1/12/2008.

    RealMatrix deriv2(numParameters, numParameters);
    RealVector deriv1(numParameters);

    RealMatrix::diag_iterator hdiag, ddiag;
    int i, j, k;
    int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    // Initialize lower triangle of h to zero
    for (i=0; i<numParameters; ++i)
    {
      hdiag = h.begin_diagonal(i+1, 1);
      for (j=numParameters-i; j--; ++hdiag)
      {
        *hdiag = 0.0;
      }
    }

    for (int grp=1; grp<=ngroups; ++grp)
    {
      typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
      typename ItemNR<D>::point_iterator itheta = ItemNR<D>::mLatentDist->begin_points(grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
      for (k = ItemNR<D>::mNumLatentVarCat; k--; ++in, ++ir, ++itheta) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
      {
        Real prob = mICC.OpenICC(param, *itheta);
        Real t1 = -*in * prob * prob;
        t1 += 2.0 * *ir * prob;
        t1 -= *ir;
        Real t2 = *ir - *in * prob;
        Real t = prob * (1.0 - prob);
        t1 /= t * t;
        t2 /= t;

        mICC.ICCDeriv1(param, *itheta, deriv1);
        mICC.ICCDeriv2(param, *itheta, deriv2);

        for (int i=0; i<numParameters; ++i)
        {
          hdiag = h.begin_diagonal(i+1, 1);
          ddiag = deriv2.begin_diagonal(i+1, 1);
          RealVector::iterator prow = deriv1.begin() + i;
          RealVector::iterator pcol = deriv1.begin();
          for (j=numParameters-i; j--; ++prow, ++pcol, ++hdiag, ++ddiag)
          {
            // subtract rather than add since function is to be minimized
            *hdiag -= t1 * *prow * *pcol;
            *hdiag -= t2 * *ddiag;
          }
        }
      }
    }

    /* Add second derivatives of priors to diagonal elements of hessian */
    PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
    RealVector::iterator iparam = param.begin();
    hdiag = h.begin_diagonal(1, 1);
    for (i = numParameters; i--; ++iparam, ++iprior, ++hdiag)
    {
      // subtract because function is to be minimized
      if (*iprior)
        *hdiag -= (*iprior)->DerivLogDensity2(*iparam);
    }

  }

  //! Indicates that the analytic gradient is available.
  template<class D, class ICC> int ItemDichotomous<D, ICC>::HasAnalyticGradient() const
  {
    return mICC.GradientDefined();
  }

  //! Indicates that the analytic hessian is available.
  template<class D, class ICC> int ItemDichotomous<D, ICC>::HasAnalyticHessian() const
  {
    return mICC.HessianDefined();
  }

  //! Indicates that the parameter vector creates a valid function value.
  template<class D, class ICC> int ItemDichotomous<D, ICC>::ValidParameters(
      const RealVector &param, bool ignorePriors) const
  {
    if (!(mICC.ValidParameters(param)))
      return 0;

    return ItemNR<D>::ValidParameters(param, ignorePriors);
  }

  /*!
    \brief
    Transforms the parameter estimates to new latent variable scale.
    
    Returns 1 if scaling results in invalid parameters. In this case parameters
    are not modified.
    
    
    \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]  ignorePriors  If TRUE, do not check if tranformed parameters fall outside the
          prior regions.
   */
  template<class D, class ICC> int ItemDichotomous<D, ICC>::ScaleParameters(Real slope,
      Real intercept, bool ignorePriors)
  {
    RealVector scaledParam(ItemNR<D>::mParameterEstimates); // Added "ItemNR<D>::" reference. ww, 1/12/2008.

    mICC.Scale(slope, intercept, scaledParam);

    // Check if scaled parameters are valid
    if (!(ValidParameters(scaledParam, ignorePriors)))
      return 1;

    ItemNR<D>::mParameterEstimates = scaledParam;

    return 0;
  }

}

#endif //ETIRM_ITEMDICHOTOMOUS_H_

---