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

Go to the documentation of this file.

/*! \file ItemPolytomous.h

  \brief
  Class representing a polytomously 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_ITEMPOLYTOMOUS_H_
#define ETIRM_ITEMPOLYTOMOUS_H_

#ifdef ETIRM_NO_DIR_PREFIX
#include "etirmtypes.h"
#include "ItemNR.h"
#else
#include "etirm/etirmtypes.h"
#include "etirm/ItemNR.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 log
#ifdef BOOST_NO_STDC_NAMESPACE
// for compilers which put C library functions in std namespace
namespace std
{ using ::log;}
#endif

namespace etirm
{

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

    \section template_args Template Parameters
   
    \param LC Type of container holding possible values of the
        discrete latent variable.
    \param M  Type containing functions defining item characteristic 
        response function (ICRF) and derivatives of ICRF.
   */
  template <class LC, class M> class ItemPolytomous : public ItemNR<LC>
  {

public:

    /*!
      \brief
      Constructor of polytomous response model class.

      \section template_args Template Parameters
   
      \param LC Type of container holding possible values of the
          discrete latent variable.
      \param M  Type containing functions defining item characteristic 
          response function (ICRF) and derivatives of ICRF.
 
      \section function_args Function Parameters

      \param[in] index Zero-offset index of the item in the vector of all item responses.
      \param[in]  icrf  Address of item category response function for the model.
      \param[in]  dist  Pointer to discrete latent variable points used in calculating the r's.
     */
    ItemPolytomous(int index, M &icrf, LC *dist);

    //! Deconstructor of polytomous response model class.
    virtual ~ItemPolytomous();

    /*!
      \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 mICRF.
     */
    virtual RealVector GetAllParameters() const
    {
      RealVector allParam(mICRF.NumAllParameters());
      mICRF.GetAllParameters(ItemNR<LC>::mParameterEstimates, allParam); // Added "ItemNR<LC>::" reference. ww, 1/12/2008.
      return allParam;
    }

    //! Assigns values of fixed and estimated parameters.
    virtual void SetAllParameters(const RealVector &allParam)
    {
      mICRF.SetAllParameters(allParam.begin(), allParam.end(), ItemNR<LC>::mParameterEstimates);
    } // Added "ItemNR<LC>::" reference. ww, 1/12/2008.


    virtual Real ICRF(const Response r, const RealVector &parameters, const Real &theta) const;

    virtual int ScaleParameters(Real slope, Real intercept, bool ignorePrior = false);
    // Transforms parameter estimates to new latent variable scale.

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

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

    /*  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
    {
      return mICRF.GradientDefined();
    }

    virtual int HasAnalyticHessian() const
    {
      return 0;
    }

protected:

    M mICRF;
    //!< Object for calculating ICRF and its derivatives.

  };

  /* Constructor  */
  template <class LC, class M> ItemPolytomous<LC, M>::ItemPolytomous(int index, M &icrf, LC *dist) :
    ItemNR<LC>(icrf.NumParameters(), index, icrf.NumRespCat(), dist), mICRF(icrf)
  {
    if (ItemNR<LC>::mNRespCat != icrf.NumRespCat()) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
    {
      throw InvalidArgument("Mismatch in number of response categories for item and ICRF",
          "ItemPolytomous::ItemPolytomous");
    }
  }

  /* Destructor */
  template <class LC, class M> ItemPolytomous<LC, M>::~ItemPolytomous()
  {
  }

  /*!
    \brief
    Returns value of item characteristic curve for response "r", item parameters "parameters", 
    and latent variable value "theta".
    
    \section template_args Template Parameters
   
    \param LC Type of container holding possible values of the
        discrete latent variable.
    \param M  Type containing functions defining item characteristic 
        response function (ICRF) and derivatives of ICRF.
 
    \section function_args Function Parameters

    \param[in] r  Response category.
    \param[in] &parameters  Item parameter vector.
    \param[in] &theta Ability parameter.
   */
  template <class LC, class M> inline Real ItemPolytomous<LC, M>::ICRF(const Response r,
      const RealVector &parameters, const Real &theta) const
  {
    return mICRF.ICRF(r, parameters, theta);
  }

  /*! 
    \brief
    Function to maximize in M-step.
    
    \section template_args Template Parameters
   
    \param LC Type of container holding possible values of the
        discrete latent variable.
    \param M  Type containing functions defining item characteristic 
        response function (ICRF) and derivatives of ICRF.
 
    \section function_args Function Parameters

    \param[in] &param Address of item parameter vector.
    
    Note: Technically, negative value of function is being minimized, so the negative function 
      value is being returned.
   */
  template <class LC, class M> double ItemPolytomous<LC, M>::f_to_minimize(RealVector &param)
  {
    int i, j, grp;
    Real value = 0.0;
    int ngroups = ItemNR<LC>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    /* Compute loglikelihood */
    for (grp=1; grp<=ngroups; ++grp)
    {
      Response r = ItemNR<LC>::FirstResponse(); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
      for (i = ItemNR<LC>::mNRespCat; i--; ++r) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
      {
        typename ItemNR<LC>::r_iterator ir = ItemNR<LC>::RVector(r, grp); // Added "typename" and "ItemNR<LC>::" references. ww, 1/13/2008.
        typename ItemNR<LC>::point_iterator it = ItemNR<LC>::mLatentDist->begin_points(grp); // Added "typename" and "ItemNR<LC>::" reference. ww, 1/13/2008.
        for (j=ItemNR<LC>::mNumLatentVarCat; j--; ++ir, ++it) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
        {
          Real prob = mICRF.OpenICRF(r, param, *it);
          value += *ir * std::log(prob);
        }
      }
    }

    /* Add priors */
    PriorVector::const_iterator iprior = ItemNR<LC>::mPriors.begin(); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
    RealVector::iterator iparam = param.begin();
    for (int j = ItemNR<LC>::NumParameters(); j--; ++iprior, ++iparam) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
    {
      if (*iprior)
      {
        if ((*iprior)->ZeroDensity(*iparam))
        {
          // If density of prior is zero then 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 LC Type of container holding possible values of the
        discrete latent variable.
    \param M  Type containing functions defining item characteristic 
        response function (ICRF) and derivatives of ICRF.
 
    \section function_args Function Parameters
    
    \param[in] &param Address of item parameter vector.
    \param[out] &g  Address of gradient vector. Gradient values are returned in the vector elements.
    
    Note: Technically, negative value of function is being minimized, so the negative gradient 
      is being returned.
   */
  template <class LC, class M> void ItemPolytomous<LC, M>::gradient(RealVector &param,
      RealVector &g)
  {
    g = 0.0;
    RealVector deriv(ItemNR<LC>::NumParameters(), 0.0); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    int i, j, grp;
    int ngroups = ItemNR<LC>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    for (grp=1; grp<=ngroups; ++grp)
    {
      Response r = ItemNR<LC>::FirstResponse(); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
      for (i = ItemNR<LC>::mNRespCat; i--; ++r) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
      {

        typename ItemNR<LC>::r_iterator ir = ItemNR<LC>::RVector(r, grp); // Added "typename" and "ItemNR<LC>::" references. ww, 1/13/2008.
        typename ItemNR<LC>::point_iterator itheta = ItemNR<LC>::mLatentDist->begin_points(grp); // Added "typename" and "ItemNR<LC>::" references. ww, 1/13/2008.
        for (j=ItemNR<LC>::mNumLatentVarCat; j--; ++ir, ++itheta) // Added "ItemNR<LC>::" reference. ww, 1/13/2008.
        {
          Real t = *ir / mICRF.OpenICRF(r, param, *itheta);

          mICRF.ICRFDeriv1(r, param, *itheta, deriv);

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

        }
      }
    }

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

  }

  /*!
    \brief
    Transforms parameter estimates to new latent variable scale.
    
    Returns 1 if scaling results in invalid parameters. In this case, the parameters
      are not modified.

    \section template_args Template Parameters
   
    \param LC Type of container holding possible values of the
        discrete latent variable.
    \param M  Type containing functions defining item characteristic 
        response function (ICRF) and derivatives of ICRF.
 
    \section function_args Function Parameters
      
    \param[in]  slope Scale parameter for transformation.
    \param[in]  intercept Intercept parameter for transformation.
    \param[in]  ignorePriors  Flag to ignore prior information when checking validity of transformed parameters.
   */ 
  template <class LC, class M> int ItemPolytomous<LC, M>::ScaleParameters(Real slope,
      Real intercept, bool ignorePriors)
  {
    RealVector scaledParam(ItemNR<LC>::mParameterEstimates); // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    mICRF.Scale(slope, intercept, scaledParam);

    // Check if scaled parameters are valid
    if (!(ItemNR<LC>::ValidParameters(scaledParam, ignorePriors)))
      return 1; // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    ItemNR<LC>::mParameterEstimates = scaledParam; // Added "ItemNR<LC>::" reference. ww, 1/13/2008.

    return 0;
  }

}

#endif // ETIRM_ITEMPOLYTOMOUS_H_

---