OscatsModel

OscatsModel — Abstract Measurement Model Class

Synopsis

#define             OSCATS_DEFAULT_KEY
typedef             OscatsResponse;
#define             OSCATS_MAX_RESPONSE
struct              OscatsModel;
struct              OscatsModelClass;
OscatsModel *       oscats_model_new                    (GType type,
                                                         OscatsSpace *space,
                                                         const OscatsDim *dims,
                                                         OscatsDim ndims,
                                                         OscatsCovariates *covariates);
OscatsResponse      oscats_model_get_max                (const OscatsModel *model);
gdouble             oscats_model_P                      (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates);
gdouble             oscats_model_distance               (const OscatsModel *model,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates);
void                oscats_model_logLik_dtheta          (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslVector *grad,
                                                         GGslMatrix *hes);
void                oscats_model_logLik_dparam          (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslVector *grad,
                                                         GGslMatrix *hes);
void                oscats_model_fisher_inf             (const OscatsModel *model,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslMatrix *I);
const gchar *       oscats_model_get_param_name         (const OscatsModel *model,
                                                         guint index);
gboolean            oscats_model_has_param_name         (const OscatsModel *model,
                                                         const gchar *name);
gboolean            oscats_model_has_param              (const OscatsModel *model,
                                                         GQuark name);
gdouble             oscats_model_get_param              (const OscatsModel *model,
                                                         GQuark name);
gdouble             oscats_model_get_param_by_index     (const OscatsModel *model,
                                                         guint index);
gdouble             oscats_model_get_param_by_name      (const OscatsModel *model,
                                                         const gchar *name);
void                oscats_model_set_param              (OscatsModel *model,
                                                         GQuark name,
                                                         gdouble value);
void                oscats_model_set_param_by_index     (OscatsModel *model,
                                                         guint index,
                                                         gdouble value);
void                oscats_model_set_param_by_name      (OscatsModel *model,
                                                         const gchar *name,
                                                         gdouble value);
gboolean            oscats_model_has_covariate          (const OscatsModel *model,
                                                         GQuark name);
gboolean            oscats_model_has_covariate_name     (const OscatsModel *model,
                                                         const gchar *name);

Object Hierarchy

  GObject
   +----OscatsModel
         +----OscatsModelDina
         +----OscatsModelGpc
         +----OscatsModelGr
         +----OscatsModelHetlgr
         +----OscatsModelL1p
         +----OscatsModelL2p
         +----OscatsModelL3p
         +----OscatsModelNida
         +----OscatsModelNominal
         +----OscatsModelPc

Properties

  "Ncov"                     guint                 : Read
  "Ndims"                    guint                 : Read
  "Np"                       guint                 : Read
  "covariates"               OscatsCovariates*     : Read / Write / Construct Only
  "dimType"                  guint                 : Read
  "dims"                     GValueArray*          : Read / Write / Construct Only
  "paramNames"               GValueArray*          : Read
  "space"                    OscatsSpace*          : Read / Write / Construct Only

Description

Details

OSCATS_DEFAULT_KEY

#define OSCATS_DEFAULT_KEY 0


OscatsResponse

typedef guint8 OscatsResponse;

Type representing the response to an item. Simply an alias for guint8.


OSCATS_MAX_RESPONSE

#define OSCATS_MAX_RESPONSE G_MAXUINT8


struct OscatsModel

struct OscatsModel {
  OscatsSpace *space;
  guint Ndims;			// dimensions of test and this model
  guint Np, Ncov;		// number of parameters, covariates
  OscatsDim *dims, dimType;
  gdouble *params;
  GQuark *names, *covariates; // parameter and covariate names
  guint *shortDims;		// shortcut for model implementations
};


struct OscatsModelClass

struct OscatsModelClass {
  OscatsResponse (*get_max) (const OscatsModel *model);
  gdouble (*P) (const OscatsModel *model, OscatsResponse resp, const OscatsPoint *theta, const OscatsCovariates *covariates);
  gdouble (*distance) (const OscatsModel *model, const OscatsPoint *theta, const OscatsCovariates *covariates);
  void (*logLik_dtheta) (const OscatsModel *model, OscatsResponse resp,
                         const OscatsPoint *theta, const OscatsCovariates *covariates,
                         GGslVector *grad, GGslMatrix *hes, gboolean inf);
  void (*logLik_dparam) (const OscatsModel *model, OscatsResponse resp,
                         const OscatsPoint *theta, const OscatsCovariates *covariates,
                         GGslVector *grad, GGslMatrix *hes);
};

OscatsModel implementations must overload get_max and P. They may overload the remaining functions. Implementations should make clear in their documentation which optional functions they provide.

Note: The accessors for virtual functions of OscatsModel check the type validity of arguments, so implementations need not do so. However, implementations should still check the substantive valididity of arguments (including size of grad and Hes), as necessary.

get_max ()

get maximum response category supported by model

P ()

get the probability of a response, given a point in latent space

distance ()

get a distance metric between the item model and a given point in latent space

logLik_dtheta ()

get the derivative of the log-likelihood of the given response with respect to continuous dimensions of the model's latent subspace

logLik_dparam ()

get the derivative of the log-likelihood of the given response with respect to model parameters

oscats_model_new ()

OscatsModel *       oscats_model_new                    (GType type,
                                                         OscatsSpace *space,
                                                         const OscatsDim *dims,
                                                         OscatsDim ndims,
                                                         OscatsCovariates *covariates);

Creates a new model of type type in the sub-space of space defined by the ndims dimensions dims. If covariates is supplied, all of the covariates present in it will be incorporated into the model, for model implementations that support covariates. (Refer to specific model implementations for details.) Note: type must be a subclass of OscatsModel.

This is a convenience wrapper for g_object_new().

type :

the implemented sub-class of OscatsModel to create

space :

the OscatsSpace in which the model resides

dims :

the subspace of space used by this model. [in][array length=ndims][transfer none]

ndims :

the size of the sub-space used by the model

covariates :

optional covariates definition. [transfer none][allow-none]

Returns :

the newly-constructed model. [transfer full]

oscats_model_get_max ()

OscatsResponse      oscats_model_get_max                (const OscatsModel *model);

model :

an OscatsModel

Returns :

the maximum valid response category for this model

oscats_model_P ()

gdouble             oscats_model_P                      (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates);

Calculates the probability of response resp, given latent ability theta.

model :

an OscatsModel

resp :

the examinee response value

theta :

the GGslVector parameter value

covariates :

the values for covariates. [allow-none]

Returns :

the computed probability

oscats_model_distance ()

gdouble             oscats_model_distance               (const OscatsModel *model,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates);

Calculates a distance metric between the model and the given latent ability. Metric definition is implementation specific. Note: model implementations are not required to provide oscats_model_distance(). Refer to specific implementation documentation for details.

model :

an OscatsModel

theta :

the GGslVector parameter value

covariates :

the values of covariates. [allow-none]

Returns :

the distance metric

oscats_model_logLik_dtheta ()

void                oscats_model_logLik_dtheta          (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslVector *grad,
                                                         GGslMatrix *hes);

Calculates the derivative of the log-likelihood with respect to the latent ability theta, given the examinee response resp, evaluated at theta. If given, the graident is added to grad, and the Hessian (second derivatives) to hes. The vectors and matrix must have dimension model->dims->size.

Not all model implementations support oscats_model_logLik_dtheta(). Generally, only models on continuous latent sub-spaces will provide derivatives. Refer to model implementation documentation for details.

model :

an OscatsModel

resp :

the examinee response value

theta :

the value of the latent variables

covariates :

the value of covariates. [allow-none]

grad :

a GGslVector for returning the gradient. [inout][allow-none]

hes :

a GGslMatrix for returning the Hessian. [inout][allow-none]

oscats_model_logLik_dparam ()

void                oscats_model_logLik_dparam          (const OscatsModel *model,
                                                         OscatsResponse resp,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslVector *grad,
                                                         GGslMatrix *hes);

Calculates the derivative of the log-likelihood with respect to the parameters, given the examinee response resp, latent variables theta, and covariates covariates. If given, the graident is added to grad, and the Hessian (second partial derivatives) to hes. The gradient and Hessian must have dimension model->Np, and the latent ability theta must be compatible with "space" for model.

Note: Not all model implementations support oscats_model_logLik_dparam(). Refer to model implementation documentation for details.

model :

an OscatsModel

resp :

the examinee response value

theta :

the point in latent space

covariates :

the values of covariates. [allow-none]

grad :

a GGslVector for returning the gradient. [inout][allow-none]

hes :

a GGslMatrix for returning the Hessian. [inout][allow-none]

oscats_model_fisher_inf ()

void                oscats_model_fisher_inf             (const OscatsModel *model,
                                                         const OscatsPoint *theta,
                                                         const OscatsCovariates *covariates,
                                                         GGslMatrix *I);

Calculates the Fisher Information at theta, given covariates: I = E_{X|theta}[-d^2/dtheta dtheta' log(P(X))]. The information is added to I. The matrix must have dimension model->space->num_cont.

model :

an OscatsModel

theta :

the OscatsPoint latent point

covariates :

the value of covariates. [allow-none]

I :

a GGslMatrix for returning the Fisher Information

oscats_model_get_param_name ()

const gchar *       oscats_model_get_param_name         (const OscatsModel *model,
                                                         guint index);

model :

an OscatsModel

index :

the parameter index

Returns :

the name of parameter index < "Np". [transfer none]

oscats_model_has_param_name ()

gboolean            oscats_model_has_param_name         (const OscatsModel *model,
                                                         const gchar *name);

model :

an OscatsModel

name :

parameter name to check. [transfer none]

Returns :

TRUE if model has a parameter called name.

oscats_model_has_param ()

gboolean            oscats_model_has_param              (const OscatsModel *model,
                                                         GQuark name);

model :

an OscatsModel

name :

parameter name (as a GQuark) to check

Returns :

TRUE if model has a parameter called name.

oscats_model_get_param ()

gdouble             oscats_model_get_param              (const OscatsModel *model,
                                                         GQuark name);

model :

an OscatsModel

name :

the parameter name (as a GQuark)

Returns :

the parameter name

oscats_model_get_param_by_index ()

gdouble             oscats_model_get_param_by_index     (const OscatsModel *model,
                                                         guint index);

model :

an OscatsModel

index :

the parameter index

Returns :

the parameter index < "Np"

oscats_model_get_param_by_name ()

gdouble             oscats_model_get_param_by_name      (const OscatsModel *model,
                                                         const gchar *name);

The GQuark version oscats_model_get_param() is faster.

model :

an OscatsModel

name :

the parameter name. [transfer none]

Returns :

the parameter called name

oscats_model_set_param ()

void                oscats_model_set_param              (OscatsModel *model,
                                                         GQuark name,
                                                         gdouble value);

Faster to set by index.

model :

an OscatsModel

name :

the parameter name (as a GQuark)

value :

the gdouble to set

oscats_model_set_param_by_index ()

void                oscats_model_set_param_by_index     (OscatsModel *model,
                                                         guint index,
                                                         gdouble value);

model :

an OscatsModel

index :

the parameter index < "Np"

value :

the gdouble value to set

oscats_model_set_param_by_name ()

void                oscats_model_set_param_by_name      (OscatsModel *model,
                                                         const gchar *name,
                                                         gdouble value);

The GQuark version oscats_model_set_param() is faster.

model :

an OscatsModel

name :

the parameter name. [transfer none]

value :

the gdouble to set

oscats_model_has_covariate ()

gboolean            oscats_model_has_covariate          (const OscatsModel *model,
                                                         GQuark name);

model :

an OscatsModel

name :

covariate name (as a GQuark)

Returns :

TRUE if model incorporates covariate name

oscats_model_has_covariate_name ()

gboolean            oscats_model_has_covariate_name     (const OscatsModel *model,
                                                         const gchar *name);

model :

an OscatsModel

name :

covariate name. [transfer none]

Returns :

TRUE if model incorporates covariate name

Property Details

The "Ncov" property

  "Ncov"                     guint                 : Read

The number of covariates in the measurement model. Default is 0.

Default value: 0


The "Ndims" property

  "Ndims"                    guint                 : Read

The dimension of the IRT model (<= the dimension of the test). Determined from "dims". Default is 1.

Allowed values: >= 1

Default value: 1


The "Np" property

  "Np"                       guint                 : Read

The number of parameters of the measurement model.

Default value: 1


The "covariates" property

  "covariates"               OscatsCovariates*     : Read / Write / Construct Only

An OscatsCovariates object defining the covariates used in this model. Note: Models are not required to handle covariates. Refer to the particular model implementation.

Note: The OscatsCovariates object is not actually stored in the OscatsModel. On property read, a new OscatsCovariates object is created.


The "dimType" property

  "dimType"                  guint                 : Read

The dimension type of the model's subspace. If the model is multidimensional with mixed dimension types, "dimType" is 0. Determined from "dims".

Default value: 0


The "dims" property

  "dims"                     GValueArray*          : Read / Write / Construct Only

An array of OscatsDim indicating the subspace used by this model. The default is one dimension, which corresponds to the first dimension of the test space (preference to continuous dimensions, then binary, then natural-valued).


The "paramNames" property

  "paramNames"               GValueArray*          : Read

An array of names for parameters. The array must have "Np" elements. The order of the parameters and default names are defined by the particular model implementation.


The "space" property

  "space"                    OscatsSpace*          : Read / Write / Construct Only

The latent space for the test. This must be supplied at construction.