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

Go to the documentation of this file.

/*! \file Examinee.h
 
  \brief 
  Class to store an item response pattern, the posterior LV distribution, 
  and the marginal likelihood of the pattern.  
 
  The Examinee class stores item responses for an examinee and a
  count to weight the examinee in the case an Examinee object represents
  multiple examinees with the same response pattern.
  Optionally, a posterior discrete latent variable distribution can
  be stored, and the marginal likelihood of the response pattern for the
  examinee.
 
  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_EXAMINEE_H_
#define ETIRM_EXAMINEE_H_

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

namespace etirm
{

  /*!
    \brief
    Class to store a response pattern, its frequency, 
    the posterior distribution of the ability parameter and the 
    marginal likelihood of the pattern.
   
    \section template_args Template Parameters
   
    \param P  Type for storing vector of posterior probabilities.
    \param R  Type for storing vector of item responses.
   */
  template <class R, class P> class Examinee
  {

public:

    typedef R response_vector; //!< Response vector type.
    
    typedef P posterior_vector; //!< Type for vector of posterior probabilities. 
    
    typedef typename R::value_type response_type; //!< Response type.
    
    typedef typename R::iterator response_iterator; //!< Iterator over item responses.

    //! Constructor
    Examinee(int nitems = 0) :
      mCount(1.0), mResponses(nitems), mPosterior(0), mMarginalResponseLikelihood(0.0)
    {
    }

    //! Destructor.
    virtual ~Examinee();

    /*! 
      \brief
      Assigns the examinee's item responses (copies response vector).
      
      \section function_args Function Parameters
   
      \param[in]  &responses  Address of examinee's response vector.
     */
    void SetResponses(response_vector &responses)
    {
      mResponses = responses;
    }

    //! Iterator to first response.
    response_iterator responses_begin()
    {
      return mResponses.begin();
    }

    //! Iterator to one past last response
    response_iterator responses_end()
    {
      return mResponses.end();
    }

    //! Returns the number of times to count the pattern of item responses for this examinee.
    Real Count()
    {
      return mCount;
    }

    /*!
      \brief
      Assigns the number of times to count the pattern of item responses for this examinee.
      
      \section function_args Function Parameters
   
      \param[in]  count Weight for counting the examinee's item response vector.
     */
    void SetCount(Real count)
    {
      mCount = count;
    }

    //! Number of items in examinee response vector
    int NumItems()
    {
      return mResponses.size();
    }

    /*!
      \brief
      Assigns posterior latent variable probabilities for examinee.
      
      \section function_args Function Parameters
   
      \param[in]  &posterior Address of posterior probability vector for examinee.
     */
    void SetPosterior(posterior_vector &posterior);

    /*!
      \brief
      Assigns iterator to first element of the examinee's posterior probability vector.
      
      Note: This function is defined within the class definition so that
      it compiles with Microsoft Visual C++ 6.
     */
    typename P::iterator posterior_begin()
    {
      if (!mPosterior)
        throw RuntimeError("No posterior distribution for examinee", "Examinee::posterior_begin");
      return mPosterior->begin();
    }

    //! Number of categories in discrete latent variable distribution.
    int NumLatentVarCat()
    {
      return (mPosterior ? mPosterior->size() : 0);
    }

    /*! 
      \brief
      Assigns marginal likelihood of examinee's response pattern.
      
      \section function_args Function Parameters
   
      \param[in]  likelihood Value of marginal likelihood of examinee's response pattern.
     */ 
    void SetMarginalRespLikelihood(Real likelihood)
    {
      mMarginalResponseLikelihood = likelihood;
    }
    
    /*!
      \brief
      Returns marginal likelihood of examinee's response pattern.
     */
    Real GetMarginalRespLikelihood()
    {
      return mMarginalResponseLikelihood;
    }

protected:

    Real mCount;
    //!< Number of examinees with the pattern of item responses in mResponses.

    response_vector mResponses;
    //!< Responses to items. Includes responses to items not presented to the examinee.

    posterior_vector *mPosterior;
    //!< Posterior latent variable probabilities for examinee.

    Real mMarginalResponseLikelihood;
    //!< Marginal likelihood of examinee's response pattern.
  };

  /*! Destructor */
  template <class R, class P> Examinee<R, P>::~Examinee()
  {
    if (mPosterior)
      delete mPosterior;
  }

  /* Set posterior latent variable probabilities for examinee */
  template <class R, class P> void Examinee<R, P>::SetPosterior(posterior_vector &posterior)
  {
    if (mPosterior)
    {
      *mPosterior = posterior;
    }
    else
    {
      mPosterior = new posterior_vector(posterior);
    }
  }

} // namespace etirm

#endif // ETIRM_EXAMINEE_H_

---