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

Go to the documentation of this file.

/*! \file Item.h

  \brief
  Class containing information about an item.

  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_ITEM_H_
#define ETIRM_ITEM_H_

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

#include <string>
#include <iterator>

namespace etirm
{

  /*! 
    \brief
    Class (template) containing information about an item.

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

public:
    //! Type of latent variable.
    typedef L latentvar_type;

    //! Iterator over parameters
    typedef RealVector::iterator param_iterator;
    
    //! Iterator over priors
    typedef PriorVector::iterator prior_iterator;

    //! Parameter vector
    typedef RealVector param_vector;
    
    //! Vector of parameter priors
    typedef PriorVector prior_vector;

    /*! 
      \brief
      Item class constructor
      
        \param[in] nparam Number of item parameters.
        \param[in] index  zero-offset index of item in vector of all item responses.
        \param[in] nRespCat Number of response categories for the item.
     */
    Item(int nparam, int index, int nRespCat);  // Corrected spelling of "nRespcat".

    //! Item class destructor
    virtual ~Item();

    //! Returns vector of estimated parameters for item.    
    RealVector GetParameters() const
    {
      return mParameterEstimates;
    }


    /*! \brief
        Returns all item parameters, including estimated and fixed parameters.
        
        For example, for a two-parameter logistic model only the a and b parameters
        are estimated, but a fixed c parameter could be specified.
        This function would return a vector containing the
        a, b, and c parameters, where only a and b would be
        returned by GetParameters().
     */
    virtual RealVector GetAllParameters() const
    {
      return GetParameters();
    }
    
    void SetParameters(const RealVector &param);

#ifndef BOOST_MSVC6_MEMBER_TEMPLATES
    template<class I> void SetParameters(I begin, I end);
#endif

    /*! \brief
        Sets all item parameters, including estimated and fixed parameters.
        
        For example, for a two-parameter logistic model only the a and b parameters
        are estimated, but a fixed c parameter could be specified.
        This function would set the a and b parameters the same as
        SetParameters, but would also set the fixed c parameter. 
     */
    virtual void SetAllParameters(const RealVector &allParam)
    {
      SetParameters(allParam);
    }

    /*!
      \brief
      Version of SetAllParameters that uses an iterator range to 
      define the sequence of all parameters.
     */
    template<class I> void SetAllParameters(I begin, I end)
    {
      RealVector allParam(begin, end);
      SetAllParameters(allParam);
    }

    PriorVector::iterator PriorsIterator()
    {
      return mPriors.begin();
    }
    //!< Returns iterator pointing to the first prior element of the first item parameter

    RealVector::iterator ParametersIterator()
    {
      return mParameterEstimates.begin();
    }
    //!< Returns iterator to the estimate of the first parameter

    void SetPriors(PriorVector &priors);
    //!< Assigns prior distributions of item parameters.

    //! Returns vector (mPriors) of parameter priors
    PriorVector GetPriors()
    {
      return mPriors;
    } // Changed "priors" to "mPriors". ww, 1/10/2008.

    void DeletePriors();
    //!< Releases memory for all priors in mPriors

    virtual int NonZeroPriors(RealVector &p) const;

    int NumParameters() const
    {
      return mNumParameters;
    }
    //!< Returns the number of parameters of the item

    int NumRespCat() const
    {
      return mNRespCat;
    }
    //!< Returns the number of valid response categories for item

    /*! 
      \brief
      Returns true if response "r" is a valid response for this item,
      otherwise return false.
      
      It is assumed that valid item responses are 
      mFirstResponse, mFirstResponse+1, ..., mFirstResponse+NumRespCat()-1.
      mNotPresentedResponse is not a valid response.
     */ 
    bool ValidResponse(Response r) const
    {
      return ((r >= mFirstResponse) && (r <= LastResponse())) ? true : false;
    }
    
    /*!
       \brief
       Returns true if "r" is a valid response or is the constant indicating
       no response to the item.
     */
    bool CheckResponse(Response r) const
    {
      return (ValidResponse(r) || r == notPresentedResponse) ? true : false;
    }

    virtual int ScaleParameters(Real slope, Real intercept, bool ignorePriors = false) = 0;
    //!< Transforms item parameters to new latent variable scale

    /*!
      \brief
      Item category response function giving the probability of response r
      for the item parameters "parameters" and the latent variable "theta".
     */
    virtual Real ICRF(Response r, const RealVector &parameters, const L &theta) const = 0;


#ifndef BOOST_MSVC6_MEMBER_TEMPLATES
    /*!
      \brief
      Computes the probabilities of all possible responses to the item
      for the latent variable "theta" and the item parameters "parameters". 
      
      Probabilities are stored using iterator iprob, which points to the location 
      where the probability for the first response category should be stored.
     */
    template<class I> void ICRFAll(const RealVector &parameters, const L &theta, I iprob) const;

#endif

    /*!
      \brief
      Returns probability of response r for parameter estimates in "mParameterEstimates"
      and the latent variable "theta".
     */
    Real ProbResp(Response r, const L &theta) const
    {
      return ICRF(r, mParameterEstimates, theta);
    }

    /*!
      \brief
      Computes the probabilities of all possible responses to the item
      for the the latent variable "theta". 
      
      Probabilities are stored using iterator iprob, which points to 
      the location where the probability for the first response category 
      should be stored.
     */
    template<class I> void ProbRespAll(const L &theta, I iprob) const
    {
      ICRFAll<I>(mParameterEstimates, theta, iprob);
    }

    /*!
      \brief
      Returns the normalizing constant used for some IRT models, such 
      as D for the 3PL model.
     */
    virtual Real NormalizingConstant() const
    {
      return 1.0;
    }

    /*!
      \brief
      Returns index associated with response, where ResponseIndex(firstResponse) == 0, 
      ResponseIndex(firstResponse+1) == 1, ..., 
      ResponseIndex(firstResponse+NumRespCat()-1) == NumRespCat()-1
      
      Assumes r is a valid response not equal to notPresentedResponse.
     */
    int ResponseIndex(const Response r) const
    {
      return r - mFirstResponse;
    }

    /*! 
      \brief
      Returns response in response category "index".
    
      Note: This is the inverse of the ResponseIndex function.
      It is assumed that index >= 0.
     */
    Response IndexResponse(const int index) const
    {
      return mFirstResponse + index;
    }


    int Index() const
    {
      return mIndex;
    }
    //!< Returns zero-offset index of item (first item has index 0).


    virtual std::string ModelName() const = 0;
    //!< Returns string containing name of model used for item.

    virtual IRTModel Model() const = 0;
    //!< Returns type of model used for item.

    /*!
      \brief
      Assigns response associated with first response category.
      
      Responses associated with other response categories are
      assumed to mFirstResponse+1, mFirstResponse+2, ...
     */
    virtual void SetFirstResponse(Response r)
    {
      mFirstResponse = r;
      // Make sure response indicating that item was not taken
      // is not a valid response
      if (ValidResponse(notPresentedResponse))
        throw RuntimeError("Not presented response is in range of valid responses",
            "Item::SetFirstResponse");
    }

    /*!
      \brief
      Returns the response corresponding to first response category.
      
      The response corresponding to the i-th response category
      would be FirstResponse() + (i-1).
     */
    Response FirstResponse() const
    {
      return mFirstResponse;
    }

    Response LastResponse() const
    {
      return mFirstResponse + NumRespCat() - 1;
    }
    //!< Returns the response corresponding to last response category.

    /*!
      \brief
      Returns response that is considered correct for dichotomous items.
    
      Should be overriden for class representing dichotomous items.
     */ 
    virtual Response CorrectResponse()
    {
      // By default throw an exception indicating there no response considered correct
      throw RuntimeError("No correct response for item", "Item::CorrectResponse()");
      return 0;
    }

    /*!
      \brief
      Returns the response which indicates an item was not presented,
      or that the examinee did not respond to the item.
     */
    static Response NotPresentedResponse()
    {
      return notPresentedResponse;
    }

    /*!
      \brief
      Returns true if "r" is equal to the constant that represents
      no response to the item.
     */
    static bool IsNoResponse(Response r)
    {
      return r == notPresentedResponse;
    }

    /*!
      \brief 
      Returns the response associated with the first response category
      if SetDefaultFirstResponse is not called.
     */
    static Response DefaultFirstResponse()
    {
      return defaultFirstResponse;
    }

    /*!
      \brief
      Assigns response indicating item was not presented.
      
      This should only be called before any item objects
      have been created.
     */
    static void SetNotPresentedResponse(Response r)
    {
      notPresentedResponse = r;
    }

    static void SetDefaultFirstResponse(Response r)
    {
      defaultFirstResponse = r;
    }
    //!< Assigns response used for initial value of mFirstResponse in constructor.

protected:

    int mIndex;
    //!< A zero-based index of the item in the vector of responses to all items.

    int mNumParameters;
    //!< Number of item parameters.

    int mNRespCat;
    //!< Number of response categories.

    RealVector mParameterEstimates;
    //!< Vector of estimated item parameters.

    PriorVector mPriors;
    //!< Vector of prior distributions for item parameters.

    /*!
      \brief
      Response associated with first response category.
      
      It is assumed that valid responses to the item are
      mFirstResponse, mFirstResponse+1, ..., mFirstResponse+NumRespCat()-1
     */
    Response mFirstResponse;

    // The following static variables must be defined somewhere in a program
    // using this class, such as in the file containing the main program.

    /*!
      \brief
      Response indicating an item was not presented or the examinee
      did not respond to the item.
     */
    static Response notPresentedResponse;


    static Response defaultFirstResponse;
    //!< Default value used for mFirstResponse if SetFirstResponse not called.


#ifdef BOOST_MSVC6_MEMBER_TEMPLATES
    // Definitions of member templates copied from below for compilers 
    // that require member templates to
    // be defined in the class definition.
public:
    template <class I> void ICRFAll(const RealVector &parameters, const L &theta, I iprob) const
    {
      Real sum = 0.0;
      int n = NumRespCat()-1;
      // Compute probabilities for all but last response category
      for (int r = 0; r < n; ++r, ++iprob)
      {
        *iprob = ICRF(IndexResponse(r), parameters, theta);
        sum += *iprob;
      }
      // Probability for last response category
      *iprob = 1.0 - sum;

    }

    template <class I> void Item<L>::SetParameters(I begin, I end)
    {
      typename std::iterator_traits<I>::difference_type n = end - begin;
      if (n != NumParameters())
        throw InvalidArgument("Wrong number of parameters", "Item::SetParameters");

      param_iterator ip = mParameterEstimates.begin();
      while (begin != end)
      {
        *ip = *begin;
        ++begin;
        ++ip;
      }

    }

#endif

  };

  /*! Constructor */
  template<class L> Item<L>::Item(int nparam, int index, int nRespCat) :
    mIndex(index), mNumParameters(nparam), mNRespCat(nRespCat), mParameterEstimates(nparam, 0.0),
        mPriors(nparam, (ItemParamPrior *) 0), mFirstResponse(defaultFirstResponse)
  {
    // Make sure response indicating that item was not taken
    // is not a valid response
    if (ValidResponse(notPresentedResponse))
      throw RuntimeError("Not presented response is in range of valid responses",
          "Item::SetFirstResponse");

  }

  /*
    \brief
    Compute the probabilities of all possible responses to the item
    for the value of the latent variable "theta" and item
    parameters "parameters". 
   
    Probabilities are stored using iterator iprob, which points to the 
    location where the probability or the first response category should 
    be stored.
   
    A copy of this member template is included in the class definition above
    for compilers that do not allow definitions of member templates
    outside the class definition. Any changes to this function must
    also be made to the copy above.
   */
#ifndef BOOST_MSVC6_MEMBER_TEMPLATES
  template<class L> template<class I> void Item<L>::ICRFAll(const RealVector &parameters,
      const L &theta, I iprob) const
  {
    Real sum = 0.0;
    int n = NumRespCat()-1;
    // Compute probabilities for all but last response category
    for (int r = 0; r < n; ++r, ++iprob)
    {
      *iprob = ICRF(IndexResponse(r), parameters, theta);
      sum += *iprob;
    }
    // Probability for last response category
    *iprob = 1.0 - sum;

  }
#endif

  /* Destructor */
  template<class L> Item<L>::~Item()
  {
  }

  //! Assigns values of parameter estimates from vector
  template<class L> void Item<L>::SetParameters(const RealVector &param)
  {
    if (param.size() != NumParameters())
      throw InvalidArgument("Wrong number of parameters", "Item::SetParameters");

    mParameterEstimates = param;

  }

  //! Assigns values of parameter estimates from iterator range
#ifndef BOOST_MSVC6_MEMBER_TEMPLATES
  template<class L> template<class I> void Item<L>::SetParameters(I begin, I end)
  {
    typename std::iterator_traits<I>::difference_type n = end - begin;
    if (n != NumParameters())
    throw InvalidArgument("Wrong number of parameters", "Item::SetParameters");

    param_iterator ip = mParameterEstimates.begin();
    while (begin != end)
    {
      *ip = *begin;
      ++begin;
      ++ip;
    }

  }
#endif

  template<class L> void Item<L>::SetPriors(PriorVector &priors)
  {
    if ( (int)priors.size() != NumParameters()) // Casting first argument to type "int", ww, 3-1-2008.
      throw InvalidArgument("Wrong number of priors", "Item::SetPriors");

    mPriors = priors;

  }

  /* Releases memory for all priors */
  template<class L> void Item<L>::DeletePriors()
  {

    int n = mPriors.size();
    PriorVector::iterator i = mPriors.begin();

    while (n--)
    {
      if (*i != 0)
      {
        delete *i;
        *i = 0;
      }
      ++i;
    }

  }

  /*! 
    \brief
    Ensures that all priors have non-zero, positive densities.
     
    If a value of a parameter in param has zero probability in
    the prior distribution for the parameter then this functions
    changes the parameter prior to a strictly positive density.
    
    Returns the number of parameters that were changed.
   */
  template<class L> int Item<L>::NonZeroPriors(RealVector &param) const
  {
    int n = 0;

    // For each parameter assigns new value to parameter if
    // prior density of parameter value is zero.
    PriorVector::const_iterator iprior = mPriors.begin();
    RealVector::iterator iparam = param.begin();
    for (int i=NumParameters(); i--; ++iprior, ++iparam)
    {
      if (*iprior)
      {
        Real newparam = (*iprior)->NearestNonZero(*iparam);
        if (newparam != *iparam)
        {
          ++n;
          *iparam = newparam;
        }
      }
    }

    return n;

  }

} // namespace etirm

#endif // ETIRM_ITEM_H_

---