pmmle_wave.c File Reference

Functions to estimate the 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_struct
	Used to passed extra parameter to mple_wave_fdfdf2. More...

Functions
int	mple_wave_fdfdf2 (const gsl_vector *par_wave, void *params, double *f, gsl_vector *df, gsl_matrix *df2)
	Compute the log likelihood, gradient and Hessian of the wavelet coefficients.
int	mple_wave_fdf (const gsl_vector *par_wave, void *params, double *f, gsl_vector *df)
	Compute the log likelihood and gradient of the wavelet coefficients.
int	mple_wave_dfdf2 (const gsl_vector *par_wave, void *params, gsl_vector *df, gsl_matrix *df2)
	Compute the log likelihood gradient and Hessian of the wavelet coefficients.
double	mple_wave_f (const gsl_vector *par_wave, void *params)
	Compute the log likelihood of the wavelet coefficients.
int	mple_wave_df (const gsl_vector *par_wave, void *params, gsl_vector *df)
	Compute the log likelihood gradient of the wavelet coefficients.
int	mple_wave_df2 (const gsl_vector *par_wave, void *params, gsl_matrix *df2)
	Compute the log likelihood Hessian of the wavelet coefficients.
int	mple_wave (int max_iter, double prec, double smooth_factor, gsl_matrix *quad_freqs, gsl_vector *quad_sizes, mple_wave_struct *params, gsl_matrix *probs, gsl_matrix *probs_stddev, gsl_vector_int *ignore, gsl_vector_int *notconverge, double *tot_pml)
	Does the maximization step of the EM algorithm to estimate the response functions by PMMLE (Penalized Maximum Marginal Likelihood).
int	em_mple_wave (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_matrix *probs, gsl_matrix *probs_stddev, gsl_vector_int *ignore, int *nbr_notconverge, gsl_vector_int *notconverge, int adjust_weights)
	Estimate the response functions by PMMLE (Penalized Maximum Marginal Likelihood).

Detailed Description

Functions to estimate the 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

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

Compute the log likelihood, 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]	f	The log likelihood.
[out]	df	The gradient of the log likelihood.
[out]	df2	The Hessian of the 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_fdf	(	const gsl_vector *	par_wave,
		void *	params,
		double *	f,
		gsl_vector *	df
	)

Compute the log likelihood and gradient of the wavelet coefficients.

Parameters

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

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

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

Compute the log likelihood 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 log likelihood.
[out]	df2	The Hessian of the 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.

double mple_wave_f	(	const gsl_vector *	par_wave,
		void *	params
	)

Compute the log likelihood of the wavelet coefficients.

Parameters

[in]	par_wave	The wavelet coefficients.
[in]	params	The extra parameter to passes to the function.

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

Returns

The log likelihood.

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

Compute the log likelihood 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 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_df2	(	const gsl_vector *	par_wave,
		void *	params,
		gsl_matrix *	df2
	)

Compute the log likelihood 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 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	(	int	max_iter,
		double	prec,
		double	smooth_factor,
		gsl_matrix *	quad_freqs,
		gsl_vector *	quad_sizes,
		mple_wave_struct *	params,
		gsl_matrix *	probs,
		gsl_matrix *	probs_stddev,
		gsl_vector_int *	ignore,
		gsl_vector_int *	notconverge,
		double *	tot_pml
	)

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

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]	smooth_factor	The factor to the penality term.
[in]	quad_freqs	A matrix(items x classes) with the expected number of subjects in the class having a success at the item.
[in]	quad_sizes	A vector (classes) with the expected number of subjects in the class.
[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.
[in]	ignore	A vector(items) with a flag of 1 if the item should be ignore.
[out]	notconverge	A vector(items) of flag set for the items that didn't converged.
[out]	tot_pml	The vaulue of the PML.

Returns

The number of item that did not converged.

Warning

The memory for the response functions should be allocated before.

int em_mple_wave	(	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_matrix *	probs,
		gsl_matrix *	probs_stddev,
		gsl_vector_int *	ignore,
		int *	nbr_notconverge,
		gsl_vector_int *	notconverge,
		int	adjust_weights
	)

Estimate the 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 items) 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,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.
[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

The number of item that did not converged at the last EM iteration.

Warning

The memory for the response functions should be allocated before.

Todo:

Compute more accurates wavelets derivatives