Introduction to conquestr

Dan Cloney

2019-02-22

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 allow R users to run ‘ACER ConQuest’ from within their R workflow. With access to the ‘ACER ConQuest’ data objects, the user can do secondary analysis and produce custom plots. 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 ConQuest and run a syntax file

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

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

ConQuest 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: Jul  9 2018
Professional Version
This version expires 1 January 2019
submit /Path/to/ConQuestAbout.cqc;
=>set warnings=no;
=>set echo=no;
/Path/to/workingdir
Version: 4.26.0
Professional Build:  Jul  9 2018
Your key: abc-123-1234
Expiry date: Expires: 1 January 2019
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 run your entire workflow form a single project directory 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’. In a future version of conquestr, some of the data objects will be optionally coerced to 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:

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.