# Introduction to conquestr

#### 2020-08-10

conquestr currently has two main features. It can can call ‘ACER ConQuest’ and run a syntax file, and it can read ‘ACER ConQuest’ system files (sometimes call a state file) to make all of the ‘ACER ConQuest’ data objects available in R. These features allows users to include ‘ACER ConQuest’ within their R workflow and to undertake secondary analysis and visualisation. This is particularly useful for users of the Mac version or command line version of ‘ACER ConQuest’ which does not support creating plots.

This vignette demonstrates how to use the built-in demo files to:

• Call ‘ACER ConQuest’ and run a syntax file
• Read in a system file and access data objects

## 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
=>set conquestr=yes;
=>dir;
/Users/<USER>/conquestr/conquestr
Developed by
Australian Council for Educational Research
University of California, Berkeley

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"