![]() |
![]() |
![]() |
liboscats Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy | Properties |
#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
);
GObject +----OscatsModel +----OscatsModelDina +----OscatsModelGpc +----OscatsModelGr +----OscatsModelHetlgr +----OscatsModelL1p +----OscatsModelL2p +----OscatsModelL3p +----OscatsModelNida +----OscatsModelNominal +----OscatsModelPc
"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
typedef guint8 OscatsResponse;
Type representing the response to an item. Simply an alias for guint8.
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 { 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 maximum response category supported by model | |
get the probability of a response, given a point in latent space | |
get a distance metric between the item model and a given point in latent space | |
get the derivative of the log-likelihood of the given response with respect to continuous dimensions of the model's latent subspace | |
get the derivative of the log-likelihood of the given response with respect to model parameters |
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()
.
|
the implemented sub-class of OscatsModel to create |
|
the OscatsSpace in which the model resides |
|
the subspace of space used by this model. [in][array length=ndims][transfer none]
|
|
the size of the sub-space used by the model |
|
optional covariates definition. [transfer none][allow-none] |
Returns : |
the newly-constructed model. [transfer full] |
OscatsResponse oscats_model_get_max (const OscatsModel *model
);
|
an OscatsModel |
Returns : |
the maximum valid response category for this model |
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
.
|
an OscatsModel |
|
the examinee response value |
|
the GGslVector parameter value |
|
the values for covariates. [allow-none] |
Returns : |
the computed probability |
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.
|
an OscatsModel |
|
the GGslVector parameter value |
|
the values of covariates. [allow-none] |
Returns : |
the distance metric |
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.
|
an OscatsModel |
|
the examinee response value |
|
the value of the latent variables |
|
the value of covariates. [allow-none] |
|
a GGslVector for returning the gradient. [inout][allow-none] |
|
a GGslMatrix for returning the Hessian. [inout][allow-none] |
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.
|
an OscatsModel |
|
the examinee response value |
|
the point in latent space |
|
the values of covariates. [allow-none] |
|
a GGslVector for returning the gradient. [inout][allow-none] |
|
a GGslMatrix for returning the Hessian. [inout][allow-none] |
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
.
|
an OscatsModel |
|
the OscatsPoint latent point |
|
the value of covariates. [allow-none] |
|
a GGslMatrix for returning the Fisher Information |
const gchar * oscats_model_get_param_name (const OscatsModel *model
,guint index
);
|
an OscatsModel |
|
the parameter index |
Returns : |
the name of parameter index < "Np". [transfer none]
|
gboolean oscats_model_has_param_name (const OscatsModel *model
,const gchar *name
);
|
an OscatsModel |
|
parameter name to check. [transfer none] |
Returns : |
TRUE if model has a parameter called name . |
gboolean oscats_model_has_param (const OscatsModel *model
,GQuark name
);
|
an OscatsModel |
|
parameter name (as a GQuark) to check |
Returns : |
TRUE if model has a parameter called name . |
gdouble oscats_model_get_param (const OscatsModel *model
,GQuark name
);
|
an OscatsModel |
|
the parameter name (as a GQuark) |
Returns : |
the parameter name
|
gdouble oscats_model_get_param_by_index (const OscatsModel *model
,guint index
);
|
an OscatsModel |
|
the parameter index |
Returns : |
the parameter index < "Np"
|
gdouble oscats_model_get_param_by_name (const OscatsModel *model
,const gchar *name
);
The GQuark version oscats_model_get_param()
is faster.
|
an OscatsModel |
|
the parameter name. [transfer none] |
Returns : |
the parameter called name
|
void oscats_model_set_param (OscatsModel *model
,GQuark name
,gdouble value
);
Faster to set by index.
|
an OscatsModel |
|
the parameter name (as a GQuark) |
|
the gdouble to set |
void oscats_model_set_param_by_index (OscatsModel *model
,guint index
,gdouble value
);
|
an OscatsModel |
|
the parameter index < "Np" |
|
the gdouble value to set |
void oscats_model_set_param_by_name (OscatsModel *model
,const gchar *name
,gdouble value
);
The GQuark version oscats_model_set_param()
is faster.
|
an OscatsModel |
|
the parameter name. [transfer none] |
|
the gdouble to set |
gboolean oscats_model_has_covariate (const OscatsModel *model
,GQuark name
);
|
an OscatsModel |
|
covariate name (as a GQuark) |
Returns : |
TRUE if model incorporates covariate name
|
gboolean oscats_model_has_covariate_name (const OscatsModel *model
,const gchar *name
);
|
an OscatsModel |
|
covariate name. [transfer none] |
Returns : |
TRUE if model incorporates covariate name
|
"Ncov"
property"Ncov" guint : Read
The number of covariates in the measurement model. Default is 0.
Default value: 0
"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
"Np"
property"Np" guint : Read
The number of parameters of the measurement model.
Default value: 1
"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.
"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
"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).
"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.
"space"
property"space" OscatsSpace* : Read / Write / Construct Only
The latent space for the test. This must be supplied at construction.