ETIRM: etirm::ItemDichotomous< D, ICC > Class Template Reference

template<class D, class ICC>

etirm::ItemDichotomous< D, ICC >::ItemDichotomous	(	int	index,
		ICC &	icc,
		D *	dist
	)			`[inline]`

Class constructor.

Template Parameters

Parameters:

	D	Class for discrete latent variable distribution.
	ICC	Type containing functions defining the item characteristic curve (ICC) and derivatives of the ICC.

Function Parameters

Parameters:

	index	Zero-offset index of the item in the vector of all item responses.
	icc	Item characteristic curve for the model.
	dist	Object containing information about the number of latent variable points used in calculating the n and r.

The first response category is assumed to correspond to an incorrect response and the second response category is assumed to correspond to a correct response.

Template Parameters

Parameters:

	D	Class for discrete latent variable distribution.
	ICC	Type containing functions defining the item characteristic curve (ICC) and derivatives of the ICC.

Function Parameters

Parameters:

`[in]`	index	Zero-offset index of the item in the vector of all item responses.
`[in]`	icc	Item characteristic curve for the model.
`[in]`	dist	Object containing information about the number of latent variable points used in calculating the n and r.

Definition at line 238 of file ItemDichotomous.h.

00239                :
00240     ItemNR<D>(icc.NumParameters(), index, 2, dist), mICC(icc),
00241         mCorrectResponse(ItemNR<D>::mFirstResponse+1) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00242   {
00243 
00244   }

template<class D, class ICC>

etirm::ItemDichotomous< D, ICC >::~ItemDichotomous ( ) [inline, virtual]

Class destructor.

Definition at line 246 of file ItemDichotomous.h.

00247   {
00248   }

template<class D, class ICC>

virtual RealVector etirm::ItemDichotomous< D, ICC >::GetAllParameters ( ) const [inline, virtual]

Returns a vector of estimated and fixed parameters.

The order of the parameters in the vector is determined by the GetAllParameters member function of mICC.

Reimplemented from etirm::Item< D::latentvar_type >.

Definition at line 96 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00097     {
00098       RealVector allParam(mICC.NumAllParameters());
00099       mICC.GetAllParameters(ItemNR<D>::mParameterEstimates, allParam); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00100       return allParam;
00101     }

template<class D, class ICC>

virtual void etirm::ItemDichotomous< D, ICC >::SetAllParameters ( const RealVector & allParam ) [inline, virtual]

Assigns values of fixed and estimated parameters.

Function Parameters

Parameters:

[in] &allParam Address of vector containing all parameters of the item.

Reimplemented from etirm::Item< D::latentvar_type >.

Definition at line 111 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00112     {
00113       mICC.SetAllParameters(allParam.begin(), allParam.end(), ItemNR<D>::mParameterEstimates);
00114     } // Added "ItemNR<D>::" reference. ww, 1/12/2008.

template<class D, class ICC>

Real etirm::ItemDichotomous< D, ICC >::ICRF	(	Response	r,
		const RealVector &	parameters,
		const Real &	theta
	)			const `[inline, virtual]`

Returns probablity of response "r".

Function Parameters

Parameters:

`[in]`	r	Item response.
`[in]`	&parameters	Address of item parameter vector.
`[in]`	theta	Latent ability theta value.

Definition at line 250 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse, and etirm::ItemDichotomous< D, ICC >::mICC.

00252   {
00253     return (r == mCorrectResponse) ? mICC.ICC(parameters, theta) : (1.0 - mICC.ICC(parameters,
00254         theta));
00255   }

template<class D, class ICC>

virtual Real etirm::ItemDichotomous< D, ICC >::NormalizingConstant ( ) const [inline, virtual]

TODO: Document NormalizingConstant.

Reimplemented from etirm::Item< D::latentvar_type >.

Definition at line 129 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00130     {
00131       return mICC.GetD();
00132     }

template<class D, class ICC>

int etirm::ItemDichotomous< D, ICC >::ScaleParameters	(	Real	slope,
		Real	intercept,
		bool	ignorePriors = `false`
	)			`[inline, virtual]`

Transforms the parameter estimates to new latent variable scale.

Returns 1 if scaling results in invalid parameters. In this case parameters are not modified.

Function Parameters

Parameters:

`[in]`	slope	Slope parameter of linear scale transformation.
`[in]`	intercept	Intercept parameter of linear scale transformation.
`[in]`	ignorePriors	If TRUE, do not check if tranformed parameters fall outside the prior regions.

Implements etirm::Item< D::latentvar_type >.

Definition at line 514 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC, and etirm::ItemDichotomous< D, ICC >::ValidParameters().

00516   {
00517     RealVector scaledParam(ItemNR<D>::mParameterEstimates); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00518 
00519     mICC.Scale(slope, intercept, scaledParam);
00520 
00521     // Check if scaled parameters are valid
00522     if (!(ValidParameters(scaledParam, ignorePriors)))
00523       return 1;
00524 
00525     ItemNR<D>::mParameterEstimates = scaledParam;
00526 
00527     return 0;
00528   }

Here is the call graph for this function:

template<class D, class ICC>

virtual std::string etirm::ItemDichotomous< D, ICC >::ModelName ( ) const [inline, virtual]

Returns string containing name of model used for item.

Implements etirm::Item< D::latentvar_type >.

Definition at line 137 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00138     {
00139       return mICC.Name();
00140     }

template<class D, class ICC>

virtual IRTModel etirm::ItemDichotomous< D, ICC >::Model ( ) const [inline, virtual]

Returns type of model used for item.

Implements etirm::Item< D::latentvar_type >.

Definition at line 143 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00144     {
00145       return mICC.Model();
00146     }

template<class D, class ICC>

virtual void etirm::ItemDichotomous< D, ICC >::SetFirstResponse ( Response r ) [inline, virtual]

Assigns values of both mFirstResponse and mCorrectResponse.

Function Parameters

Parameters:

[in] r Code of incorrect item score. (r+1) is assumed to be the correct item score.

Reimplemented from etirm::Item< D::latentvar_type >.

Definition at line 156 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse.

00157     {
00158       ItemNR<D>::mFirstResponse = r;
00159       mCorrectResponse = r+1;
00160     } // Added "ItemNR<D>::" reference. ww, 1/12/2008.

template<class D, class ICC>

virtual Response etirm::ItemDichotomous< D, ICC >::CorrectResponse ( ) [inline, virtual]

Returns the correct response category.

For dichotomous items, the response to the second response category is considered correct.

Reimplemented from etirm::Item< D::latentvar_type >.

Definition at line 169 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse.

00170     {
00171       return mCorrectResponse;
00172     }

template<class D, class ICC>

Response etirm::ItemDichotomous< D, ICC >::IncorrectResponse ( ) [inline]

Returns the incorrect response category.

For dichotomous items, the response to the first response category is considered incorrect.

Definition at line 181 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse.

00182     {
00183       return mCorrectResponse-1;
00184     }

template<class D, class ICC>

double etirm::ItemDichotomous< D, ICC >::f_to_minimize ( RealVector & param ) [inline, virtual]

Function to maximize in M-step.

Template Parameters

Parameters:

	D	Class for discrete latent variable distribution.
	ICC	Type containing functions defining the item characteristic curve (ICC) and derivatives of the ICC.

Function Parameters

Parameters:

[in] &param Address of item parameter vector.

Note: Technically, the negative value of the function is to be minimized by UNCMIN++, see inline comments in function code.

Implements etirm::ItemNR< D >.

Definition at line 274 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse, and etirm::ItemDichotomous< D, ICC >::mICC.

00275   {
00276     Real value = 0.0;
00277     int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00278 
00279     /* Compute loglikelihood */
00280     for (int grp=1; grp<=ngroups; ++grp)
00281     {
00282       typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00283       typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00284       typename ItemNR<D>::point_iterator it = ItemNR<D>::mLatentDist->begin_points(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00285       for (int i = ItemNR<D>::mNumLatentVarCat; i--; ++in, ++ir, ++it) // Added "ItemNR<D>::" references. ww, 1/12/2008.
00286       {
00287         Real prob = mICC.OpenICC(param, *it);
00288 
00289         Real t = std::log(prob) * *ir;
00290         t += (*in - *ir) * std::log((1.0 - prob));
00291         value += t;
00292       }
00293     }
00294 
00295     /* Add priors */
00296     PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00297     RealVector::iterator iparam = param.begin();
00298     for (int j = ItemNR<D>::NumParameters(); j--; ++iprior, ++iparam) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00299     {
00300       if (*iprior)
00301       {
00302         if ((*iprior)->ZeroDensity(*iparam))
00303         {
00304           // If the prior density is zero then the log of prior density is
00305           // minus infinity (negative of minus infinity is returned
00306           // because the function is being minimized)
00307           if (std::numeric_limits<Real>::has_infinity)
00308           {
00309             return std::numeric_limits<Real>::infinity();
00310           }
00311           else
00312           {
00313             return std::numeric_limits<Real>::max();
00314           }
00315         }
00316         else
00317         {
00318           value += (*iprior)->LogDensity(*iparam);
00319         }
00320       }
00321     }
00322 
00323     return -value; // return negative value to find minimum rather than maximum
00324   }

template<class D, class ICC>

void etirm::ItemDichotomous< D, ICC >::gradient	(	RealVector &	param,
		RealVector &	g
	)			`[inline, virtual]`

Gradient of function to maximize in M-step.

Template Parameters

Parameters:

	D	Class for discrete latent variable distribution.
	ICC	Type containing functions defining the item characteristic curve (ICC) and derivatives of the ICC.

Function Parameters

Parameters:

`[in]`	&param	Address of item parameter vector.
`[out]`	&g	Address of gradient with respect to item parameters.

Note: Technically, the negative value of the function is to be minimized by UNCMIN++, see inline comments in function code.

Implements etirm::ItemNR< D >.

Definition at line 344 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse, and etirm::ItemDichotomous< D, ICC >::mICC.

00346   {
00347     g = 0.0;
00348     RealVector deriv(ItemNR<D>::NumParameters()); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00349     int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00350 
00351     int i;
00352 
00353     for (int grp=1; grp<=ngroups; ++grp)
00354     {
00355       typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00356       typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00357       typename ItemNR<D>::point_iterator itheta = ItemNR<D>::mLatentDist->begin_points(grp); // Added typename and "ItemNR<D>::" references. ww, 1/12/2008.
00358       for (i = ItemNR<D>::mNumLatentVarCat; i--; ++in, ++ir, ++itheta) // Added "ItemNR<D>::" references. ww, 1/12/2008.
00359       {
00360         Real prob = mICC.OpenICC(param, *itheta);
00361 
00362         Real t = *ir - *in * prob;
00363         t /= (1.0 - prob) * prob;
00364 
00365         mICC.ICCDeriv1(param, *itheta, deriv);
00366 
00367         // use -t since function is to be minimized, not maximized
00368         deriv *= -t;
00369         g += deriv;
00370 
00371       }
00372     }
00373 
00374     /* Add priors */
00375     PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" references. ww, 1/12/2008.
00376     RealVector::iterator iparam = param.begin();
00377     RealVector::iterator ig = g.begin();
00378     for (int j = ItemNR<D>::NumParameters(); j--; ++iprior, ++iparam, ++ig) // Added "ItemNR<D>::" references. ww, 1/12/2008.
00379     {
00380       // subtract because function is to be minimized
00381       if (*iprior)
00382         *ig -= (*iprior)->DerivLogDensity1(*iparam);
00383     }
00384 
00385   }

template<class D, class ICC>

void etirm::ItemDichotomous< D, ICC >::hessian	(	RealVector &	param,
		RealMatrix &	h
	)			`[inline, virtual]`

Hessian of function to maximize in M-step.

Template Parameters

Parameters:

	D	Class for discrete latent variable distribution.
	ICC	Type containing functions defining the item characteristic curve (ICC) and derivatives of the ICC.

Function Parameters

Parameters:

`[in]`	&param	Address of item parameter vector.
`[out]`	&h	Address of hessian with respect to item parameters.

Note: Technically, the negative value of the function is to be minimized by UNCMIN++, see inline comments in function code.

Note: The hessian is stored in the lower trangle of h.

Implements etirm::ItemNR< D >.

Definition at line 407 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mCorrectResponse, and etirm::ItemDichotomous< D, ICC >::mICC.

00409   {
00410     int numParameters = ItemNR<D>::NumParameters(); // Added "ItemNR<D>::" references. ww, 1/12/2008.
00411 
00412     RealMatrix deriv2(numParameters, numParameters);
00413     RealVector deriv1(numParameters);
00414 
00415     RealMatrix::diag_iterator hdiag, ddiag;
00416     int i, j, k;
00417     int ngroups = ItemNR<D>::mLatentDist->NumGroupsUnique(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00418 
00419     // Initialize lower triangle of h to zero
00420     for (i=0; i<numParameters; ++i)
00421     {
00422       hdiag = h.begin_diagonal(i+1, 1);
00423       for (j=numParameters-i; j--; ++hdiag)
00424       {
00425         *hdiag = 0.0;
00426       }
00427     }
00428 
00429     for (int grp=1; grp<=ngroups; ++grp)
00430     {
00431       typename ItemNR<D>::n_iterator in = ItemNR<D>::NVector(grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
00432       typename ItemNR<D>::r_iterator ir = ItemNR<D>::RVector(mCorrectResponse, grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
00433       typename ItemNR<D>::point_iterator itheta = ItemNR<D>::mLatentDist->begin_points(grp); // Added "typename" and "ItemNR<D>::" references. ww, 1/12/2008.
00434       for (k = ItemNR<D>::mNumLatentVarCat; k--; ++in, ++ir, ++itheta) // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00435       {
00436         Real prob = mICC.OpenICC(param, *itheta);
00437         Real t1 = -*in * prob * prob;
00438         t1 += 2.0 * *ir * prob;
00439         t1 -= *ir;
00440         Real t2 = *ir - *in * prob;
00441         Real t = prob * (1.0 - prob);
00442         t1 /= t * t;
00443         t2 /= t;
00444 
00445         mICC.ICCDeriv1(param, *itheta, deriv1);
00446         mICC.ICCDeriv2(param, *itheta, deriv2);
00447 
00448         for (int i=0; i<numParameters; ++i)
00449         {
00450           hdiag = h.begin_diagonal(i+1, 1);
00451           ddiag = deriv2.begin_diagonal(i+1, 1);
00452           RealVector::iterator prow = deriv1.begin() + i;
00453           RealVector::iterator pcol = deriv1.begin();
00454           for (j=numParameters-i; j--; ++prow, ++pcol, ++hdiag, ++ddiag)
00455           {
00456             // subtract rather than add since function is to be minimized
00457             *hdiag -= t1 * *prow * *pcol;
00458             *hdiag -= t2 * *ddiag;
00459           }
00460         }
00461       }
00462     }
00463 
00464     /* Add second derivatives of priors to diagonal elements of hessian */
00465     PriorVector::const_iterator iprior = ItemNR<D>::mPriors.begin(); // Added "ItemNR<D>::" reference. ww, 1/12/2008.
00466     RealVector::iterator iparam = param.begin();
00467     hdiag = h.begin_diagonal(1, 1);
00468     for (i = numParameters; i--; ++iparam, ++iprior, ++hdiag)
00469     {
00470       // subtract because function is to be minimized
00471       if (*iprior)
00472         *hdiag -= (*iprior)->DerivLogDensity2(*iparam);
00473     }
00474 
00475   }

template<class D, class ICC>

int etirm::ItemDichotomous< D, ICC >::HasAnalyticGradient ( ) const [inline, virtual]

Indicates that the analytic gradient is available.

Implements etirm::ItemNR< D >.

Definition at line 478 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00479   {
00480     return mICC.GradientDefined();
00481   }

template<class D, class ICC>

int etirm::ItemDichotomous< D, ICC >::HasAnalyticHessian ( ) const [inline, virtual]

Indicates that the analytic hessian is available.

Implements etirm::ItemNR< D >.

Definition at line 484 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

00485   {
00486     return mICC.HessianDefined();
00487   }

template<class D, class ICC>

int etirm::ItemDichotomous< D, ICC >::ValidParameters	(	const RealVector &	p,
		bool	ignorePriors = `false`
	)			const `[inline, virtual]`

Indicates that the parameter vector creates a valid function value.

Reimplemented from etirm::ItemNR< D >.

Definition at line 490 of file ItemDichotomous.h.

References etirm::ItemDichotomous< D, ICC >::mICC.

Referenced by etirm::ItemDichotomous< D, ICC >::ScaleParameters().

00492   {
00493     if (!(mICC.ValidParameters(param)))
00494       return 0;
00495 
00496     return ItemNR<D>::ValidParameters(param, ignorePriors);
00497   }

Here is the caller graph for this function:

template<class D, class ICC>

ICC etirm::ItemDichotomous< D, ICC >::mICC [protected]

Object for calculating ICC and its derivatives.

Definition at line 204 of file ItemDichotomous.h.

template<class D, class ICC>

Response etirm::ItemDichotomous< D, ICC >::mCorrectResponse [protected]

The response associated with the correct answer.

Stored as a data member to avoid overhead of falling CorrectResponse() for member functions.

Definition at line 213 of file ItemDichotomous.h.

Referenced by etirm::ItemDichotomous< D, ICC >::CorrectResponse(), etirm::ItemDichotomous< D, ICC >::f_to_minimize(), etirm::ItemDichotomous< D, ICC >::gradient(), etirm::ItemDichotomous< D, ICC >::hessian(), etirm::ItemDichotomous< D, ICC >::ICRF(), etirm::ItemDichotomous< D, ICC >::IncorrectResponse(), and etirm::ItemDichotomous< D, ICC >::SetFirstResponse().

etirm::ItemDichotomous< D, ICC > Class Template Reference

Public Member Functions

Protected Attributes

Detailed Description

template<class D, class ICC>
class etirm::ItemDichotomous< D, ICC >

Template Parameters

Constructor & Destructor Documentation

Template Parameters

Function Parameters

Template Parameters

Function Parameters

Member Function Documentation

Function Parameters

Function Parameters

Function Parameters

Function Parameters

Template Parameters

Function Parameters

Template Parameters

Function Parameters

Template Parameters

Function Parameters

Member Data Documentation


Public Member Functions
	ItemDichotomous (int index, ICC &icc, D *dist)
	Class constructor.
virtual	~ItemDichotomous ()
	Class destructor.
virtual RealVector	GetAllParameters () const
	Returns a vector of estimated and fixed parameters.
virtual void	SetAllParameters (const RealVector &allParam)
	Assigns values of fixed and estimated parameters.
virtual Real	ICRF (Response r, const RealVector &parameters, const Real &theta) const
	Returns probablity of response "r".
virtual Real	NormalizingConstant () const
	TODO: Document NormalizingConstant.
virtual int	ScaleParameters (Real slope, Real intercept, bool ignorePrior=false)
	Transforms the parameter estimates to new latent variable scale.
virtual std::string	ModelName () const
	Returns string containing name of model used for item.
virtual IRTModel	Model () const
	Returns type of model used for item.
virtual void	SetFirstResponse (Response r)
	Assigns values of both mFirstResponse and mCorrectResponse.
virtual Response	CorrectResponse ()
	Returns the correct response category.
Response	IncorrectResponse ()
	Returns the incorrect response category.
virtual double	f_to_minimize (RealVector &p)
	Function to maximize in M-step.
virtual void	gradient (RealVector &p, RealVector &g)
	Gradient of function to maximize in M-step.
virtual void	hessian (RealVector &x, RealMatrix &h)
	Hessian of function to maximize in M-step.
virtual int	HasAnalyticGradient () const
	Indicates that the analytic gradient is available.
virtual int	HasAnalyticHessian () const
	Indicates that the analytic hessian is available.
virtual int	ValidParameters (const RealVector &p, bool ignorePriors=false) const
	Indicates that the parameter vector creates a valid function value.
Protected Attributes
ICC	mICC
	Object for calculating ICC and its derivatives.
Response	mCorrectResponse
	The response associated with the correct answer.

etirm::ItemDichotomous< D, ICC > Class Template Reference

Public Member Functions

Protected Attributes

Detailed Description

template<class D, class ICC> class etirm::ItemDichotomous< D, ICC >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class D, class ICC>
class etirm::ItemDichotomous< D, ICC >