*! version 1.0 2020.03.25
help uirt_sim

Title

uirt_sim -- Stata module to simulate data from unidimensional Item Response Theory models

Syntax

uirt_sim [namelist] , ipar() [ options]

where namelist is a list of items to select from ipar() matrix;
optional - used if one wants to generate a dataset just for some of the items listed in ipar();
not an abbreviated varlist, exact list of item names is required

options

Obligatory
ipar(name) item parameters

Single group options
mean(#) mean of normal distribution of theta; default value is mean(0)

sd(#) standard deviation of normal distribution of theta; default value is sd(1)

obs(#) number of generated observations; default value is obs(1000)

Multiple groups options
grpar(name) parameters of normal distribution of theta in each group

grn(name) number of observations in each group

User-specified variables
theta(varname) use existing Stata variable with theta values

group(varname) use existing Stata variable with grouping information

Other
addtheta add a "theta" variable at the end of the dataset

igrn(name) number of observations for each item in each group

icats(name) matrix with item categories

Description

uirt_sim generates responses according to IRT model specifications provided by the user.
It is capable of generating multigroup and incomplete design datasets.
IRT model parameter formulation is the same as in uirt output, so the uirt results can be directly used as input for uirt_sim.

Options

Obligatory

ipar(name) sets the item parameters used for response simulation.
ipar() has to be a Stata matrix specified like e(item_par) in uirt output.

Single group options

mean(#) sets the mean of normal distribution of theta; default value is mean(0).
Used if theta() or grpar() are not provided.

sd(#) sets the standard deviation of normal distribution of theta; default value is sd(1).
Used if theta() or grpar() are not provided.

obs(#) sets the number of generated observations; default value is obs(1000).
Used if theta() or grn() are not provided.
Can be used in multigroup setting - each group will be of size obs().

Multiple groups options

grpar(name) sets the parameters of normal distribution of theta in each group.
For single group it can be replaced by setting mean() and sd().
A "group" variable indicating group membership is added at the end of the dataset.
grpar() has to be a Stata matrix specified like e(group_par) in uirt output.

grn(name) sets the number of observations in each group.
For single group it can be replaced by setting obs().
grn() has to be a Stata matrix specified like e(group_N) in uirt output.

User-specified variables

theta(varname) is used to provide a name of existing Stata variable with theta values to be used in response simulation.
If theta(varname) is specified mean() and sd() and obs() and grpar() and grn() options are ignored.
Missing values are not allowed in the theta() variable.

group(varname) is used to provide a name of existing Stata variable with grouping information.
It requires theta() or properly specified grpar().
Missing values are not allowed in the group() variable.

Other

addtheta adds a "theta" variable at the end of the dataset.
The variable contains theta values used in generating responses for each observation.
It is ignored if theta() is provided by the user.

igrn(name) used to set the number of observations for each item in each group.
It is useful for defining incomplete design datasets.
If an item has less observations in a group than specified in obs() or grn() then the missing item responses
will be generated at random within the group.
igrn() has to be a Stata matrix specified like e(item_group_N) in uirt output.

icats(name) sets a matrix with item categories.
If it is not specified the responses are generated as consequtive integers 0,1,...,max_cat where max_cat is inferred from ipar() matrix.
icats() has to be a Stata matrix specified like e(item_cats) in uirt output.

Examples

Creating a matrix with item parameters for 6 items in 2pl model

. matrix define ipar_example=(1,1,1,1.5,1.5,1.5\-1,0,1,-1,0,1)'

. matrix colnames ipar_example= a b

. matrix roweq ipar_example= i1 i2 i3 i4 i5 i6

. matrix rownames ipar_example= 2plm 2plm 2plm 2plm 2plm 2plm

. mat l ipar_example

Generating data according to "ipar_example" with default settings

. uirt_sim,ipar(ipar_example)

Generating two-group data according to "ipar_example" with grpar() and grn() settings

. *1) creating an example matrix with parameters of normal distribution for each group to use in grpar()

. matrix define grpar_example=(0,-1\1,2)

. matrix colnames grpar_example=group_1 group_2

. matrix rownames grpar_example=mean sd

. mat l grpar_example

. *2) creating an example matrix with number of observations each group to use in grn()

. matrix define grn_example=(1000,2000)

. matrix colnames grn_example=group_1 group_2

. matrix rownames grn_example=N

. mat l grn_example

. *Generating the dataset

. uirt_sim,ipar(ipar_example) grpar(grpar_example) grn(grn_example)

Previous example in NEAT design using igrn() setting

. *3) creating an example matrix to use in igrn(): i1 i2 - responded in group_1, i5 i6 - responded in group_2, i3 i4 - common items

. matrix define igrn_example=(1000,1000,1000,1000,0,0\0,0,2000,2000,2000,2000)'

. matrix colnames igrn_example=group_1 group_2

. matrix rownames igrn_example=i1 i2 i3 i4 i5 i6

. mat l igrn_example

. *Generating the dataset

. uirt_sim,ipar(ipar_example) grpar(grpar_example) grn(grn_example) igrn(igrn_example)

Generating data only for items i1 i2 i3 i6 from "ipar_example" with user-provided "theta_user" variable

. uirt_sim i1 i2 i3 i6,ipar(ipar_example) theta(theta_user)

Generating data according to "ipar_example" matrix with items i1 and i3 scored 0,2 instead of 0,1 with icats() option

. * creating an example matrix to use in icats(); only entries for item i1 and i3, remaining items will be scored as defaulted

. matrix define icats_example=(0,2\0,2)

. matrix colnames icats_example=cat_1 cat_2

. matrix rownames icats_example=i1 i3

. *Generating the dataset

. uirt_sim,ipar(ipar_example) icats(icats_example)

Stored results

uirt_sim does not store anything in r() or e()

Author

Bartosz Kondratek
everythingthatcounts@gmail.com

Funding

Preparation of uirt_sim was funded by the National Science Center research grant number 2015/17/N/HS6/02965.