Functions to estimate the multiple choice item parameters by PMMLE (Penalized Maximal Marginal Likelihood). More...

#include "libirt.h"
#include <stdio.h>
#include <math.h>
#include <gsl/gsl_errno.h>
#include <gsl/gsl_multiroots.h>
#include <gsl/gsl_linalg.h>
#include <gsl/gsl_wavelet.h>

Data Structures
struct	mple_wave_mc_struct
	Used to passed extra parameter to mple_wave_mc_fdfdf2. More...

Functions
void	probs_from_logits (gsl_matrix logits, gsl_matrix probs)
	Compute the options characteristic curves from the logits.
void	logits_from_probs (gsl_matrix probs, gsl_matrix logits)
	Compute the logit from the options characteristic curves.
int	mple_wave_mc_fdfdf2 (const gsl_vector par_wave, void params, double f, gsl_vector df, gsl_matrix *df2)
	Compute the gradient and Hessian of the wavelet coefficients.
int	mple_wave_mc_dfdf2 (const gsl_vector par_wave, void params, gsl_vector df, gsl_matrix df2)
	Compute the gradient and Hessian of the wavelet coefficients.
int	mple_wave_mc_df (const gsl_vector par_wave, void params, gsl_vector *df)
	Compute the gradient of the wavelet coefficients.
int	mple_wave_mc_df2 (const gsl_vector par_wave, void params, gsl_matrix *df2)
	Compute the Hessian of the wavelet coefficients.
int	mple_wave_mc (int max_iter, double prec, mple_wave_mc_struct params, gsl_matrix probs, gsl_matrix probs_stddev, double mllk)
	Does the maximization step of the EM algorithm to estimate the response functions by PMMLE (Penalized Maximum Marginal Likelihood) of one multiple choice item.
int	em_mple_wave_mc (int max_em_iter, int max_nr_iter, double prec, double smooth_factor, gsl_matrix_int patterns, gsl_vector counts, gsl_vector quad_points, gsl_vector quad_weights, gsl_vector_int items_pos, gsl_vector_int nbr_options, gsl_matrix probs, gsl_matrix probs_stddev, gsl_vector_int ignore, int nbr_notconverge, gsl_vector_int *notconverge, int adjust_weights)
	Estimate the options response functions by PMMLE (Penalized Maximum Marginal Likelihood).

Detailed Description

Functions to estimate the multiple choice item parameters by PMMLE (Penalized Maximal Marginal Likelihood).

The functional estimations are done by a wavelet decomposition, and then by using a root finding algorithm on the wavelet coefficients.

Author: Stephane Germain germs.nosp@m.te@g.nosp@m.mail..nosp@m.com

Function Documentation

void probs_from_logits	(	gsl_matrix *	logits,
		gsl_matrix *	probs
	)

Compute the options characteristic curves from the logits.

Parameters

[in]	logits	A matrix(logits x classes).
[out]	probs	A matrix(options x classes).

void logits_from_probs	(	gsl_matrix *	probs,
		gsl_matrix *	logits
	)

Compute the logit from the options characteristic curves.

Parameters

[in]	probs	A matrix(options x classes).
[out]	logits	A matrix(logits x classes).

int mple_wave_mc_fdfdf2	(	const gsl_vector *	par_wave,
		void *	params,
		double *	f,
		gsl_vector *	df,
		gsl_matrix *	df2
	)

Compute the gradient and Hessian of the wavelet coefficients.

Parameters

[in]	par_wave	The wavelet coefficients.
[in]	params	The extra parameter to passes to the function.
[out]	df	The gradient of the penalized log likelihood.
[out]	df2	The Hessian of the penalized log likelihood.

This function is not used directly by the root finding functions, but by others functions that comply with the gsl.

Returns: GSL_SUCCESS for success.

int mple_wave_mc_dfdf2	(	const gsl_vector *	par_wave,
		void *	params,
		gsl_vector *	df,
		gsl_matrix *	df2
	)

Compute the gradient and Hessian of the wavelet coefficients.

Parameters

[in]	par_wave	The wavelet coefficients.
[in]	params	The extra parameter to passes to the function.
[out]	df	The gradient of the penalized log likelihood.
[out]	df2	The Hessian of the penalized log likelihood.

This function is just a wrapper around mple_wavefdfdf2 to be used by the root finding functions in the gsl.

Returns: GSL_SUCCESS for success.

int mple_wave_mc_df	(	const gsl_vector *	par_wave,
		void *	params,
		gsl_vector *	df
	)

Compute the gradient of the wavelet coefficients.

Parameters

[in]	par_wave	The wavelet coefficients.
[in]	params	The extra parameter to passes to the function.
[out]	df	The gradient of the penalized log likelihood.

This function is just a wrapper around mple_wavefdfdf2 to be used by the root finding functions in the gsl.

Returns: GSL_SUCCESS for success.

int mple_wave_mc_df2	(	const gsl_vector *	par_wave,
		void *	params,
		gsl_matrix *	df2
	)

Compute the Hessian of the wavelet coefficients.

Parameters

[in]	par_wave	The wavelet coefficients.
[in]	params	The extra parameter to passes to the function.
[out]	df2	The Hessian of the penalized log likelihood.

This function is just a wrapper around mple_wavefdfdf2 to be used by the root finding functions in the gsl.

Returns: GSL_SUCCESS for success.

int mple_wave_mc	(	int	max_iter,
		double	prec,
		mple_wave_mc_struct *	params,
		gsl_matrix *	probs,
		gsl_matrix *	probs_stddev,
		double *	mllk
	)

Does the maximization step of the EM algorithm to estimate the response functions by PMMLE (Penalized Maximum Marginal Likelihood) of one multiple choice item.

Parameters

[in]	max_iter	The maximum number of Newton iterations performed for each item.
[in]	prec	The desired precision of each wavelet parameter estimate.
[in]	params	The extra parameter to passes to the function.
[in,out]	probs	A matrix(items x classes) with the estimated response functions. They should be initialize first.
[out]	probs_stddev	matrix(items x classes) with the standard error of the logit response functions.
[out]	mllk	The maximum log likelihood.

Returns: 1 if the item converge, 0 otherwise.

Warning: The memory for the response functions should be allocated before.

int em_mple_wave_mc	(	int	max_em_iter,
		int	max_nr_iter,
		double	prec,
		double	smooth_factor,
		gsl_matrix_int *	patterns,
		gsl_vector *	counts,
		gsl_vector *	quad_points,
		gsl_vector *	quad_weights,
		gsl_vector_int *	items_pos,
		gsl_vector_int *	nbr_options,
		gsl_matrix *	probs,
		gsl_matrix *	probs_stddev,
		gsl_vector_int *	ignore,
		int *	nbr_notconverge,
		gsl_vector_int *	notconverge,
		int	adjust_weights
	)

Estimate the options response functions by PMMLE (Penalized Maximum Marginal Likelihood).

Parameters

[in]	max_em_iter	The maximum number of EM iterations. At least 20 iteration are made.
[in]	max_nr_iter	The maximum number of Newton iterations performed for each item at each EM iteration.
[in]	prec	The relative change in the likelihood to stop the EM algorithm. This value divided by 10 is also the desired precision of each parameter estimate.
[in]	smooth_factor	The factor to the penality term.
[in]	patterns	A matrix(patterns x options) of binary responses.
[in]	counts	A vector(patterns) with the count of each pattern. If NULL the counts are assumed to be all 1.
[in]	quad_points	A vector(classes) with the middle points of each quadrature class.
[in]	quad_weights	A vector(classes) with the prior weights of each quadrature class.
[in]	items_pos	A vector(items) with the position of the first option of each item in patterns (and probs).
[in]	nbr_options	A vector(items) with the number of option of each item in patterns (and probs).
[in,out]	probs	A matrix(options x classes) with the estimated response functions. They should be initialize first.
[out]	probs_stddev	matrix(items x classes) with the standard error of the logit response functions.
[in]	ignore	A vector(items) of ignore flag.
[out]	nbr_notconverge	The number of items that didn't converged.
[out]	notconverge	A vector(items) of flag set for the items that didn't converged.
[in]	adjust_weights	Controls whether adjust the quadrature weights after each iteration.

Returns: 1 if the relative change in the maximum log likelihood was less than prec else 0.

Warning: The memory for the outputs should be allocated before.

Todo:: Compute more accurates wavelets derivatives

Data Structures

Functions

Detailed Description

Function Documentation