Table of Contents

• Using ICL
  • Installing and Running ICL
    • Running the Windows and Linux Versions of ICL
    • Running the Macintosh Version of ICL
  • Basic ICL Commands
  • ICL Commands
  • Using Tcl
• Examples
  • Single Group Estimation
  • Multiple Group Estimation
  • EAP and MLE Theta Estimates for Examinees
  • Pretest Item Calibration
  • Multiple Group Estimation with Normal Distributions
  • Bootstraping Item Parameter Estimates
  • Simulating Item Responses
  • Estimation of Dichotomous and Polytomous Items
  • Data Processing Using Tcl
• Format Specifiers for C sprintf Function
• License
• References

• Using ICL:
• Examples:
• Format Specifiers for C sprintf Function:
• License:
• References:

Using ICL

• Installing and Running ICL:
• Basic ICL Commands:
• ICL Commands:
• Using Tcl:

IRT Command Language (ICL) is a computer program that can estimate parameters for the 1-, 2-, and 3-parameter logistic item response models for dichotomous items (Lord, 1980), and the partial credit and generalized partial credit models for polytomous items (Muraki, 1992). ICL can compute maximum likelihood or Bayes modal estimates of item parameters by finding the maximum of the marginal likelihood or posterior distribution, where the marginalization is over a discrete distribution of latent examinee proficiency in the population of examinees from which the data were sampled. The EM algorithm (Dempster, Laird, and Rubin, 1977; McLachlan and Krishnan, 1997) is used to compute the maximum likelihood or Bayes modal estimates. ICL handles single and multiple group estimation. In single group estimation it is assumed that all examinees are sampled from the same population, although different examinees may take different subsets of items. In multiple group estimation groups of examinees taking different, overlapping, subsets of items may be sampled from different populations. A description of the general algorithm used by the program in the single group case is presented in Woodruff and Hanson (1997) and Hanson (1998).

The next section discusses how to install and run ICL on three different operating systems: Windows, Macintosh, and Linux. Section 1.2 describes some basic ICL commands. These sections present basic information that is needed by all ICL users. The last two sections discuss ICL commands that allow more control over the program. These sections only need to be read if features are needed beyond those offered by the commands discussed in Section 1.2 (Basic ICL Commands).

The next chapter contains several examples. The first two examples use only the basic ICL commands discussed in Section 1.2. The remaining examples illustrate more advanced features of ICL.

Information about ICL, the latest version of ICL, this manual, and the ICL source code can be obtained from the ICL home page. ICL is part of the Social Science Measurement project hosted on the SourceForge web site. The development of ICL is managed through the SourceForge web site, which allows anyone interested to participate in the development of ICL.

ICL supercedes the Estimation Program for Dichotomous Item Response Models (EPDIRM) by adding the capability of estimating item parameters for polytomous IRT models. Most EPDIRM control files will require some minor changes to be used with ICL. Most importantly, the names of the three commonly used EPDIRM commands epdirm_start, epdirm_end, and starting_values have been changed to allocate_items_dist release_items_dist, and starting_values_dichotomous, respectively, in ICL. More details about EPDIRM commands that have changed in ICL can be found on this web page: epidrm_differences.html.

Installing and Running ICL

• Running the Windows and Linux Versions of ICL:
• Running the Macintosh Version of ICL:

There are pre-compiled versions of ICL available for Windows, Macintosh, and Linux. The Linux source code can be used to compile ICL for other UNIX operating systems. In each case ICL is packaged as a single executable file. Installing ICL just involves copying this executable file to an appropriate location on the hard disk.

ICL runs by executing a sequence of commands. The commands are executed one by one in the order given. ICL can be run either interactively or in batch mode. When run interactively individual commands are typed for ICL to execute. In batch mode ICL processes a file containing a sequence of commands. The commands in the file are executed in the order in which they appear in the file. The following sections describe how to run the Windows, Linux, and Macintosh versions of ICL.

Running the Windows and Linux Versions of ICL

The Windows version of ICL requires a 32-bit version of Windows (95, 98, NT, 2000, XP). Even though the Windows version of ICL is a command-line program it will not run under DOS. There may be problems running ICL on very early versions of Windows 95. ICL requires the DLL file MSVCRT.DLL which was not included with the original Windows 95 release. If you have an early version of Windows 95 without MSVCRT.DLL you will need to upgrade your version of Windows or obtain a copy of the required DLL.

The Linux version of ICL should run under any Linux distribution. It is statically linked and does not depend on any Linux shared libraries.

ICL is command line program that runs in a command console. Under Windows it runs in a command prompt window, and under Linux it runs in a console window. ICL can be started from a command console in interactive mode by typing the name of the executable file and hitting the enter or return key. An interactive session is started in which ICL commands can be entered. This assumes the ICL executable file has been put in a directory that is in the list of directories searched for executable applications (i.e., the directory is contained in the list of directories given by the PATH environment variable). ICL can also be started in interactive mode by double clicking on the ICL icon. This will open a console window in which ICL commands can be entered. To stop an interactive ICL session use the exit command, or close the console window in which ICL is running. The source command can be used to execute a sequence of commands from a file when ICL is run interactively. To use the source command type source followed by the name of the file containing the ICL commands to execute.

To run ICL in batch mode type the name of the ICL executable file followed by the name of a file containing ICL commands in a console window. The commands in the file will be executed and ICL will then quit. For example, the following command can be used to run the example program described in Section 2.1 (the name of the executable file is icl):

icl mondaty.tcl

Running the Macintosh Version of ICL

The Macintosh version of ICL should work on version 8.0 or higher of the classic Macintosh operating system (Mac OS). ICL will also probably work with Mac OS version 7, but has only been tested on Mac OS 8 and Mac OS 9. The Macintosh version of ICL will also run in the classic environment of Mac OS X.

ICL requires a Macintosh with a PowerPC processor (including the G3 or G4 processor). All recent Macintosh models have a PowerPC processor. ICL will not work on older Macintoshes which use the 68000 family of processors. The default memory allocation for ICL is 6 megabytes. For large problems the memory allocation will need to be increased.

ICL is a command line program that is run in a command console. Unlike Windows and Linux, the Mac OS does not have any built-in command console. The Macintosh version of ICL currently only supports interactive mode in a command window created by the program.

To start the Macintosh version of ICL double click on the ICL program icon. When the program begins a command window is displayed. ICL commands can be typed into this window and executed. The source command can be used to execute ICL commands contained in a file. To use the source command type source followed by the name of the file containing the ICL commands to execute.

File names used with commands such as source are relative to the current folder. When the program begins the current folder is the folder containing the ICL application. The full path of the current folder can be printed using the pwd command. A list of the files and folders contained in the current folder can be obtained using the ls command. The ls -l command lists additional information about the files and folders in the current folder.

The cd command can be used to change the current folder. It may be easier to change the current folder if files need to be accessed in another folder which would require the use of a full path name. On a Macintosh colons separate elements of a path name. For example, the command cd {Macintosh HD:work} will change the current folder to a folder named work on a disk named Macintosh HD. The brackets are needed around the path to the folder because there is a space in the path.

A strategy for using the Macintosh version of ICL that minimizes having to type long path names is to install the files to be used with ICL within folders that are contained in the folder containing the ICL application. For instance, if the examples folder that comes with the ICL distribution was placed in the same folder containing the ICL application then the following two commands could be used to run the given in Section 2.1:

cd :examples
source mondaty.tcl

The cd command in the above example illustrates that relative paths on the Macintosh begin with a colon. If it is necessary to deal with full path names a utility like CopyPaths is recommended. CopyPaths allows full paths to be copied from the Finder and pasted into an ICL command.

Text in the console window can be copied and saved using commands in the File and Edit menus. To quit the program selected Quit from the File menu, or use the exit command.

Basic ICL Commands

When ICL executes a sequence of commands in the order given. Commands can be entered interactively one by one, or read from a file. This section discusses command syntax and describes several basic ICL commands.

An ICL command has the following syntax

command arg1 arg2 arg3 ...

where command is the command name which is followed by the arguments to the command. The command name and the command arguments are separated from one another by white space (spaces or tabs).

Each ICL command appears on a separate line. A command can appear on two or more lines if each line before the last one containing the command ends with a backslash. Any line in which the first non-blank character is a pound sign (#) is treated as a comment. An example ICL command file is given below:

# Estimate item parameters using data set mondatx
# from Kolen and Brennan (1995)

# Write output to log file mondatx.log
output -log_file mondatx.log

# 36 dichotomous items to be modeled
allocate_items_dist 36

# Read examinee item responses from file mondatx.
# Each record contains the responses to
# 36 items for an examinee in columns 1-36.
read_examinees mondatx 36i1

# Compute starting values for item parameter estimates
starting_values_dichotomous

# Perform EM iterations for computing item parameter estimates.
# Maximum of 50 EM iterations.
EM_steps -max_iter 50

# Print item parameter estimates and discrete latent
# variable distribution.
print -item_param -latent_dist

# Release memory allocated to hold items and the
# latent variable distribution
release_items_dist

There are 7 ICL commands in this file. All lines beginning with a pound sign are comments. Blank lines are ignored. Detailed descriptions of the commands used in this command file are given below. This example is discussed in more detail in Section 2.1.

This section presents detailed descriptions of eight basic ICL commands -- allocate_items_dist, release_items_dist, read_examinees, starting_values_dichotomous, EM_steps, print, options, and output. These eight commands are all that are needed to compute item parameter estimates in typical cases. Recall that ICL commands are executed in the order given. A restriction on the order in which the commands can be given is that the read_examinees, starting_values_dichotomous, EM_steps, and print commands can only occur after an allocate_items_dist command. In addition, the output and options commands will typically occur as the first commands to be executed, although they are not restricted to appearing before other commands.

Some arguments to ICL commands begin with a hyphen. These arguments are optional and can appear in any order. Arguments that do not begin with a hyphen must appear in a specific position within the command string (positional arguments). In some cases an option will be composed of two command arguments -- one argument beginning with a hyphen and a second argument following the first which specifies a variable associated with that option. For example, the following command contains one positional argument and two command options.

# 60 dichotomous items will be modeled.
# 50 points in discrete latent variable distribution.
# Examinees are sampled from one population.
allocate_items_dist 60 -num_latent_dist_points 50 -num_groups 1

The first argument of the allocate_items_dist command is the number of items to be modeled. This argument is required and must be the first argument of the command. The second and third arguments (-num_latent_dist_points and 50) are associated with one command option. These two arguments together specify that the number of points used for the discrete latent variable distribution is 50. The fourth and fifth arguments (-num_groups and 1) are also associated with one command option. These two argument specify that the examinees were sampled from one group (single group estimation is used). The effect of the command would have been the same if the last two arguments were left off because the default number of groups is one if the -num_groups option is not specified.

The notation used in the command documentation in this section and following sections is as follows. The commands are presented in bold type, a command argument that is literal text (the text is exactly the same in every instance of the command) is presented in fixed type, and a command argument that is variable text (this text can vary from one instance of the command to another) is presented in italic type. Optional arguments are enclosed within a pair of question marks. In cases in which two arguments compose a command option and must go together both arguments are enclosed in a single set of question marks. The Tcl to the right of each command is an indication of the language the command was written in and can be ignored -- it has no significance regarding how the command is used. The meaning of Tcl is explained in the next section which discusses advanced ICL commands. The remainder of this section presents descriptions of the eight basic ICL commands.

allocate_items_dist nitems ?-models list? ?-models_str string? ?-num_latent_dist_points npoints? ?-num_groups ngroups? ?-latent_dist_range list? ?-unique_points?

Tcl

The allocate_items_dist command is used to specify the number of items to be modeled, whether a dichotomous or polytomous model is to be used for each item, the number of examinee groups, the number of points in the discrete latent variable distribution, and the minimum and maximum points of the discrete latent variable distribution. The allocate_items_dist command allocates space to hold information for each item and for the latent variable distribution. An allocate_items_dist command must be given before any of the commands except options and output can be used. The value of the first argument is the total number of items to be modeled. In subsequent commands items are identified by item number. If the number of items specified is n then item numbers 1 through n are used to refer to these items in subsequent commands. The -models argument is associated with a list containing an integer for each item. The integer 1 corresponding to an item means the item is modeled using a dichotomous model. If the integer corresponding to an item is greater than 1 that means the item is a polytomous item with that number of response categories modeled using a polytomous model. By default the three-parameter logistic model is used for dichotomous items and the generalized partial credit model is used for polytomous items. The default models to use for dichotomous and polytomous items can be set with the --default_model_dichotomous and the -default_model_polytomous arguments of the options command. If the -models option is not present the models for all items are assumed to be dichotomous. The -models_str argument identifies whether to use a dichotomous or polytomous model for each item in the same way as the -models option, except that the integers that indicate the model to use for each item are contained in a string. Each character in the string gives a model to use for one item. This means the -model_str argument can only be used when the number of response categories for all polytomous items is less than 10. If the number of response categories is greater than 9 for any item the -models argument must be used, rather than the -models_str argument. If the -models and a -models_str arguments are both present the -models_str argument is used to determine the model for each item. The following example illustrates the use of the -models_str argument. # Ten total items are modeled. The # first six items are modeled using the three-parameter # logistic model, and the remaining four items are # modeled using the generalized partial credit model. # The seventh item has two response categories, the # eighth and ninth items have 3 response categories, # and the tenth item has four response categories. allocate_items_dist 10 -models_str 1111112334 Examples of using the -models argument are given in Sections 2.7 and 2.8. The -num_latent_dist_points option gives the number of categories used for the discrete latent variable distribution. The default value if the -num_latent_dist_points option is not present is 40. The -num_groups option gives the number of groups of examinees in the data that are sampled from different populations. The default value if the -num_groups option is not present is 1. If the number of groups is greater than 1 multiple group estimation used, and a group identifier must be indicated for each examinee. The list given for the -latent_dist_range option should contain two numbers giving the minimum and maximum points of the discrete latent variable distribution, respectively. For example, -latent_dist_range {-5 5} indicates the minimum and maximum points of the latent distribution are -5 and 5. The default minimum and maximum points of the latent distribution if the -latent_dist_range option is not used are -4 and 4, respectively. If the -unique_points option is present then unique points will be used for each latent variable distribution in each examinee group. If the -unique_points option is not present one set of points are used for the latent variable distributions in all examinee groups, although different latent distribution probabilities are used for each group. The -unique_points option is only relevant if more than one examinee group is specified with the -num_groups option. This option must be used with the allocate_items_dist command if the -estim_dist_mean_sd option or -estim_dist_mean option is used with the EM_steps command. Section 2.5 gives an example in which the -unique_points option is used. The allocate_items_dist command assigns initial values to the item parameters for all items. The initial parameter estimates assigned to all a-, b-, and c-parameters are 1.0, 0.0, and 0.2, respectively. The same values are used for the a- and b-parameters of dichotomous and polytomous models. The values of the item parameters for individual items can be changed using the item_set_param and item_set_params commands. The starting_values_dichotomous command can be used to compute parameter starting values for dichotomous models. The allocate_items_dist command initializes the prior distributions used for all item parameters to default values. The prior distributions used as defaults can be set using the options command. If the options command is not given the default item parameter prior distributions for the a-, b- and c-parameters are four-parameter beta with parameters (1.75, 3.0, 0.0, 3.0), (1.01, 1.01, -6.0, 6.0) and (3.5, 4.0, 0.0, 0.5), respectively, where the four numbers in the parameter list are the two shape parameters followed by the lower and upper limits of the distribution. The same default priors are used for the a-parameters and b-parameters of both dichotomous and polytomous models. The priors used for item parameters for individual items can be changed with the item_set_prior and items_set_prior commands. The values of the points and weights (probabilities) used for the discrete latent variable distribution are also initialized by the allocate_items_dist command. There is one set of points (unless the -unique_points option is used) and a set of weights for each examinee group. The default points are equally spaced between minimum and maximum points indicated by the -latent_dist_range option, inclusive. The default weights are chosen so the resulting discrete distribution approximates a standard normal distribution. When there is more than one examinee group the initial weights are the same across groups. The points can be changed with the dist_set_point and dist_set_points commands. The weights can be changed by the dist_set_prob and dist_set_probs commands. The allocate_items_dist command writes information to the log file specified using the output command including the version number of the ICL program, the number of items, the number of categories in the discrete latent variable distribution, the number of groups, and the default prior distributions used for item parameters. The command file is also listed, if a command file is being used. This information is not written to the log file if the output -no_print command is executed before the allocate_items_dist command.

EM_steps ?-max_iter iter? ?-crit d? ?-estim_dist? ?-scale_points? ?-no_print_iter? ?-no_mstep_iter_error? ?-estim_dist_mean_sd? ?-estim_dist_mean?

Tcl

The EM_steps command performs EM iterations to estimate item parameters and, optionally, the marginal latent variable distributions. An allocate_items_dist command must be given before this command can be used. The -max_iter options specifies the maximum number of EM iterations. If the maximum number of iterations is not specified a default value of 100 is used. The convergence criterion used to determine when to stop EM iterations is the maximum relative change in an item parameter estimate from the previous to the current iteration over all parameters across all items. The option -crit specifies the value this convergence criterion must be less than to stop. The default criterion if the -crit option is not specified is 0.001. If the convergence criterion is not met after the specified number of iterations a warning message is printed in the log file. If the -estim_dist option is given an M-step to estimate the probabilities of the marginal latent variable distribution for the base examinee group is performed in each EM iteration, otherwise this distribution is fixed across EM iterations. The base examinee group is group 1 unless otherwise specified using the -base_group option on the options command. If the number of examinee groups is greater than one the latent variable distributions for groups other than group 1 are estimated regardless of whether the -estim_dist option is used. If the -scale_points option is used the points of latent variable distribution are linearly transformed after every M-step so that the mean and s.d. in base examinee group are 0 and 1. This scale transformation is also applied to the parameter estimates for all items to put them on the same scale. When this argument is not present the points of the latent variable distribution are not changed, even when the latent variable probabilities for all groups are estimated. This argument only has an effect when the latent variable distribution of the base group is being estimated as requested with the -estim_dist option. If the -no_mstep_iter_error option is used then the maximum number of iterations being exceeded in the M-step optimization is not considered an error that stops the calculation. Instead, a warning message is printed in the log file and the calculation continues. If this option is not present then if the maximum number of M-step iterations is exceeded for an item an error message is printed and the calculation is terminated. The maximum number of M-step iterations can be set for all items with the -max_iter_optimize option of the options command, or can be set for individual items with the mstep_max_iter command. If the -estim_dist_mean_sd option is used the mean and standard deviation, rather than the probabilities, of the latent variable distributions are estimated. If this option is used the points of the latent variable distribution for all examinee groups except the base group are modified to be consistent with an estimated mean and standard deviation (the mean and standard deviation are fixed for the base group). The -estim_dist_mean option is similar to the -estim_dist_mean_sd option except that only the means of the latent variable distributions are estimated. These options require that different latent distribution points be used for different examinee groups as specified using the -unique_points option of the allocate_items_dist command. Section 2.5 gives an example in which the -estim_dist_mean_sd option is used. After each iteration several numbers are written to the log file unless output has been suppressed with the output -no_print command: 1) the iteration number, 2) the maximum difference between a parameter estimate from the last and second to last iteration, 3) the maximum difference between a probability of the latent variable distribution from the last and second to last iteration if the latent variable distribution is being estimated (the number of examinee groups is greater than 1 or the -estim_dist option is used, and the -estim_dist_mean_sd or -estim_dist_mean options are not used), 4) the maximum difference between the latent variable distribution mean from the last and second to last iteration if the -estim_dist_mean_sd or -estim_dist_mean option is used, 5) the maximum differences in the s.d. between the last and second to last iteration if the -estim_dist_mean_sd option is used, and 6) the value of the marginal posterior at the value of the parameter estimates (this is the quantity being maximized by the EM algorithm). This information is also written to the screen unless the -no_print_iter option is used. A list containing these values at the last iteration is returned by the EM_steps command.

options ?-D d? ?-missing_resp resp? ?-base_group group? ?-default_model_dichotomous model? ?-default_model_polytomous model? ?-max_iter_optimize max? ?-default_prior_a prior? ?-default_prior_b prior? ?-default_prior_c prior? ?-default_dist_range list?

Tcl

The options command sets global program options. The options set with this command influence the behavior of other commands such as the allocate_items_dist command. Consequently, the options command is typically one of the first commands executed. The -missing_resp option is used to specify the character that indicates an examinee has not responded to an item. Any character except 0 and 1, which indicate an incorrect and correct response, can be used. The default character indicating a missing response is a period. The -D option specifies the value of a scaling constant (D) in the logistic function for the 3PL, 2PL, and 1PL models. The value 1.7 makes the logistic ogive close to a normal ogive. If the option -D command is not given the value of 1.7 is used as the default. This option does not have an effect on the GPCM and PCM models. The -default_model_dichotomous option specifies the default model used for an item modeled using a dichotomous model. The value of this option can be one of three values 3PL, 2PL, or 1PL corresponding to the three-parameter, two-parameter, and one-parameter logistic models. If the option -default_model_dichotomous command is not given the three-parameter logistic model is used as the default. The -default_model_polytomous option specifies the default model used for an item modeled using a polytomous model. The value of this option can be either GPCM or PCM corresponding to the generalized partial credit model and the partial credit model. If the option -default_model_polytomous command is not given the generalized partial credit model is used as the default. The model for individual items can be set with the item_set_model command. The -base_group option specifies the examinee group that will be used as the base group. The latent variable distribution for the base group is fixed rather than estimated unless the -estim_group option is used with the EM_steps command. If the -estim_group option is used with the EM_steps command the mean and standard deviation of the base group latent variable distribution are fixed at zero and one. The -max_iter_optimize option sets the maximum number of iterations used for each item in the optimization procedure used for the M-step and starting value calculations. The default value used if this option is not present is 150. To set the maximum number of iterations used in the optimization procedure for each item individually use the mstep_max_iter command. The -default_dist_range option sets the minimum and maximum points to be used for the discrete latent variable distribution. If this option is not present the default values used for the minimum and maximum points of the discrete latent variable distribution are -4 and 4, respectively. The minimum and maximum points are specified as two numbers surrounded by brackets (a list of two numbers). For example, the following command will specify the minimum and maximum points at -5 and 5 options -default_dist_range {-5 5} The third argument of this command shows that to specify a list of strings as a single command argument the elements of the list should be surrounded by brackets. The -default_prior_a, -default_prior_b, and -default_prior_c options set the default prior distributions used for the a-, b-, and c-parameters for all items. The same default priors for a- and b-parameters are used for dichotomous and polytomous models. For each of these options the prior is specified by a list, where the first element of the list is the type of prior distribution and the remaining elements of the list are the parameters of the prior distribution. There are three distribution types possible: normal, lognormal beta, and none, corresponding to the normal distribution, the lognormal distribution, the four-parameter beta distribution, and no prior distribution, respectively. For the normal and lognormal distributions two parameters need to be specified: a mean and standard deviation, in that order. For the four-parameter beta distribution the parameters that need to be specified are the two shape parameters, the lower limit, and the upper limit, in that order. For example, # Specify prior distributions used by default in BILOG # Lognormal prior for a-parameters with mean 0 and standard # deviation 0.5 in the underlying normal distribution options -default_prior_a {lognormal 0.0 0.5} # No prior for b-parameters options -default_prior_b none # Two-parameter beta prior is used by BILOG for the # c-parameters when the number of response options is 4. options -default_prior_c {beta 6.0 16.0 0.0 1.0} As the above example indicates, more than one options command can be used. The following example shows the default prior distributions that would be used if no options statements were used. These priors are also presented in the discussion of the allocate_items_dist command. # Default prior for a used if option command is not used. # The 10th, 25th, 50th, 75th, and 90th percentiles # of this distribution are .34, .62, 1.05, 1.53, and 1.96, # respectively. The mean is 1.11 and the mode is .82. options -default_prior_a {beta 1.75 3.0 0.0 3.0} # Default prior for b used if option command is not used # This is an almost uniform prior on the interval -6 # to 6. It is better to not use an exact uniform # distribution so that the slopes at # the distribution limits are not infinite options -default_prior_b {beta 1.01 1.01 -6.0 6.0} # Default prior for c used if option command is not used. # The 10th, 25th, 50th, 75th, and 90th percentiles # of this distribution are .12, .17, .23, .30, and .35, # respectively. The mean is .23 and the mode is .23. options -default_prior_c {beta 3.5 4.0 0.0 0.5} Separate prior distributions for parameters of individual items can be set with the item_set_prior and items_set_prior commands.

output ?-log_file file_name? ?-no_print?

Tcl

The output command is used to specify options for printed output. The -log_file argument is used to specify the name of a log file to which the printed output of commands is written. If the -no_print option is specified then written output of any command is suppressed.

print ?-item_param? ?-latent_dist? ?-latent_dist_moments? ?-no_heading? ?-items itemno? ?-format string? ?-item_model?

Tcl

The print command prints item parameter estimates, latent variable distributions, and moments to the log file. If the -item_param argument is present then the current item parameter estimates are printed to the log file. If the -latent_dist argument is present then the current discrete latent distributions for all examinee groups are printed to the log file. If the -latent_dist_moments argument is present then the mean and standard deviation of the current discrete latent distributions for all examinee groups are printed to the log file. If more than one of the -item_param, -latent_dist, or -latent_dist_moments options is given the order in which the output is printed is: 1) the item parameters, 2) latent variable distributions, and 3) moments of the latent variable distributions. To print the options in a different order multiple print statements could be used: # print latent variable distributions followed by item parameter # estimates print -latent_dist print -item_param If the -no_heading option is used no descriptive heading is printed before the item parameters and latent variable distribution. Item parameter estimates will only be printed for items corresponding to item numbers in the list following -items. If the -items option is not used item parameter estimates are printed for all items. If the -item_param option is not used then the -items option has no effect. The -format option is used to specify the output format used for the item parameter estimates, weights of the latent variable distribution, and moments. The format is used for all item parameter estimates, for the weights of the latent variable distribution (fixed point format with six decimal places is used for the points of the latent variable distribution), and the mean and standard deviation. The format specified is used for all elements to be printed. To use separate formats for different elements to be printed use separate print commands as in the example below. The string giving the format is a C sprintf-like format -- %[width][.precision]char, where char = f (fixed point), e (scientific notation), or g (fixed point or scientific notation, which ever takes less space). A more detailed description of the format specification is given in Appendix A. If a format is not specified the default format used for printing the item parameter estimates and distribution moments is %.6f (fixed point with six places after the decimal point), and the default format used for the distribution weights is %.6e (scientific notation with six places after the decimal point). If the -model_item option is present the model associated with each item (either 3PL, 2PL, 1PL, GPCM, or PCM) is printed between the item number and first parameter when the -item_param option is specified. An example of the print command is given below. # Print the item parameter estimates and latent variable # distribution using 8 digits after the decimal # point rather than the default 6. print -item_param -format %.8f print -latent_dist -format %.8e

read_examinees file resp_format ?group_format?

Tcl

The read_examinees command reads examinee responses to the items, and optionally an examinee group, from a file. The first argument is the name of the file to read examinee responses from. It is assumed that each line of the file contains responses to all items for one examinee. The second argument consists of a format list which indicates which columns in each record contain item responses. The syntax of a format list is explained below. The optional third argument consists of a format list which indicates which columns in each record contain the group number the examinee belongs to. The third argument is only needed if the number of groups indicated in the allocate_items_dist command is greater than 1. The read_examinees command returns the number of examinees for whom item responses were read. The number of item responses read for an examinee must be equal to the number of items given on the allocate_items_dist command (the read_examinees_missing command can be used when examinee records do not contain the responses to all items). A '1' or '0' indicates a correct or incorrect response to the item, respectively. If the examinee did not respond to the item, for example if they did not receive the item, a '.' (period) should be given as the item response. The character that indicates an examinee did not respond to the item can be changed using the options command. The first item read for each examinee corresponds to item 1, the second item read corresponds to item 2, etc. The group numbers must be 1, 2, ..., up to the number of groups. The format list used for the second and third arguments contains strings in one of two forms: 1) @#, where # is an integer, which means move to column # of the input record, 2) ri#, where r and # are integers, which means read r item responses from r times # columns at the current location in the input record, where each response contains # characters. The r is optional, and if not given is assumed to be 1. If there is more than one string in the format list the list must be delimited by brackets ('{' and '}'). If there is only one string in the format the brackets are not necessary. Examples of the read_examinee command illustrating the use of format lists in the second and third argument are: # Read item responses for 15 items from columns 3-7 # and columns 20-29 of each input record in file test.in read_examinees test.in {@3 5i1 @20 10i1} # Read item responses for 100 items from columns 2-101. # Read group number from column 1 read_examinees test.in {@2 100i1} i1 Other examples illustrating the use of the read_examinees command are given in Chapter 2.

release_items_dist

Tcl

The release_items_dist command indicates the completion of sequence of commands begun by an allocate_items_dist command. Memory and resources allocated by the allocate_items_dist command and subsequent commands are released, and the log file is closed. An allocate_items_dist command should be paired with a corresponding release_items_dist command.

starting_values_dichotomous ?-items list? ?-use_all? ?-ignore_error?

Tcl

The starting_values_dichotomous computes starting values for the item parameter estimates of items model using a dichotomous model. An allocate_items_dist command must be given before this command can be used. The -items argument is followed by a list of item numbers for which starting values are to be computed. All these items must be modeled using a dichotomous model. If the -items option is not present starting values are computed for all items modeled using a dichotomous model. If the option -use_all is present then all examinees are included in the computation of initial proficiencies used for computing starting values, even examinees who get all items correct or all items incorrect. If the -use_all argument is not present examinees who get all items correct or incorrect are not included in computing the initial proficiencies used in computing the starting values. If the argument -ignore_error is present then the program will continue even if there was an error in computing the starting values, although a warning message will be printed. If the argument -ignore_error is not present the program will terminate if an error occurs in computing the starting values. More information about the starting values is contained in the discussion of the item_3PL_starting_values command in the next section. The starting_values_dichotomous command calls the item_3PL_starting_values command. Currently there is no command to produce starting values for items modeled using a polytomous model. Using the default values assigned to the a-parameters (1) and b-parameters (0) as starting values for polytomously modeled items appears to result in good parameter estimates, at the possible expense of more EM iterations. Starting values for any item can be manually assigned using the item_set_param and item_set_params commands.

ICL Commands

The commands presented in the previous section allow basic control of the program for estimating 3PL model item parameters, and latent variable distributions, including multiple group estimation. For many users the commands presented in the previous section are all that would be needed to accomplish what they want to do with ICL. This section discusses additional features of the ICL command language that allow more control over the operation of the program.

To process commands ICL uses an embedded Tool Command Language (Tcl) interpreter. Tcl is pronounced "tickle". Tcl is a scripting language designed to be embedded within applications in order to act as the command language for the application. There are a basic set of ICL commands written in C++ that are added to the basic Tcl interpreter. In addition, all commands that are part of the Tcl interpreter are available for use as ICL commands. Many of the ICL commands, including all the commands described in the previous section, are actually written in the Tcl language using the more basic commands written in C++. The Tcl source code for the ICL commands written in Tcl, including those discussed in the previous section, is contained in the file icl.tcl provided with the ICL distribution.

There are a few restrictions on the order in which the commands can be given. Most commands require the new_items_dist command be executed before they can be used (the allocate_items_dist command discussed in the previous section calls the new_items_dist command). Exceptions are commands that set default values used by other commands such as set_default_D, set_default_model_dichotomous, set_default_model_polytomous, set_default_prior, and set_missing_resp. Examinee item response data must be assigned using the add_examinee command before commands which compute estimates can be used (the allocate_items_dist or new_items_dist command must be executed before an add_examinee command can be executed).

The format of the command descriptions is the same as that described in the previous section. On the first line of the command description in the right margin is either Tcl or C++, which indicates whether the command was written in Tcl or C++. A source code command written in Tcl can be found in the file icl.tcl that comes with the ICL distribution. The source code for the commands written in C++ can be found in the source file swig_etirm.cpp which comes with the ETIRM distribution and the swig_icl.cpp that come with the ICL source code distribution.

add_examinee responses ?group? ?count?

C++

The add_examinee command adds information for an examinee that is used for parameter estimation. The first argument is a list of integers giving the item responses for the examinee. The number of integers in this list must be the same as the total number of items as defined in a allocate_items_dist command. A zero represents an incorrect response and a one represents a correct response. A negative number indicates the examinee did not respond to the item. The second argument gives the group number to which the examinee belongs. The default value of the second argument if it is not present is 1. The third argument gives a count which indicates the number of times this response pattern should be counted in performing computations. The count can be non-integer. For example, if there were two examinees with the same response pattern in the same group they could be added with two add_examinee commands, or one add_examinee command with a count of 2. The default value of the third argument if it is not present is 1. The add_examinee returns the examinee number associated with the examinee added. The examinee number for the examinee added with the first add_examinee command is 1, etc. This number can be used in other commands which take an examinee number as an argument.

allocate_items_dist nitems ?-models list? ?-models_str string? ?-num_latent_dist_points npoints? ?-num_groups ngroups? ?-latent_dist_range list? ?-unique_points?

Tcl

The allocate_items_dist command is documented in the previous section.

bootstrap_seed seed

C++

Assign a seed for the random number generator used in the bootstrap_sample command. If this command is not used then the random number generator is initialized with an arbitrary seed.

bootstrap_sample

C++

Generate a bootstrap sample of examinees. This command will modify the count associated with each examinee to be the number of times the examinee is included in the bootstrap sample. The examinee_get_count command can be used to return the count assigned to each examinee by the bootstrap_sample command. The counts associated with examinees prior to using the bootstrap_sample command are replaced.

delete_items_dist

C++

The delete_items_dist command indicates the completion of a sequence of commands begun by a new_items_dist command. Memory and resources allocated by the new_items_dist command and subsequent commands are released. A new_items_dist command should be paired with a corresponding delete_items_dist command.

delete_estep obj

C++

The delete_estep command disposes of an E-step object created with the new_estep command. The argument is a variable containing an E-step object. An example of using the delete_estep command is given in the description of the estep_compute command.

dist_get_point cat ?group?

C++

Returns the point value for one category of the discrete latent variable distribution. The first argument is the number of the category for which the point value is returned: 1 for the first (lowest) category, 2 for the second category, etc. The second argument is the number of the examinee group (1, 2, ...) for which the point value is returned. The default group used if the second argument is not given is 1. The third argument is only used if different latent distribution points are used for different examinee groups as specified in the new_items_dist or allocate_items_dist command.

dist_get_points ?group?

C++

Returns a list containing the point values for all categories of the discrete latent variable distribution. The argument gives the examinee group (1, 2, ...) for which the point values should be returned. The default group used when the argument is not given is 1. The third argument is only used if different latent distribution points are used for different examinee groups as specified in the new_items_dist or allocate_items_dist command.

dist_get_prob cat ?group?

C++

Returns the discrete probability for one category of the latent variable distribution for one examinee group. The first argument is the number of the latent variable category for which the probability is returned (1, 2, ...). The second argument is the examinee group (1, 2, ...) for which the probability should be returned. If the second argument is not present a default value of 1 is used.

dist_get_probs ?group?

C++

Returns a list of the discrete probabilities for all categories of the latent variable distribution for one examinee group. The argument is the examinee group (1, 2, ...) for which the probabilities should be returned. If the argument is not present a default value of 1 is used.

dist_mean_sd ?group?

C++

Returns a list containing the mean and standard deviation of the discrete latent variable distribution in the examinee group indicated by the argument (the number of the examinee group-- 1, 2, ...). If the first argument is not present a default value of 1 is used. For example: # find mean and standard deviation of latent variable # distribution in groups 1 and 2 set moments1 [dist_mean_sd 1] set moments2 [dist_mean_sd 2] # print means for groups 1 and 2 to log file puts_log "Means: [lindex $moments1 0], [lindex $moments2 0]" # print standard deviations for groups 1 and 2 to log file puts_log "s.d.'s: [lindex $moments1 1], [lindex $moments2 1]"

dist_scale mean sd ?group?

C++

The dist_scale scales points of the discrete latent variable distribution so the mean and standard deviation of the distribution for the examinee group given by the last argument (the number of the examinee group -- 1, 2, ...) are equal to the values specified by the first and second arguments. If the last argument is not present the default value of 1 is used. If different latent distribution points are used for different groups the points for all groups are transformed to the new scale. A list is returned containing the slope and intercept of the scale transformation.

dist_set_point cat point ?group?

C++

Sets the value of the latent variable for one category of the discrete latent variable distribution in one examinee group. The first argument is the number of the category to set: 1 for the first (lowest) category, 2 for the second category, etc. The second argument is the value that the point for that category should be set equal to. The third argument is a group number of the group for which the point is to be set. The default value of the third argument if it is not present is 1. The third argument is only used if different latent distribution points are used for different examinee groups as specified in the new_items_dist or allocate_items_dist command.

dist_set_points list ?group?

C++

Sets the value of the latent variable for all categories of the discrete latent variable distribution in one examinee group. The first argument is a list giving values that the points of each category should be set equal to. There should be as many elements in the list as there are latent variable categories. The number of latent variable categories is set with the allocate_items_dist command or the new_items_dist command. The third argument is a group number of the group for which the points are to be set. The default value of the third argument if it is not present is 1. The third argument is only used if different latent distribution points are used for different examinee groups as specified in the new_items_dist or allocate_items_dist command.

dist_set_prob cat prob ?group?

C++

Sets the discrete probability for one category of the latent variable distribution in one examinee group. The first argument is the number of the latent variable category for which the probability is set (1, 2, ...). The second argument is the value the probability should be set to. The third argument is the examinee group (the number of the examinee group-- 1, 2, ...) for which the probability should be set. If the third argument is not present a default value of 1 is used. When the probability for a single category is set the remaining probabilities are not standardized so all probabilities sum to one. It is the responsibility of the user to make sure the sum is one after all probabilities have been assigned.

dist_set_probs list ?group?

C++

Sets the discrete probabilities for all categories of the latent variable distribution for one examinee group. The first argument is a list of probabilities which will be assigned to the distribution. The number of elements in the list must be equal to the number of categories in the discrete latent variable distribution as set with the allocate_items_dist or new_items_dist command. The values in the list are standardized to sum to 1. The second argument is the examinee group (1, 2, ...) for which the probabilities should be set. If the second argument is not present a default value of 1 is used.

dist_transform slope intercept

C++

The dist_transform transforms the points of the discrete latent variable distribution to a new scale using a linear transformation given by the the arguments. If different latent distribution points are used for different groups the points for all groups are transformed to the new scale.

dist_unique_points

C++

The dist_unique_points command returns a one if different latent distribution points are used for different examinee groups, as requested in the new_items_dist or allocate_items_dist command, otherwise the command returns zero.

EM_steps ?-max_iter iter? ?-crit d? ?-estim_dist? ?-scale_points? ?-no_print_iter? ?-no_mstep_iter_error? ?-estim_dist_mean_sd? ?-estim_dist_mean?

Tcl

The EM_steps command is documented in the previous section.

estep_compute obj ?compute_post? ?store_post? ?items?

C++

The estep_compute command performs E-step computations using an E-step object created with the new_estep command. The value returned is the logarithm of the marginal posterior density computed using the current item parameter estimates. This is the value the EM algorithm is maximizing. The arguments are positional, so they must appear in the indicated order. The first argument is an E-step object created with the new_estep command. The items used to compute the posterior distribution for each examinee are determined when the E-step object is created. The current item parameter estimates are used for the E-step calculation. If the second argument is non-zero the posterior distributions are computed for each examinee, otherwise posterior distributions previously computed in an estep_compute command are used. If the second argument is not present the examinee posterior distributions are computed (the same as the second argument being non-zero). If the third argument is non-zero the posterior distributions for examinees are stored. The stored posterior distribution for an examinee can be obtained with the examinee_get_posterior command. If the third argument is not present the examinee posterior distributions are not stored (the same as the third argument being zero). The fourth argument is a list of item numbers indicating the items for which the n's and r's used in the next M-step are updated (see Woodruff and Hanson, 1997; Hanson, 1998). If the fourth argument is not present then the n's and r's are updated for all items used to compute the examinee posterior distributions as indicated in the new_estep command. If an empty list is passed as the fourth argument the n's and r's are not updated for any items. The following is an example of how to use the estep_compute command. The example in Section 2.4 provides an illustration of the usefulness of the estep_compute command. # Make a new E-step object and assign it to the variable e. # Items 1, 3, 5-10, 15, and 18-22 will be used to compute # the posterior latent variable distribution for each # examinee in the E-step calculation. set e [new_estep [concat 1 3 [seq 5 10] 15 [seq 18 22]]] # compute E-step storing posterior distributions # for all examinees estep_compute $e 1 1 # print posterior mean (EAP estimate) for # examinee 1 to log file puts_log [examinee_posterior_mean 1] # delete E-step object delete_estep $e Note that the value returned by the estep_compute command is the logarithm of the marginal posterior density at the values of the item parameter estimates, not the loglikelihood. The logarithm of the marginal posterior density is the loglikelihood summed with the logarithm of the prior densities of all item parameters. The loglikelihood for the current item parameter estimates can be computed using the following commands: # Create new E-step object set e [new_estep] # Compute the loglikelihood. The empty list as last # argument to estep_compute indicates that n's and # r's will not be updated for any items. The log of # the prior density is only added to the # loglikelihood for items for which n's and # r's are updated. Thus, the value returned # is the loglikelihood. set loglikelihood [estep_compute $e 1 0 {}] # Print loglikelihood to log file puts_log "Loglikelihood: $loglikelihood\n" # Delete E-step object delete_estep $e

examinee_get_count examineeno

C++

Returns the count for the examinee corresponding to the examinee number given by the first argument. For an explanation of the examinee count see the description of the add_examinee command.

examinee_get_posterior examinee

C++

The examinee_get_posterior command returns a list containing the posterior latent variable distribution for the examinee corresponding to the examinee number given by the argument. This distribution must have been previously stored for the examinee, with a command such as estep_compute $e 1 1.

examinee_get_group examinee

C++

The examinee_get_group command returns an integer giving the group of the examinee corresponding to the examinee number given by the argument. The first group is indicated by a 1, the second group by a 2, etc.

examinee_set_group examinee group

C++

The examinee_set_group command sets the group of the examinee corresponding to the examinee number given by the argument to the group number given by the second argument. The first group is indicated by a 1, the second group by a 2, etc.

examinee_posterior_mean examinee

C++

The examinee_posterior_mean command returns the mean of the posterior latent variable distribution for an examinee -- the expected a posterior (EAP) estimate of examinee proficiency. This distribution must have been previously stored for the examinee, with a command such as estep_compute $e 1 1. The argument is an examinee number for the examinee for which the posterior mean is returned. An example of using the examinee_posterior_mean command is given in the description of the estep_compute command and in the example in Section 2.3.

examinee_set_count examineeno count

C++

Sets the count for the examinee corresponding to the examinee number given by the first argument to the value given by the second argument. For an explanation of the examinee count see the description of the add_examinee command.

examinee_set_posterior examinee list

C++

The examinee_set_posterior command sets the probabilities of the posterior latent variable distribution for the examinee corresponding to the examinee number given by the first argument to the list of probabilities given by the second argument. The number of probabilities in the list given by the second argument must be equal to the number of categories in the discrete latent variable distribution as specified in the new_items_dist or allocate_items_dist command. The probabilities are standardized so they sum to one.

examinee_theta_MLE examinee min_theta max_theta prec itemno

C++

The examinee_theta_MLE command returns a maximum likelihood estimate (MLE) of the latent variable for an examinee based on the examinee item responses and the current item parameter estimates. The first argument is an examinee item number identifying the examinee for which the MLE is returned. The second and third arguments are the minimum and maximum values which the estimate can assume. The fourth argument is a precision representing the length of interval in which MLE is determined to lie. If the fourth argument is not present a value of 0.001 is used. The fifth argument is a list of item numbers identifying the items used to compute the MLE. If the fifth argument is not present the MLE will be computed using all items.

examinee_responses examinee

C++

Returns a list of integers representing an examinee's responses to all items. The argument is an examinee number of the examinee for which the item responses are returned. The list returned contains integers where zero represents a response in the first response category and a response in the highest response category is indicated by an integer equal to the number of response categories minus one. A negative number for an item response indicates the examinee did not respond to the item.

examinee_response_str examinee

C++

Returns a string representing an examinee's responses to all items. The argument is an examinee number of the examinee for which the item responses are returned. The string returned contains characters where zero represents a response in the first response category, a two represents a response in the second response category, etc. The character that represents a missing response is the character assigned using the set_missing_resp command (a period by default). This command is only useful when the number of response categories for all items is less than 10.

examinees_count ?group?

C++

Returns the sum of examinee counts in an examinee group, or across all examinee groups. The count for each examinee is the value assigned when the examinee is added with the add_examinee command. The count for an examinee can also be assigned by the set_examinee_count command or the bootstrap_sample command. The argument is an integer giving the examinee group for which the sum of the examinee counts is to be returned. If the argument is not present, or is equal to zero, the sum of examinee counts across all groups is returned. If the count for each examinee is 1 then the examinees_count command with no argument returns the same number as the num_examinees command.

get_base_group

C++

Returns the number of the group used as the base group when standardizing the latent variable distribution (for instance, when the -scale_points option is specified in the EM_steps command). The base group can be set with the set_base_group command.

get_default_prior_param param

C++

Returns a vector of parameters for the default prior distribution corresponding to the item parameter given by the argument (a, b, or c). The default prior can be set with the set_default_prior command.

get_default_prior_type param

C++

Returns the name of the default prior distribution corresponding to the item parameter given by the argument (a, b, or c). The string returned is either normal (normal distribution), lognormal (lognormal distribution), beta (four-parameter beta distribution), or none (no prior distribution). The default prior can be set with the set_default_prior command.

get_responses line offsets lengths

C++

The get_responses command reads item responses from a string given by the first argument and returns a list of integer item responses (0 corresponding to the first response category, 1 corresponding to the second response category, etc., and -1 indicating no response). The second argument is a list giving the zero-based offset of each item response in the string given by the first argument (the first character in the string is at offset zero). The third argument is a list giving the number of consecutive characters in the string that are to be read to obtain the item response for each item. The number of elements in the lists given by the second and third arguments do not need to be equal to the total number of items as specified in the allocate_items_dist or new_items_dist command. For example: # Response record containing responses to five items beginning in # column 3. The response to fourth item is missing. set line {12010.1} # Variable resp will contain the list # {0 1 0 -1 1} of item responses set resp [get_responses $line {2 3 4 5 6} {1 1 1 1 1}]

get_responses_missing line offsets lengths items

C++

The get_responses_missing command reads item responses for a subset of items from a string given by the first argument and returns a list of integer item responses to all items (0 corresponding to the first response category, 1 corresponding to the second response category, etc., and -1 indicating no response). The second and third arguments are the same as the second and third arguments of the get_responses command. The fourth argument is a list of item numbers for which responses are to be read. The responses to the items indicated by the fourth argument are read from the string given by the first argument. Responses to any items not read from the string are assigned -1 (indicating a missing response).

item_cat_counts itemno ?group?

C++

Returns a list giving the sum of examinee counts in each response category for the item corresponding to the item number given by the first argument. If the second argument is used the counts are return just for examinees in the examinee group indicated. If the second argument is not present, or is equal to zero, the counts are returned for examinees in all examinee groups. The count for each examinee is the value assigned when the examinee is added with the add_examinee command, or the value assigned to an examinee with the set_examinee_count command. If the count for each examinee is 1 the number of examinees who responded in each response category of the item is returned.

item_get_all_params itemno

C++

Returns a list of values of all item parameters for the item corresponding to item number given by the argument. Both fixed and estimated parameters are returned. For the 3PL, 2PL, and 1PL models the list returned contains three elements corresponding to the values of the a-, b-, and c- parameters, respectively. For the 2PL and 1PL models the c-parameter is fixed, and for the 1PL model the a-parameter is fixed. For the GPCM and PCM the list returned contains a a-parameter followed by b-parameters in order of increasing response category. For the PCM the a-parameter is fixed.

item_get_model itemno

C++

Returns a string describing model used for the item corresponding to the item number given by the argument, where 3PL = three-parameter logistic, 2PL = two-parameter logistic, 1PL = one-parameter logistic, GPCM = generalized partial credit model, PCM = partial credit model.

item_get_name itemno

C++

Returns a string containing the name of the item corresponding to the item number given by the argument. Item names are set with the item_set_name or items_set_names command. If the item was not assigned a name the item number (the command argument) is returned.

item_get_param param itemno

C++

Returns the value of the item parameter for the parameter given by the first argument and the item corresponding to item number given by the second argument. The first argument is an integer giving the index of the parameter to return in the list of parameters for the item. For a three-parameter logistic model the indices for the a-, b-, and c- parameters are 1, 2, and 3. For a two-parameter logistic model the indices for the a- and b- parameters are 1, 2. for a one-parameter logistic model the index for the b-parameter is 1. For a generalized partial credit model the index for the a-parameter is 1, and the indices of the b-parameters are 2, 3, etc. For the partial credit model the indices for the b-parameters are 1, 2, etc.

item_get_params itemno

C++

Returns a list of values of all estimated item parameters for the item corresponding to item number given by the argument. For the three-parameter logistic model the list contains the a-, b-, and c- parameters, in that order. For the two-parameter logistic model the list contains the list contains the a-parameter followed by the b-parameter. For the one-parameter logistic model the list contains the b-parameter. For the generalized partial credit model the list contains the a-parameter, followed by the b-parameters in order of increasing response category. For the partial credit model the list contains the b-parameters in order of increasing response category.

item_get_prior_type param itemno

C++

Returns the type of prior distribution (normal, lognormal, beta, or none) used for the parameter given by the first argument for the item corresponding to the item number given by the second argument. The first argument is an integer index giving the position of the parameter in the list of parameters for the item. The index corresponding to each parameter is given in the description of the item_get_param command.

item_get_prior_param param itemno

C++

Returns a list containing the parameters of the prior distribution used for the parameter given by the first argument for the item corresponding to item number given by the second argument. The first argument is an integer index giving the position of the parameter in the list of parameters for the item. The index corresponding to each parameter is given in the description of the item_get_param command. The number of elements in the returned list depends on the prior distribution used for the item: 2 (mean and standard deviation) for the normal and lognormal distributions, 4 (two shape parameters, the lower limit and the upper limit) for the four-parameter beta distribution. If no prior distribution is used for the item an empty list is returned.

item_num_params itemno

C++

Returns the number of estimated parameters for the item corresponding to item number given by the argument.

item_num_resp_cat itemno

C++

Returns the number of response categories (number of possible item responses) for the item corresponding to item number given by the argument.

item_prob_resp itemno response theta

C++

The item_prob_resp returns the probability that an examinee with a latent variable value given by the third argument would give the response given by the second argument to the item corresponding to the item number given by the first argument. The second argument should be an integer corresponding to an item response, where a response in the first response category is 0, a response in the second response category is 1, etc.

item_resp_count itemno ?group?

C++

Returns the sum of the examinee counts for examinees responding to the item corresponding to the item number given by the first argument. If the second argument is used the count is return just for examinees in the examinee group indicated. If the second argument is not present, or is equal to zero, the count is returned for examinees in all examinee groups. The count for each examinee is the value assigned when the examinee is added with the add_examinee command, or the value assigned to an examinee with the set_examinee_count or bootstrap_sample command. If the count for each examinee is 1 the number of examinees who responded to the item is returned.

item_scale_params itemno slope intercept ?ignore_priors?

C++

Transform the scale of the parameters for the item associated with the item number given by the first argument using the latent variable transformation with slope and intercept given by the second and third arguments, respectively. The item_scale_params command returns zero if the parameters were successfully transformed, or one if the scaling would result in one or more parameters having values with zero prior density. If the fourth argument is zero then the command returns a 1 if any transformed parameter for the item has zero prior density, and the item parameters remain unchanged. If the fourth argument is non-zero then the parameters are transformed even if one of the transformed parameters has zero prior density, and the command always returns 0. The default value of the fourth argument if it is not present is zero.

item_set_all_params itemno list

C++

Set the values of all item parameters for the item corresponding to the item number given by the first argument to the values given in the second argument. Values of both fixed and estimated item parameters are set. The order of the parameters in the list given by the second argument is given in the description of the item_get_all_params command. For example: # Set the values of the fixed a and c parameters, and # the estimated b parameter for item 5 # (modeled using the 1PL model) to 1.0, 0.0, and 0.2, respectively. item_set_all_params 5 {1.0 0.0 0.2}

item_set_model itemno model

C++

Sets the model used for the item corresponding to the item number given by the first argument to the model corresponding to the string given by the second argument. The string identifying the model should be equal to either 3PL (three-parameter logistic), 2PL (two-parameter logistic), 1PL (one-parameter logistic), GPCM (generalized partial credit model), or PCM (partial credit model). The model for an item with more than 2 response categories cannot be changed to the 3PL, 2PL, or 1PL model.

item_set_name itemno name

Tcl

The item_set_name command associates a name with an item. The first argument is an item number corresponding to the item for which the name is to be assigned. The second argument is a string giving the name for that item. Item names are only used to label items in output, consequently it is possible to assign names to some items and not others. For items without item names, the item number is used to label the item in output. Item numbers, not item names, are used as arguments in ICL commands to refer to items.

items_set_names names ?itemnos?

Tcl

The item_set_names command associates names with items. The first argument is a list of item names. The second argument is a list giving item numbers corresponding to the list of item names given by the first argument. If the second argument is not present default values of 1, 2, ..., up to the number of elements in the name list are used. The lists given by the first and second arguments must have the same number of elements. Item names are only used to label items in output, consequently it is possible to assign names to some items and not others. For items without item names, the item number is used to label the item in output. Item numbers, not item names, are used as arguments in ICL commands to refer to items. An example of the items_set_names command is # Assign item names to the first five items items_set_names {item20 item21 item22 item23 item24}

item_set_param param itemno value

C++

Set the value of the item parameter given by the first argument for the item corresponding to item number given by the second argument to the value given by the third argument. The first argument is an integer index giving the position of the parameter in the list of parameters for the item. The index corresponding to each parameter is given in the description of the item_get_param command.

item_set_params itemno list

C++

Set the values of all item parameters for the item corresponding to the item number given by the first argument to the values given in the second argument. The order of the parameters in the list given by the second argument is given in the description of the item_get_params command. For example: # Set the values of the a, b, and c parameters for item 5 # (modeled using the 3PL model) to 1.0, 0.0, and 0.2, respectively. item_set_params 5 {1.0 0.0 0.2}

item_set_prior param itemno prior ?list?

C++

Sets the prior distribution for the parameter given by the first argument of the item corresponding to item number given by the second argument. The first argument is an integer index giving the position of the parameter in the list of parameters for the item. The index corresponding to each parameter is given in the description of the item_get_param command. The type of prior distribution is given by the third argument. It must be one of normal (normal distribution), lognormal (lognormal distribution), beta (four-parameter beta distribution), or none (no prior distribution). The parameters of the prior distribution are given in a list as the last argument. The number of prior parameters depends on the prior distribution: two (mean and standard deviation) for normal and lognormal, four (two shape parameters, lower limit, and upper limit) for beta. If none is specified as the prior distribution the last parameter is not needed. The default prior distributions for the item parameters that are used if an item_set_prior command is not present can be set by the -default_prior_a, -default_prior_b, and -default_prior_c options of the options command, or the set_default_prior command. The default prior distributions if the item_set_prior command is not used are presented in the description of the options command. An example of using the item_set_prior command is: # set the prior distribution for the c parameter of item 10 # (modeled using the three-parameter logistic model) to # four-parameter beta with shape parameters 1.5 and 1.5, lower # limit 0.0 and upper limit 0.5. This is a symmetric unimodal # distribution in the interval 0.0 to 0.5 with mode at 0.25. item_set_prior 3 10 beta {1.5 1.5 0.0 0.5}

item_3PL_starting_values ?use_all? ?item_all? ?itemno?

C++

The item_3PL_starting_values computes starting values for the item parameter estimates for items modeled using the three-parameter logistic (3PL), two-parameter logistic (2PL), and one-parameter logistic (1PL) models. If the first argument is non-zero then all examinees are used to compute initial proficiencies used in computing the starting values, even examinees who get all items correct or all items incorrect, and all items are used to compute initial item difficulties used in computing the starting values, even items answered correctly or incorrectly by all examinees. The default value of the first argument if it is not present is zero. If the second argument is non-zero all items are used to compute initial values of examinee proficiency used in computing the starting values, even those for which starting values are not being computed. If the second argument is zero then only items for which starting values are being computed are used to compute initial examinee proficiencies. The default value of the second argument if it is not present is zero. The third argument is a list of item numbers for which starting values are computed. This list must only contain item numbers for items modeled using the 3PL, 2PL, or 1PL models. If the third argument is not present starting values are computed for all items modeled by the 3PL, 2PL, or 1PL models. The value returned is an integer giving the number of items for which minimization procedure used to compute starting values failed -- zero indicates starting values were successfully computed for all items. Starting values are computed by producing a rough estimate of latent proficiency for each examinee based on their item responses using the PROX procedure (Linacre, 1994). Nonlinear regressions with these proficiencies as independent variables and item responses as dependent variable are used to get starting values for the item parameters. For more details on how the starting values are calculated see the C++ source file Start3PL.h in the ETIRM distribution.

items_set_prior item_param prior_dist ?prior_params? ?itemno?

Tcl

The items_set_prior command sets the prior distribution for one item parameter for a set of items. The first argument is an integer index giving the position of the parameter in the list of parameters for the item. The index corresponding to each parameter is given in the description of the item_get_param command. The second argument is the type of prior distribution - either normal, lognormal, beta, or none corresponding to a normal distribution, a lognormal distribution, a four-parameter beta distribution, or no prior, respectively. The third argument is a list containing the parameters of the prior distribution. For the normal and lognormal distribution the parameters are the mean and variance. For the four-parameter beta distribution the parameters are the two shape parameters, the lower limit, and the upper limit. This argument is optional because it is not needed if none is specified as the type of prior. The last argument is a list of item numbers identifying the items for which the prior distribution of the indicated parameter should be set. If the last argument is not present then the prior is set for all items. It is assumed that the parameter index given by the first argument identifies the same parameter for all items.

mstep_dist estep group

C++

Performs the M-step calculation for a discrete latent variable distribution for one examinee group. The first argument is an E-step object created using the new_estep command. The second argument gives the number of the group ( 1, 2, ...) for which the M-step calculation giving estimates of the probabilities in the latent variable distribution is performed.

mstep_item_param ?-items itemno? ?-no_max_iter_error?

Tcl

The mstep_item_param command performs the M-step calculation for item parameter estimates. The maximum relative difference in parameters from previous iteration to current iteration is returned. The -items option specifies a list of item numbers for which the M-step calculation is performed. If this option is not present the M-step calculation is performed for all items. If the -no_max_iter_error option is present the maximum number of iterations being exceeded in the M-step optimization for an item is not considered an error, otherwise if the maximum number of M-step iterations for an item is exceeded the calculation stops at the point where the error occurred.

mstep_items ?ignore? ?itemno?

C++

The mstep_items command performs the M-step calculation for item parameter estimates. The first argument is an integer flag. If the first argument is non-zero then the maximum number of iterations in the M-step being exceeded is not treated as an error, otherwise if the maximum number of M-step iterations is exceeded processing stops at the point where the error occurred. The second argument is a list of item numbers for which the M-step calculation is performed. If the second argument is not present the M-step calculation is performed for all items. Zero is returned if the calculation is successful. If the first argument is non-zero, and the only error that occurs is that the maximum number of M-step iterations is exceeded, then the negative of number of items for which maximum number iterations was exceeded is returned. If the first argument is zero and an error occurs, or an error other than exceeding the maximum number of M-step iterations occurs, then the item number for which error occurred is returned and processing is stopped at the point of the error.

mstep_max_diff

C++

Returns the maximum relative difference between parameters in the current and previous EM iteration computed the last time the mstep_items was executed. The maximum is over all parameters for all items.

mstep_max_iter itemno max

C++

Sets the maximum number of iterations used in the M-step optimization procedure for the item corresponding to the item number given in the first argument to the value given by the second argument. The default maximum number of M-step iterations used for each item when this command is not given is 150. The maximum number of iterations set with this command also applies to the optimization procedure used to compute the starting values in item_3PL_starting_values command.

mstep_message itemno

C++

Returns the message generated in the last call to mstep_items from the optimization procedure used for an item. The argument is the item number for which the message is returned. The possible integers returned and their associated messages are: 0 -- Optimal solution found, terminated with gradient small. 1 -- Terminated with gradient small, solution is probably optimal. 2 -- Terminated with step size small, solution is probably optimal. 3 -- Lower point cannot be found, solution is probably optimal. 4 -- Iteration limit exceeded. 5 -- Too many large steps, function may be unbounded. -1 -- Analytic gradient check requested, but no analytic gradient supplied. -2 -- Analytic hessian check requested, but no analytic hessian supplied. -3 -- Illegal dimension. -4 -- Illegal tolerance. -5 -- Illegal iteration limit. -6 -- Minimization function has no good digits. -7 -- Iteration limit exceeded in line search. -20 -- Function not defined at starting value. -21 -- Check of analytic gradient failed. -22 -- Check of analytic hessian failed.

mstep_latent_dist estep_obj ?-estim_base_group? ?-scale_points?

Tcl

The mstep_latent_dist command performs the M-step calculation for the probabilities of the discrete latent variable distributions. The maximum relative difference in distribution probabilities across points from the previous iteration to current iteration is returned. The first argument is an E-step object created with the new_estep command. If the optional -estim_base_group argument is present the probabilities of the latent variable distribution are estimated for the base group. If the -estim_base_group argument is not present only probabilities of the latent variable distribution for examinee groups other than the base group are estimated. If the optional -scale_points argument is used the points of latent variable distribution are linearly transformed so that the mean and s.d. in base examinee group are 0 and 1. This scale transformation is also applied to the parameter estimates for all items to put them on the same scale.

mstep_latent_dist_moments estep_obj ?-mean_only? ?-estim_base_group?

Tcl

The mstep_latent_dist_moments command performs the M-step calculation to estimate the mean and standard deviation of the discrete latent variable distributions for all examinee groups except the base group for which the mean and standard deviation are fixed (unless the -estim_base_group option is used). This command modifies the points of the latent variable distribution for all groups except the base group to be consistent with an estimated mean and standard deviation in that group. The probabilities of the latent variable distributions are not changed. The maximum relative difference in distribution means from the previous iteration to current iteration is returned. The first argument is an E-step object created with the new_estep command. If the optional -mean_only argument is present only the mean is estimated, not the standard deviation. If the optional -estim_base_group argument is present the mean and standard deviation of the base group are estimated. This command requires that different latent distribution points be used for different examinee groups as specified in the new_items_dist or allocate_items_dist command.

new_items_dist nitems ?npoints? ?ngroups? ?models? ?range_list? ?unique_points?

C++

The new_items_dist command is used to specify the number of items to be modeled, and optionally, the number of points in the discrete latent variable distribution, the number of examinee groups, whether a dichotomous or polytomous model is to be used for each item, the minimum and maximum points of the discrete latent variable distribution, and whether unique points are used for the latent distributions in each group. Memory is allocated by the new_items_dist for the number of items and number of discrete latent variable points specified. The number of items and number of points in the discrete latent variable distribution can only be changed by the new_items_dist command. A new_items_dist command must be given before most other commands can be used. The first argument gives the total number of items to be modeled. In subsequent commands items are identified by item number. If the number of items specified is n then item numbers 1 through n are used to refer to these items in subsequent commands. The second argument is the number of categories used for the discrete latent variable distribution. The default value if the second argument is not present is 40. The third argument is the number of groups of examinees in the data that are sampled from different populations. The default value if the third argument is not present is 1. Multiple group estimation is used if the number of groups is greater than 1, and in this case a group identifier must be indicated for each examinee. The fourth argument is a list containing an integer for each item. The integer 1 corresponding to an item means the item is modeled using a dichotomous model. If the integer corresponding to an item is greater than 1 that means the item is a polytomous item with that number of response categories modeled using a polytomous model. If the fourth argument is not present the models for all items are assumed to be dichotomous. The fifth argument is a list giving the minimum and maximum points of the discrete latent variable distribution. The first element of the list is the minimum point and the second element of the list is the maximum point of the latent variable distribution. The default minimum and maximum points of the latent variable distribution are -4 and 4 if the fifth argument is not present. The sixth argument is an integer which if nonzero indicates different latent distribution points are used for different examinee groups. If the sixth argument is zero the same set of latent variable points is used for all examinee groups. The default value of the sixth argument if it is not present is zero. The new_items_dist command initializes the IRT model used for each item and the prior distributions of all item parameters to default values. The model and prior distributions used as defaults can be set using the set_default_model_dichotomous, set_default_model_polytomous, and set_default_prior commands. If the set_default_model_dichotomous command is not used the default model for dichotomous items is the three-parameter logistic model. If the set_default_model_polytomous command is not used the default model for polytomous items is the generalized partial credit model. The default prior distributions for the item parameters are described in the documentation of the allocate_items_dist command. The values of the discrete latent variable points and probabilities are set to initial values. There is a set of probabilities for each examinee group. There is one set of points for all examinee groups unless the fifth argument is nonzero, in which case there is a different set of points for each examinee group. The points are equally spaced in the range given by the fourth argument. The weights are chosen so the resulting discrete distribution approximates a standard normal distribution. The initial probabilities and points are the same across groups. The points can be changed with the dist_set_point and dist_set_points commands. The probabilities can be changed by the dist_set_prob and dist_set_probs commands.

new_estep ?items?

C++

Creates and returns a new E-step object to use for E-step computations. The optional argument is a list of item numbers indicating the items to be used in the E-step calculation to compute examinee posterior latent variable distributions. The estep_compute command is used to perform an E-step computation using an E-step object created with the new_estep command. An E-step object created with the new_estep command should be disposed of with the delete_estep command when it is no longer needed. Examples of using the new_estep command is given in the description of the estep_compute command and the example given in Section 2.4.

normal_dist_points npoints min max ?mean? ?sd?

C++

Returns a list of points of a discrete distribution with the number of points given by first argument. The second and third arguments are minimum and maximum points for a standard normal distribution. The list of points returned are transformed equally spaced points between the second and third argument, inclusive. The transformation is computed so that the mean and standard deviation computing using these points with the probabilities returned by normal_dist_prob (using the same second and third arguments) equals the mean and standard deviation given by the fourth and fifth arguments. Thus, the minimum and maximum points returned will differ from the second and third argument if the fourth and fifth arguments differ from zero and one, respectively. If the fourth argument is not present the default value of zero is used, and if the fifth argument is not present the default value of one is used.

normal_dist_prob npoints min max

C++

Returns a list of probabilities of a discrete distribution that approximates a standard normal distribution with the number of discrete points given by the first argument, the minimum point given by the second argument, and the maximum point given by the third argument.

num_examinees

C++

The num_examinees command returns the number of examinees for which data have been assigned using the add_examinee command.

num_groups

C++

The num_groups command returns the number of examinee groups as set with the allocate_items_dist or new_items_dist command.

num_items

C++

The num_items command returns the number of items as set with the allocate_items_dist or new_items_dist command.

num_latent_dist_points

C++

The num_latent_dist_points command returns the number of points in the discrete latent variable distribution as set with the allocate_items_dist or new_items_dist command.

options ?-D d? ?-missing_resp resp? ?-base_group group? ?-default_model_dichotomous model? ?-default_model_polytomous model? ?-max_iter_optimize max? ?-default_prior_a prior? ?-default_prior_b prior? ?-default_prior_c prior? ?-default_dist_range list?

Tcl

The options command is documented in the previous section.

output ?-log_file file_name? ?-no_print?

Tcl

The output command is documented in the previous section.

print ?-item_param? ?-latent_dist? ?-latent_dist_moments? ?-no_heading? ?-items itemno? ?-format string? ?-item_model?

Tcl

The print command is documented in the previous section.

puts_log ?-nonewline? string

Tcl

The puts_log command writes a string to the log file. If the argument -nonewline is present a newline character is not written after the end of the string. The -nonewline argument must be the first argument if it is present.

read_examinees file resp_format ?group_format?

Tcl

Documentation for the read_examinees command is given in the previous section.

read_examinees_channel fileID resp_format ?group_format?

Tcl

The read_examinees_channel command reads examinee responses to the items, and optionally an examinee group, from a an open I/O channel (e.g., file or process pipeline). The first argument is an identifier for an I/O channel returned by the Tcl open command. The remaining arguments are the same as those for the read_examinees command. This command functions the same as the read_examinees command except that it takes an open I/O channel rather than a file name as the first argument.

read_examinees_missing file form_format itemNos resp_format ?group_format? ?group_conv?

Tcl

The read_examinees_missing command reads examinee responses to the items, and optionally an examinee group, from a file. While the read_examinees command requires responses to all items be read for every examinee, this command allows reading of examinee records containing responses to only some of the items. The responses to the items not read for an examinee are assumed missing. The first argument is the name of the file to read examinee responses from. A set of items for which a group of examinees have responses is called a form. The second argument consists of a format list which indicates which columns in each record contain a form identifier for each examinee. The syntax of the format list is explained in the description of the read_examinees command. The form identifier can be any string, it does not need to be an integer. If the second argument is an integer then that integer is taken as the form identifier for all records in the file. This can be useful when responses to the different forms are contained in separate files. In this case each read_examinees_missing command is reading a file containing only one form so a form identifier for each examinee is not needed. The third and fourth argument are names of Tcl arrays, where the indices of the array are the form identifiers (Tcl arrays can be indexed by general strings in addition to integers). Note the names of the arrays are used as arguments. The array name should not be preceded by a dollar sign when used as the third or fourth argument. The third argument is the name of an array containing lists of item numbers for which responses are to be read for examinees taking each form. The fourth argument is the name of an array containing format lists used to read examinee responses for each form. The number of elements in the arrays whose names are passed as the third and fourth arguments should be equal to the number of forms. A '1' or '0' indicates a correct or incorrect response to the item, respectively. If the examinee did not respond to the item, for example if they did not receive the item, a '.' (period) should be given as the item response (the character which indicates a m