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

Go to the documentation of this file.

/*! \file ExamineeThetaMLE.h
 
  \brief
  Compute maximum likelihood estimate of latent variable (theta)
  for an 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_EXAMINEETHETAMLE_H_
#define ETIRM_EXAMINEETHETAMLE_H_

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

// Function ExamineeThetaMLE uses Fmin univariate minimization
// function which is part of the Uncmin++ package
// (http://www.smallwaters.com/software/cpp/uncmin.html).
#include "Fmin.h"

namespace etirm
{
  /*! 
    \brief
   Compute latent variable estimate for an examinee using 
   maximum likelihood. Returns the latent trait estimate for the examinee.
   
   \section template_args Template Parameter
   
     \param L Function type returning minus the loglihood. An object of this
     type is passed to minimization procedure.
   
   \section function_args Function Parameters

     \param [in]  minTheta  Minimum value of theta estimate
     \param [in]  maxTheta  Maximum value of theta estimate 
     \param [in]  precision Length of interval in which MLE is determined to lie.
       This should be greater than, roughly, 3.0e-8.
     \param [in]  likelihood  The function to minimize (minus the loglikelihood).
   */
  template<class L> Real ExamineeThetaMLE(Real minTheta, Real maxTheta, Real precision,
      L &likelihood)
  {
    Real midTheta = (minTheta + maxTheta) / 2.0;

    // See if middle value is bracketed
    Real fmin = likelihood(minTheta);
    Real fmid = likelihood(midTheta);
    Real fmax = likelihood(maxTheta);

    Real theta;

    // Compute minimum on two intervals and take the one corresponding to the largest
    // likelihood. This reduces the chances of a local minimum being identified by Fmin when the
    // function is multimodal and is not bracketed.
    fmin = Fmin(minTheta, midTheta, likelihood, precision);
    fmax = Fmin(midTheta, maxTheta, likelihood, precision);
    
    theta = (likelihood(fmin) < likelihood(fmax)) ? fmin : fmax;
    return theta;
  }

  /*! 
    \brief
    Compute latent variable estimate for an examinee using 
    maximum likelihood, create a ThetaLogLikelihood object 
    from two item iterators and an interator to the examinee 
    responses, and return the latent trait estimate for the examinee.
      
    \section template_args Template Parameters
   
    \param  II Iterator type over pointers to item objects.
    \param  IR Iterator type over examinee responses to items.

    \section function_args Function Parameters

    \param[in] minTheta Minimum value of theta estimate
    \param[in]  maxTheta  Maximum value of theta estimate 
    \param[in]  precision Length of interval in which MLE is determined to lie.
            This should be greater than, roughly, 3.0e-8.
    \param[in] items_begin  Iterator pointing to first item object pointer.
    \param[in]  items_end Iterator pointing to one past the last item object pointer.
    \param[in]  responses_begin Iterator pointing to examinee's response to first item.
 


   */
  template<class II, class IR> Real ExamineeThetaMLE(Real minTheta, Real maxTheta, Real precision,
      II items_begin, II items_end, IR responses_begin)
  {
    // Last argument being true indicates the function object
    // should return the negative of the likelihood since
    // the function will be minimized, not maximized.
    ThetaLogLikelihood<II,IR> likelihood(items_begin, items_end, responses_begin, true);

    return ExamineeThetaMLE(minTheta, maxTheta, precision, likelihood);

  }

} // namespace etirm

#endif // ETIRM_EXAMINEETHETAMLE_H_

---