Common functions. More...

#include "libirt.h"
#include <math.h>
#include <gsl/gsl_cdf.h>

Data Structures
struct	pattern_node
	Used in patterns_count to build a triary tree of the unique patterns. More...

Functions
double	logit (double p)
	Compute the logit transformation.
double	logistic (double t)
	Compute the logistic transformation.
void	quadrature (int nbr_quad, double from, double to, gsl_vector quad_points, gsl_vector quad_weights)
	Generate the quadrature classes.
void	patterns_counts (gsl_matrix_int subjects, gsl_vector_int index, gsl_matrix_int patterns, gsl_vector *counts)
	Group the identical patterns from subjects into patterns.
void	likelihood (gsl_matrix_int patterns, gsl_matrix probs, gsl_matrix *like)
	Compute the likelihood of each patterns.
void	likelihood_mc (gsl_matrix_int patterns, gsl_matrix probs, gsl_vector_int nbr_options, gsl_vector_int items_pos, gsl_matrix *like)
	Compute the likelihood of each multiple choice patterns.
void	posteriors (gsl_matrix_int patterns, gsl_matrix probs, gsl_vector quad_weights, gsl_matrix post)
	Compute the posteriori probabilities.
void	posteriors_mc (gsl_matrix_int patterns, gsl_matrix probs, gsl_vector_int nbr_options, gsl_vector_int items_pos, gsl_vector quad_weights, gsl_matrix post)
	Compute the posteriori probabilities for multiple choice patterns.
void	frequencies (gsl_matrix_int patterns, gsl_vector counts, gsl_matrix post, gsl_matrix probs, gsl_vector quad_sizes, gsl_matrix quad_freqs)
	Compute the expected numbers of subjects.
void	adjust_quad_weights (double nbr_subject, gsl_vector quad_sizes, gsl_vector quad_points, gsl_vector *quad_weights)
	Recompute the quadrature weights based on the observations.
int	set_ignore (gsl_matrix_int patterns, gsl_matrix probs, gsl_vector thresholds, gsl_vector_int ignore)
	Check for degenerate items.
int	set_ignore_mc (gsl_matrix_int patterns, gsl_vector_int nbr_options, gsl_vector_int items_pos, gsl_matrix probs, gsl_vector thresholds, gsl_vector_int ignore)
	Check for degenerate multiple choice items.
void	constrain_probs (gsl_matrix *probs, double eps)
	Reset the probabilities to be inside the open interval (0,1).
void	patterns_expand (gsl_matrix_int patterns_mc, gsl_vector_int nbr_options, gsl_matrix_int patterns, gsl_vector_int items_pos)
	Transform a matrix with multiple choice items into a matrix with binary items by creating a new "item"for each option.
void	icc_from_probs (gsl_matrix probs, gsl_matrix probs_stddev, gsl_vector options_weights, gsl_vector_int nbr_options, gsl_vector_int items_pos, gsl_matrix iccs, gsl_matrix *iccs_stddev)
	Compute the items' characteristic curves from the options' characteristic curves.

Variables
const char *	libirt_version = VERSION
	The version of the library.
int	libirt_verbose = 0
	Control the verbosity level.

Detailed Description

Common functions.

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

Function Documentation

double logit ( double p )

Compute the logit transformation.

Returns: The logit of p.

double logistic ( double t )

Compute the logistic transformation.

Returns: The logistic of t.

void quadrature	(	int	nbr_quad,
		double	from,
		double	to,
		gsl_vector *	quad_points,
		gsl_vector *	quad_weights
	)

Generate the quadrature classes.

Parameters

[in]	nbr_quad	The number of classes.
[in]	from	The starting value for the middle points of the classes.
[in]	to	The ending value for the middle points of the classes.
[out]	quad_points	A vector(classes) with the middle points of each class.
[out]	quad_weights	A vector(classes) with the normal weights of each class.

void patterns_counts	(	gsl_matrix_int *	subjects,
		gsl_vector_int **	index,
		gsl_matrix_int **	patterns,
		gsl_vector **	counts
	)

Group the identical patterns from subjects into patterns.

Parameters

[in]	subjects	A matrix(subjects x items) of binary responses.
[out]	patterns	A matrix(patterns x items) with the uniques patterns.
[out]	counts	A vector(patterns) with the count of each pattern.
[out]	index	A vector(subjects) with the new position of each subjects in patterns.

Warning: This function allocate the memory for patterns, counts and index

void likelihood	(	gsl_matrix_int *	patterns,
		gsl_matrix *	probs,
		gsl_matrix *	like
	)

Compute the likelihood of each patterns.

Parameters

[in]	patterns	A matrix (patterns x items) of binary responses.
[in]	probs	A matrix(items x classes) with response functions.
[out]	like	A matrix(patterns x classes) with the likelihood of each pattern in each quadrature class.

Warning: The memory for likel should be allocated before.

void likelihood_mc	(	gsl_matrix_int *	patterns,
		gsl_matrix *	probs,
		gsl_vector_int *	nbr_options,
		gsl_vector_int *	items_pos,
		gsl_matrix *	like
	)

Compute the likelihood of each multiple choice patterns.

Parameters

[in]	patterns	A matrix (patterns x options) of binary responses.
[in]	probs	A matrix(options x classes) with response functions.
[in]	nbr_options	A vector(items) with the number of option of each items.
[in]	items_pos	A vector(items) with the position of the first option of each item in patterns.
[out]	like	A matrix(patterns x classes) with the likelihood of each pattern in each quadrature class.

Warning: The memory for likel should be allocated before.

void posteriors	(	gsl_matrix_int *	patterns,
		gsl_matrix *	probs,
		gsl_vector *	quad_weights,
		gsl_matrix *	post
	)

Compute the posteriori probabilities.

Parameters

[in]	patterns	A matrix (patterns x items) of binary responses.
[in]	probs	A matrix(items x classes) with response functions.
[in]	quad_weights	A vector(classes) with the prior weights of each quadrature class.
[out]	post	A matrix(patterns x classes) with the probability that a pattern is in a quadrature class.

Warning: The memory for post should be allocated before.

void posteriors_mc	(	gsl_matrix_int *	patterns,
		gsl_matrix *	probs,
		gsl_vector_int *	nbr_options,
		gsl_vector_int *	items_pos,
		gsl_vector *	quad_weights,
		gsl_matrix *	post
	)

Compute the posteriori probabilities for multiple choice patterns.

Parameters

[in]	patterns	A matrix (patterns x options) of binary responses.
[in]	probs	A matrix(options x classes) with response functions.
[in]	nbr_options	A vector(items) with the number of option of each items.
[in]	items_pos	A vector(items) with the position of the first option of each item in patterns.
[in]	quad_weights	A vector(classes) with the prior weights of each quadrature class.
[out]	post	A matrix(patterns x classes) with the probability that a pattern is in a quadrature class.

Warning: The memory for post should be allocated before.

void frequencies	(	gsl_matrix_int *	patterns,
		gsl_vector *	counts,
		gsl_matrix *	post,
		gsl_matrix *	probs,
		gsl_vector *	quad_sizes,
		gsl_matrix *	quad_freqs
	)

Compute the expected numbers of subjects.

Parameters

[in]	patterns	A matrix (patterns x items) of binary responses.
[in]	counts	A vector(patterns) with the count of each pattern.
[in]	post	A matrix(patterns x classes) with the probability that a pattern is in a quadrature class.
[in]	probs	A matrix(items x classes) with response functions. Used to replace the missing data.
[out]	quad_sizes	A vector(classes) with the expected number of subjects in the class.
[out]	quad_freqs	A matrix(items x classes) with the expected number of subjects in the class having a success at the item.

Warning: The memory for quad_sizes and quad_freqs should be allocated before.

Todo:: Recomputing the quad_size for each item is unecessary.

void adjust_quad_weights	(	double	nbr_subject,
		gsl_vector *	quad_sizes,
		gsl_vector *	quad_points,
		gsl_vector *	quad_weights
	)

Recompute the quadrature weights based on the observations.

Parameters

[in]	nbr_subject	the number of subjects.
[in]	quad_sizes	A vector(classes) with the expected number of subjects in the class.
[in,out]	quad_points	A vector(classes) with the middle points of each class.
[out]	quad_weights	A vector(classes) with the prior weights of each quadrature class.

Warning: The memory for quad_weights should be allocated before.

int set_ignore	(	gsl_matrix_int *	patterns,
		gsl_matrix *	probs,
		gsl_vector *	thresholds,
		gsl_vector_int *	ignore
	)

Check for degenerate items.

For each items, check if it's almost either all success or all failures, and if so enable the ignore flag and set the prob accordingly.

Parameters

[in]	patterns	A matrix (patterns x items) of binary responses.
[out]	probs	A matrix (items x classes) of response functions.
[out]	thresholds	A vector(items) with the threshold parameters of each item.
[out]	ignore	A vector (items) of flag.

Returns: The number of items to ignore.

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

int set_ignore_mc	(	gsl_matrix_int *	patterns,
		gsl_vector_int *	nbr_options,
		gsl_vector_int *	items_pos,
		gsl_matrix *	probs,
		gsl_vector *	thresholds,
		gsl_vector_int *	ignore
	)

Check for degenerate multiple choice items.

For each items, check if a option is all success, and if so enable the ignore flag and set the prob accordingly.

Parameters

[in]	patterns	A matrix (patterns x options) of binary responses.
[in]	nbr_options	A vector(items) with the number of option of each items.
[in]	items_pos	A vector(items) with the position of the first option of each item in patterns.
[out]	probs	A matrix (options x classes) of option response functions.
[out]	thresholds	A vector(options) with the threshold parameters of each logit.
[out]	ignore	A vector (items) of flag.

Returns: The number of items to ignore.

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

void constrain_probs	(	gsl_matrix *	probs,
		double	eps
	)

Reset the probabilities to be inside the open interval (0,1).

Parameters

[in,out]	probs	A matrix (items x classes) of response functions.
[in]	eps	The minimal distance allowed from 0 or 1.

void patterns_expand	(	gsl_matrix_int *	patterns_mc,
		gsl_vector_int *	nbr_options,
		gsl_matrix_int *	patterns,
		gsl_vector_int *	items_pos
	)

Transform a matrix with multiple choice items into a matrix with binary items by creating a new "item"for each option.

Parameters

[in]	patterns_mc	A matrix(patterns x items) of multiple choice responses.
[in]	nbr_options	A vector(items) with the number of option of each items.
[out]	patterns	A matrix(patterns x options) of binary responses.
[out]	items_pos	A vector(items) with the position of the first option of each item in patterns.

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

void icc_from_probs	(	gsl_matrix *	probs,
		gsl_matrix *	probs_stddev,
		gsl_vector *	options_weights,
		gsl_vector_int *	nbr_options,
		gsl_vector_int *	items_pos,
		gsl_matrix *	iccs,
		gsl_matrix *	iccs_stddev
	)

Compute the items' characteristic curves from the options' characteristic curves.

Parameters

[in]	probs	A matrix (options x classes) of options' characteristic curves.
[in]	probs_stddev	A matrix (options x classes) of occ standard error.
[in]	options_weights	A vector (options) of options' weights.
[in]	nbr_options	A vector(items) with the number of option of each items.
[in]	items_pos	A vector(items) with the position of the first option of each item.
[out]	iccs	A matrix (items+1 x classes) of items' characteristic curves and the test characteristic curve.
[out]	iccs_stddev	A matrix (items+1 x classes) of icc standard error.

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

Variable Documentation

const char* libirt_version = VERSION

The version of the library.

int libirt_verbose = 0

Control the verbosity level.

By default it is 0 (silent).

Data Structures

Functions

Variables

Detailed Description

Function Documentation

Variable Documentation