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

Go to the documentation of this file.

/*! \file MStepIRT.h
 
  \brief
  Functions used in implementing the M-step for IRT models.

  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_MSTEPIRT_H_
#define ETIRM_MSTEPIRT_H_

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

namespace etirm
{

  /*!
    \brief
    Returns the maximum relative difference between an old and new set of item parameters.
    
    \param[in] &oldParam  Address of vector containing base parameter values.
    \param[in] &newParam  Address of vector containing comparison (new) parameter values.
    \param[in] typicalValue Minimum denominator for relative comparison.
  */
  double MaxRelParamDiff(RealVector &oldParam, RealVector &newParam, Real typicalValue = 1.0);

  /*!
    \brief
    Executes M-step for each item.
    
    This function is used when the M-step can be carried out separately for each item.
   
    Returns 0 if successful.
    
    If ignoreMaxIter is true, and the only error that occurs is that the
    maximum number of M-step iterations is exceeded, then returns
    negative of number of items for which maximum number iterations were
    exceeded. 
    
    If ignoreMaxIter is false and an error occurs, or an error
    other than exceeding the maximum number of M-step iterations occurs,
    then returns the item number (1-offset) for which error occurred and
    processing is stopped at the point of the error.

    \section template_args Template Parameters
   
    \param II Iterator to Item object pointer.
    \param MI Iterator to pointers to minimization routines (interface is for 
        Uncmin, but any minimization routine with the same interface as Uncmin 
        could be used).

    \section function_args Function Parameters

    \param[in]  min_routines Object holding minimization routine (any minimization
       parameters set will be used for each item).
    \param[in]  item_begin  Iterator pointing to first item (*item_begin is a pointer to the first item)
    \param[in]  item_end  Iterator pointing to one past last item (*(item_end-1) is a pointer to the last item)
    \param[out]  &maxreldiff Address of maximum relative difference between an old and new parameter 
       estimate across all items.
    \param[in]  ignoreMaxIter If true and maximum number of M-step iterations are exceeded then
       parameters are used anyway. If false and maximum number of M-step iterations
       are exceeded the function returns immediately with item number at which error occurred.
   */
  template<class MI, class II> int MStepItems(MI min_routines, II item_begin, II item_end,
      double &maxreldiff, bool ignoreMaxIter = false)
  {
    int nMaxIter = 0;
    maxreldiff = 0.0;

    for (II iitem = item_begin; iitem != item_end; ++iitem, ++min_routines)
    {
      (*min_routines)->SetFunction(*iitem);

      int dim = (*iitem)->dim();
      RealVector start = (*iitem)->GetParameters();
      RealVector xpls(dim), gpls(dim);
      double fpls;

      int result = (*min_routines)->Minimize(start, xpls, fpls, gpls);

      if (result != 0)
      {
        int message = (*min_routines)->GetMessage();
        if (ignoreMaxIter && message == 4)
          nMaxIter--; // assumes message==4 means maximum number of iterations exceeded
        else
          return iitem-item_begin+1; // return number of item where minimization failed
      }
      (*iitem)->SetParameters(xpls);

      double d = MaxRelParamDiff(start, xpls);
      if (maxreldiff < d)
        maxreldiff = d;
    }
    return nMaxIter;
  }

} // namespace etirm

#endif // ETIRM_MSTEPIRT_H_

---