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

Go to the documentation of this file.

/*! \file DiscreteLatentDist.h
 
  \brief
  Class containing information about a discrete latent variable distribution
  for one or more groups of examinees.

  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_DISCRETELATENTDIST_H_
#define ETIRM_DISCRETELATENTDIST_H_

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

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

namespace etirm
{

  /*!
    \brief
    Class approximating the latent ability distribution by numeric quadrature.

    \section template_args Template Parameters
   
    \param  L  Type of latent variable.
   */
  template <class L> class DiscreteLatentDist
  {

public:

    typedef L latentvar_type; //!< Type of latent variable.
    typedef std::vector<L> point_container; //!< Type of container for points.
    typedef typename std::vector<L>::iterator point_iterator; //!< Type of iterator over quadrature points.
    typedef RealMatrix::row_iterator weight_iterator; //!< Type of iterator over quadrature weigths.

    //! Constructor using number of quadrature points, number of groups, etc.
    DiscreteLatentDist(int ntheta, int ngroups = 1, bool uniquePoints = false);
    
    //! Copy constructor using DiscreteLatentDist object.
    DiscreteLatentDist(const DiscreteLatentDist &dist);

    point_iterator begin_points(int g = 1);
    // Returns iterator to first point for group g (1-offset).

    weight_iterator begin_weights(int g = 1);
    // Returns iterator to first weight for group g (1-offset).

    int size();
    // Returns number of discrete points.

    int NumGroups();
    // Returns number of examinee groups.

    int NumGroupsUnique();
    // Returns number of examinee groups for which points of latent distribution are unique.

    void Transform(Real slope, Real intercept);
    // Transforms scale of points using a specified linear transformation.

    void Scale(Real mean, Real sd, int group, Real &slope, Real &intercept);
    // Modifies points to obtain a specified mean and s.d. for a group.

    void MeanSD(int group, Real &mean, Real &sd);
    // Computes mean and s.d. of distribution for a group.

    virtual Real MStep(const RealVector &eprob, int g);
    // Computes an M-step for the probabilities of the multinomial discrete latent variable 
    // distribution in one examinee group.
    
private:

    bool mUniquePoints;
    //!< If true then unique latent distribution points are used for each group.

    int mNumPoints;
    //!< Number of points in latent variable distribution for each group.

    int mNumGroups;
    //!< Number of examinee groups.

    std::vector<L> mPoints;
    /*!<  Vector of latent distribution points.
      If unique latent distribution points are used for each group
      then the size of this vector will be the product of the number
      of points in each group and the number of groups.
      The points for each group are stacked in this vector, so the
      first point for group g is mPoints[mNumPoints * (g-1)].
     */

    RealMatrix mWeights;
    //!< Each row gives the distribution for one group of examinees.
  };

  /* Constructor */
  template<class L> DiscreteLatentDist<L>::DiscreteLatentDist(int ntheta, int ngroups,
      bool uniquePoints) :
    mNumPoints(ntheta), mPoints(ntheta), mWeights(ngroups, ntheta), mUniquePoints(uniquePoints),
        mNumGroups(ngroups)
  {
    if (uniquePoints)
      mPoints.resize(ntheta*ngroups);
  }

  /* Copy constructor */
  template<class L> DiscreteLatentDist<L>::DiscreteLatentDist(const DiscreteLatentDist &dist) :
    mUniquePoints(dist.mUniquePoints), mNumPoints(dist.mNumPoints), mNumGroups(dist.mNumGroups),
        mPoints(dist.mPoints), mWeights(dist.mWeights)
  {
  }

  /*! 
    \brief
    Returns the number of discrete points for each group.

    \section template_args Template Parameters

    \param  L  Type of latent variable. 
   */
  template<class L> inline int DiscreteLatentDist<L>::size()
  {
    return mNumPoints;
  }

  /*! 
    \brief
    Returns the number of groups of examinees.

    \section template_args Template Parameters
 
    \param  L  Type of latent variable. 
   */
  template<class L> inline int DiscreteLatentDist<L>::NumGroups()
  {
    return mNumGroups;
  }

  /*!
    \brief
    Returns number of examinee groups for which points of latent distribution are unique.
    
    \section template_args Template Parameters
 
    \param  L  Type of latent variable.
   */
  template<class L> inline int DiscreteLatentDist<L>::NumGroupsUnique()
  {
    return mUniquePoints ? mNumGroups : 1;
  }

  /*! 
    \brief
    Returns iterator to first point for group g (1-offset).

    \section template_args Template Parameters
 
    \param  L  Type of latent variable.

    \section function_args Function Parameters
   
    \param[in]  g Group to return pointer for, where first group = 1, second group = 2, etc.
   */
  template<class L> inline typename std::vector<L>::iterator DiscreteLatentDist<L>::begin_points(
      int g)
  {
    return mUniquePoints ? (mPoints.begin()+mNumPoints*(g-1)) : mPoints.begin();
  }

  /*! 
    \brief
    Returns iterator to first weight for group g (1-offset).

    \section template_args Template Parameters
 
    \param  L  Type of latent variable.

    \section function_args Function Parameters
   
    \param  g Group to return weights for, where first group = 1, second group = 2, etc.
   */
  template<class L> inline typename RealMatrix::row_iterator DiscreteLatentDist<L>::begin_weights(
      int g)
  {
    return mWeights.begin_row(g);
  }

  /*! 
    \brief 
    Computes mean and standard deviation in the specified group.

    \section template_args Template Parameters
 
    \param  L  Type of latent variable.
      
    \section function_args Function Parameters
   
    \param[in]  group Group whose distribution is used.
    \param[out] &mean  Address if mean of distribution.
    \param[out] &sd Address of standard deviation of distribution.
   */
  template<class L> void DiscreteLatentDist<L>::MeanSD(int group, Real &mean, Real &sd)
  {
    /* Check for valid group */
    if (group < 1 || group > mNumGroups)
    throw InvalidArgument("Invalid examinee group", "DiscreteLatentDist::MeanSD");

    int i;

    /* Compute mean of distribution in specified group */
    point_iterator ip = begin_points(group);
    weight_iterator iw = begin_weights(group);
    mean = 0.0;
    for (i = mNumPoints; i--; ++ip, ++iw)
    {
      mean += *ip * *iw;
    }

    /* Compute s.d. of distribution in specified group */
    ip = begin_points(group);
    iw = begin_weights(group);
    sd = 0.0;
    for (i = mNumPoints; i--; ++ip, ++iw)
    {
      Real dev = *ip - mean;
      sd += dev * dev * *iw;
    }
    sd = std::sqrt(sd);
  }

  /*!
    \brief
    Transforms scale of points using a specified linear transformation.

    Points for all groups are transformed.

    \section template_args Template Parameters
 
    \param  L  Type of latent variable.
      
    \section function_args Function Parameters
   
    \param[in] slope  Slope of scale transformation.
    \param[in] intercept Intercept of scale transformation.
   */
  template<class L>
  void DiscreteLatentDist<L>::Transform(Real slope, Real intercept)
  {

    int n, i;

    if (mUniquePoints) n = mNumGroups;
    else n = 1;

    /* Transform points for all groups */
    for (int g = 1; g <= n; ++g)
    {
      point_iterator ip = begin_points(g);
      for (i = mNumPoints; i--; ++ip)
      {
        *ip *= slope;
        *ip += intercept;
      }
    }
  }

  /*! 
    \brief
    Transforms scale of points so that mean and standard deviation in the specified
    group are equal to the values indicated. 
    
    Points for all groups are transformed.
   
    \section template_args Template Parameters
 
    \param  L  Type of latent variable. 
      
    \section function_args Function Parameters
   
    \param[in] mean   Desired mean of distribution.
    \param[in] sd   Desired standard deviation of distribution.
    \param[in] group  Group for which mean and s.d. are specified.
    \param[out] slope Slope of scale transformation.
    \param[out] intercept Intercept of scale transformation.
   
   */
  template<class L>
  void DiscreteLatentDist<L>::Scale(Real mean, Real sd, int group,
  Real &slope, Real &intercept)
  {

    /* Check for valid group */
    if (group < 1 || group> mNumGroups)
    throw InvalidArgument("Invalid examinee group", "DiscreteLatentDist::Scale");

    Real oldmean;
    Real oldsd;
    MeanSD(group, oldmean, oldsd);

    /* Compute slope and intercept to transfer from old scale to new scale */
    slope = sd / oldsd;
    intercept = mean - slope * oldmean;

    /* Transform points */
    Transform(slope, intercept);
  }

  /*! 
    \brief
    Computes an M-step for the probabilities of the multinomial discrete latent variable distribution
    in one examinee group.
   
    \section template_args Template Parameters
 
    \param  L  Type of latent variable.
      
    \section function_args Function Parameters
   
    \param[in] &eprob Address of vector containing probabilities for each latent variable 
        category, computed in last E-step for group. 
    \param[in] g  Group to estimate latent distribution for (g = 1, 2, ..., "number of groups").
   */
  template<class L>
  Real DiscreteLatentDist<L>::MStep(const RealVector &eprob, int g)
  {
    int ncat = mNumPoints;

    if (ncat != eprob.size())
    {
      throw RuntimeError("Mismatch in number of latent variable points",
      "DiscreteLatentDist::MStep");
    }

    if (g < 1 || g> mNumGroups)
    {
      throw RuntimeError("Invalid examinee group number",
      "DiscreteLatentDist::MStep");
    }

    /* Find total N for this group */
    RealVector::const_iterator in = eprob.begin();
    Real ntot = 0.0;
    int i;
    for (i = ncat; i--; ++in) ntot += *in;

    /* Update group latent variable distribution */
    Real reldiff = 0.0;
    Real typicalValue = 1.0 / ncat;
    in = eprob.begin();
    weight_iterator iw = begin_weights(g);
    for (i = ncat; i--; ++in, ++iw)
    {
      Real old = *iw;
      *iw = *in / ntot;

      // Compute absolute relative difference between old and new probability
      Real d = old - *iw;
      Real denom = (*iw < typicalValue) ? typicalValue : *iw;
      if (denom != 0.0) d /= denom;
      d = (d < 0.0) ? -d : d; // fabs(d)
      if (reldiff < d) reldiff = d;
    }

    return reldiff;

  }

} // namespace etirm

#endif // ETIRM_DISCRETELATENTDIST_H_

---