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

Go to the documentation of this file.

/*! \file ItemNR.h
 
  \brief
  ItemNR class, derived from Item, maintains information calculated for 
  an Item object in the E-step so that it can be used in the M-step
  to estimate item parameters.
 
  Information stored from the E-step includes the expected number of
  examinees in each category of the discrete latent variable of those
  that took the item (these usually are denoted by the letter "n"),
  and for each item response the expected number of examinees in each
  category of the discrete latent variable who gave that item response
  of those examinees who took the item (these usually are denoted by
  the letter "r").

  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-2001, Bradley A. Hanson
 */

#ifndef ETIRM_ITEMNR_H_
#define ETIRM_ITEMNR_H_

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

namespace etirm
{
  /*!    
    \brief
    Class, derived from Item, to maintain information calculated for 
    an Item object in the E-step so that it can be used in the M-step
    to estimate item parameters.
 
    Information stored from the E-step includes the expected number of
    examinees in each category of the discrete latent variable of those
    that took the item (these usually are denoted by the letter "n"),
    and for each item response the expected number of examinees in each
    category of the discrete latent variable who gave that item response
    of those examinees who took the item (these usually are denoted by
    the letter "r").

    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.
   */
  template <class D> class ItemNR : public Item<typename D::latentvar_type>
  {

public:
  
    //! Type iterator over responses of an item.
    typedef RealMatrix::row_iterator r_iterator;
    
    //! Type iterator over number of examinees who responded to an item.
    typedef RealVector::iterator n_iterator;

    //! Type iterator over quadrature points.
    typedef typename D::point_iterator point_iterator;
    
    /*!
      \brief
      Constructor.
      
      \section template_args Template Parameters
   
      \param D  Class for discrete latent variable distribution.
    
      \section function_args Function Parameters

      \param[in] nparam Number of item parameters.
      \param[in] index  Zero-offset index of item in vector of all item responses.
      \param[in] respCat  Number of response categories.
      \param[in] dist Latent variable distribution.
     */ 
    ItemNR(int nparam, int index, int respCat, D *dist = 0);

    //! Destructor.
    virtual ~ItemNR();

    /*!
      \brief
      Returns iterator to first element of row of mR corresponding to response "resp" 
      for examinee group "group" (where the first examinee group is group 1)
    
      \section function_args Function Parameters
    
      \param[in] resp Response vector.
      \param[in] group  Examinee group (default =1).
     */ 
    r_iterator RVector(Response resp, int group = 1);

    /*!
      \brief
      Returns iterator to first element of mN for examinee group "group" 
      (where the first examinee group is group 1).
      
      \section function_args Function Parameters
    
      \param[in]  group Group index.
     */
    n_iterator NVector(int group = 1);


    /*!
      \brief
      Assigns values associated with discrete latent variable categories.
      
      Note: I was not able to locate any SetLatentVarPoints function in the code base.
      It is questionable whether this function is operative at all (ww, 2-28-2008).
      
      \section function_args Function Parameters
   
      \param[in]  n Number of discrete categories of the latent ability distribution.
      \param[in]  points  Iterator over quadrature points.
     */
    void SetLatentVarPoints(int n, point_iterator points);

    /*!
      \brief
      Returns iterator over quadrature points.

      \section function_args Function Parameters
   
      \param[in]  group \ Examinee group (1, 2, ..., "number of groups").
     */       
    point_iterator GetLatentVarPoints(int group = 1)
    {
      return mLatentDist->begin_points(group);
    }

    //! Returns number of discrete latent variable categories.
    int NumLatentVarCat()
    {
      return mNumLatentVarCat;
    }

    /*!
      \brief
      Initializes elements of mR and mN to zero.
     */
    void InitializeNR();

    /*  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. */

    /*! 
      \brief
      Function to maximize in M-step.
      
      \section function_args Function Parameters
      
      \param[in] &p Address of item parameter vector.
      
      Note: Technically, negative value of function is being minimized, so the negative function 
        value is being returned.
     */
    virtual double f_to_minimize(RealVector &p) = 0;

    /*!
      \brief
      Computes gradient of function to maximize in M-step.
      
      \section function_args Function Parameters
      
      \param[in] &p 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.
     */
    virtual void gradient(RealVector &p, RealVector &g) = 0;

    /*!
      \brief
      Computes hessian of function to maximize in M-step.
      
      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.
     */
    virtual void hessian(RealVector &x, RealMatrix &h) = 0;

    /*!
      \brief
      Function to indicate that the algebraic gradient of the item (ICCDeriv1) is defined.
      
      This function can be used by UNCMIN++.
     */
    virtual int HasAnalyticGradient() const = 0;

    /*!
      \brief
      Function to indicate that the algebraic hessian of the item (ICCDeriv2) is defined.
      
      This function can be used by UNCMIN++.
     */
    virtual int HasAnalyticHessian() const = 0;

    /*!
      \brief
      Returns 1 if all parameters have a non-zero prior density, or 0 otherwise.
      
      \section function_args Function Parameters
      
      \param[in]  &p Address of parameter vector for this item.
      \param[in]  ignorePriors  Boolan flag to bypass the test of prior densities.
     */
    virtual int ValidParameters(const RealVector &p, bool ignorePriors = false) const;

    /*!
      \brief
      Number of item parameters.
     */
    int dim() const
    {
      return Item<typename D::latentvar_type>::NumParameters();
    } // Added "Item<typename D::latentvar_type>::" to NumParameters method call. ww, 1/12/2008

protected:

    D *mLatentDist;
    //!< Latent variable distribution used to determine discrete categories on the latent variable.

    /*!
      \brief
      Expected number of respondents in each latent variable category
      who took this item and gave the i-th response.
      
      If there are different points for different examinee groups
      the expected number of examinees will differ for different groups,
      and will be stacked in each row.

      The first mNumLatentVarCat values will be for the first group,
      the second mNumLatentVarCat values will be for the second group, etc.
      These expected counts are computed in the E-step.
     */
    RealMatrix *mR;

    /*!
      \brief
      Expected number of examinees who took this item in
      each latent variable category.
      
      If there are different points for different examinee groups
      the expected number of examinees will differ for different groups,
      and will be stacked.

      The first mNumLatentVarCat values will be for the first group,
      the second mNumLatentVarCat values will be for the second group, etc.
      These expected counts are computed in the E-step.
     */
    RealVector *mN;


    int mNumLatentVarCat;
    //!< Number of latent variable categories.

  };

  /* 
    \brief
    Class constructor.
   
    \section template_args Template Parameters
   
    \param D  Class for discrete latent variable distribution.

    \section function_args Function Parameters
    
    \param[in]  nparam  Number of item parameters
    \param[in]  index   Zero-offset index of item in vector of all item responses
    \param[in]  respCat Number of response categories for item.
    \param[in]  dist    Latent variable distribution used to define discrete 
        latent variable points.
   */
  template <class D>
#ifndef BOOST_MSVC
  ItemNR<D>::ItemNR(int nparam, int index, int respCat, D *dist) :
    Item<typename D::latentvar_type>(nparam, index, respCat),
#else
        ItemNR<D>::ItemNR(int nparam, int index, int respCat, D *dist) : Item<D::latentvar_type>(nparam, index, respCat),
#endif
        mLatentDist(dist), mR(0), mN(0), mNumLatentVarCat(0)
  {
    if (dist)
    {
      mNumLatentVarCat = dist->size();
      // Compute total number of latent distribution points over all groups for
      // which the points are unique
      int totpoints = mLatentDist->NumGroupsUnique() * mNumLatentVarCat;

      mR = new RealMatrix(respCat, totpoints);
      mN = new RealVector(totpoints);
    }
  }

  /*
    \brief
    Class destructor. 
   */
  template <class D> ItemNR<D>::~ItemNR()
  {
    if (mN)
      delete mN;
    if (mR)
      delete mR;
  }

  /*
    \brief
    Initializes elements of mR and mN to zero.
   */
  template <class D> void ItemNR<D>::InitializeNR()
  {
    if (mN)
      *mN = 0.0;
    if (mR)
      *mR = 0.0;
  }

  /*
    \brief
    Returns iterator to first element of row of mR corresponding to response "resp" 
    for examinee group "group" (where the first examinee group is group 1)
    
    \section function_args Function Parameters
    
    \param[in] resp Response vector.
    \param[in] group  Examinee group.
   */
  template <class D> typename ItemNR<D>::r_iterator ItemNR<D>::RVector(Response resp, int group)
  {
    int ngroups = mLatentDist->NumGroups();
    if (group > ngroups || group < 1)
      throw InvalidArgument("Invalid group", "ItemNR::RVector");

    r_iterator rvec = mR->begin_row(Item<typename D::latentvar_type>::ResponseIndex(resp)+1); // Added "Item<typename D::latentvar_type>::" to ResponseIndex method call. ww, 1/12/2008

    return (mLatentDist->NumGroupsUnique() == 1) ? rvec : (rvec + (group-1) * mNumLatentVarCat);
  }

  /*
    \brief
    Returns iterator to first element of mN for examinee group "group" 
    (where the first examinee group is group 1).
    
    \section function_args Function Parameters
    
    \param[in]  group Group index.
   */
  template <class D> typename ItemNR<D>::n_iterator ItemNR<D>::NVector(int group)
  {
    int ngroups = mLatentDist->NumGroups();
    if (group > ngroups || group < 1)
      throw InvalidArgument("Invalid group", "ItemNR::NVector");

    n_iterator nvec = mN->begin();
    return (mLatentDist->NumGroupsUnique() == 1) ? nvec : (nvec + (group-1) * mNumLatentVarCat);
  }

  /*
    \brief
    Returns 1 if all parameters have a non-zero prior density, or 0 otherwise.
    
    \section function_args Function Parameters
    
    \param[in]  &param Address of parameter vector for this item.
    \param[in]  ignorePriors  Boolan flag to bypass the test of prior densities.
   */
  template <class D> int ItemNR<D>::ValidParameters(const RealVector &param, bool ignorePriors) const
  {
    // For each parameter check that prior density at the value of the
    // parameter is not zero
    if (!ignorePriors)
    {
      PriorVector::const_iterator iprior = Item<typename D::latentvar_type>::mPriors.begin();
      RealVector::const_iterator iparam = param.begin();
      for (int i=Item<typename D::latentvar_type>::NumParameters(); i--; ++iprior, ++iparam) // Added "Item<typename D::latentvar_type>::" to NumParameters method call. ww, 1/12/2008
      {
        if (*iprior)
        {
          if ((*iprior)->ZeroDensity(*iparam))
          {
            return 0;
          }
        }
      }
    }
    return 1;
  }

} // namespace etirm

#endif // ETIRM_ITEMNR_H_

---