Introduction to conquestr

Call ConQuest and run a syntax file

First, ensure you have the most current version of ConQuest. Version > 4.34.1 is required. If you are unsure, check the ConQuest forums, or contact support

install.packages("conquestr")
library("conquestr")

conquestr has some in-built ‘ACER ConQuest’ syntax files. You can use these, or your own file. To call ‘ACER ConQuest’ you will need two pieces of information: the location of your syntax file and the location of the ‘ACER ConQuest’ executable.

# if you don't provide a syntax file, using the argumenmt `cqc=`, then the in-built demo syntax file will be run. 
  # This simply sets up some default settings and runs the command `about;`.

myConQuestExe<- file.path("/Applications", "ConQuest", "ConQuest") # update file path to your install location

ConQuestCall(cqInstallLocation = myConQuestExe) 

# the following output is produced:

ConQuest build: Sep 23 2019
Professional Version
This version expires 1 September 2020
submit /Library/Frameworks/R.framework/Versions/3.6/Resources/library/conquestr/extdata/ConQuestAbout.cqc;
=>set conquestr=yes;
=>dir;
/Users/<USER>/conquestr/conquestr
=>about;
Developed by
    Australian Council for Educational Research
    University of California, Berkeley

Your key: acb-123-1234
Expires: 1 September 2020

Professional Build:  Sep 23 2019
Version: 4.33.1

Programmers
    Ray Adams, Margaret Wu, Greg Macaskill, Sam Haldane, Xiao Xun Sun, Dan Cloney
End of Program

When you use ConQuestCall to call ‘ACER ConQuest’ and run a syntax file, some options are set by default. The same options can be set within ‘ACER ConQuest’ by using the set command (set progress = yes, exit_on_error = yes, storecommands = yes, warnings = no; which is syntactically the same as using the helper function set conquestr = true; ). WARNING - this will make it easy to overwrite output as you will not be prompted or warned. To turn off these settings your syntax file must explicitly change these using the set command.

When calling ‘ACER ConQuest’ from R, the ConQuest working directory will default to the current R working directory. This makes it easy to write portable syntax using relative paths. If you need ‘ACER ConQuest’ to use a different working directory, set it in your syntax file.

The next example runs a small analysis and generates a system file in your current working directory.

ConQuestCall(cqc = system.file("extdata", "ConQuestTest.cqc", package = "conquestr"), cqInstallLocation = myConQuestExe) # update file path to your install location

Read in a ConQuest system file

The above example created a system file, in the current working directory. Alternatively, there is an inbuilt example of a system file.

conquestr can read in a system file, using the ConQuestSys function. This function returns a list that includes the response data, parameter estimates, and other data objects created by ‘ACER ConQuest’. These lists can be optionally coerced into R data frames.

# if no argument is provided to ConQuestSys, the example system file is read in by default.
myCqs<- ConQuestSys()

You can see the data objects available within the object (e.g., str(myCqs)), and some useful objects will be:

• gResponseData this is the ‘ACER ConQuest’ object gResponseData - the raw response data including information about the raw and key value for each item.
• gYData this is the ‘ACER ConQuest’ object gYData - the regressor data included in the estimation.
• gAllCaseEstimates this is the ‘ACER ConQuest’ object gAllCaseEstimates - the estimates (e.g., PVs, WLEs) on the latent traits from the estimation
• if you have used the command matrixsampler and the option matrixout, see also matrixSampler_fit, matrixSampler_raw, matrix_userfit for the simulated data.
• data from itanal, when using the option matrixout, is found in gMatrixList which is a list of matrices, e.g. *_counts, *_itemtotrestcor, *_ptbis, *_pvmeansd where "*" is a user defined prefix declared in the option matrixout.

Note - to get some ‘ACER ConQuest’ objects, including itanal objects, you must use the option matrixout = x (where x is a prefix used in naming the matrix objects) in the relevant command in ‘ACER ConQuest’. These matrix objects are not created, and therefore saved in the system file, by default.

Users can search the names of objects in the system file using the helper function searchConQuestSys:

# search for objects named history in myCqs
searchConQuestSys("history", myCqs)
# not run: > [1] "gHistoryFileName" "gHistory"         "gCommandHistory"