knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) library("conquestr")
conquestr has three main functions:
These functions allows users to include 'ACER ConQuest' within their R workflow. This is particularly useful for users of the Mac OS X version (and Windows console) version of 'ACER ConQuest' which does not support ploting.
This vignette demonstrates how to use the package built-in demonstration files to:
First, ensure you have the most current version of ConQuest. Version > 5.17.4 is required. If you are unsure, check ConQuest on the ACER Shop. You will also need to install the conquestr library:
install.packages("conquestr") library("conquestr")
You must pass the ConQuestCall
function at least two pieces of information: the install location of ConQuest and a valid syntax file.
conquestr has included syntax files that can be used to run a model and test other package functions.
A default syntax file will be called is you do not explicitly provide one.
conquestr will search for a valid installation of 'ACER ConQuest' unless the executable is explicitly declared.
The search locations are (in order):
%ProgramFiles%\ACER ConQuest\ConQuestConsole.exe
and Mac OS X: /Applications/ConQuest/ConQuest
).# if you don't provide a syntax file, using the argumenmt `cqc=`, then the in-built demo syntax file will be run. ConQuestCall()
# the following output is produced: ConQuest build: Mar 10 2021 <TYPE> Version This version expires <DATE> submit <PATH>conquestr/extdata/conquestabout.cqc; =>dir; <PATH> =>about; Developed by Australian Council for Educational Research University of California,Berkeley Your key: <KEY> Expires: <DATE> <TYPE> Build: <DATE> Version: 5.17.4 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.
For more information see 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 creates a system file that is read into the R object myExSys
.
# set up oldWd <- getwd() myTmpDir <- tempdir() setwd(myTmpDir) file.copy(from = c( system.file("extdata", "ex1.cqc", package = "conquestr"), system.file("extdata", "ex1.dat", package = "conquestr"), system.file("extdata", "mysysfile.cqs", package = "conquestr") ), to = myTmpDir) # run ConQuest # ConQuestCall is not run here, as it requires a local install of ConQuest # ConQuestCall(cqc = file.path(myTmpDir, "ex1.cqc"), stdout = NULL) # searches for valid install of CQ myExSys <- ConQuestSys(myCqs = file.path(myTmpDir, "mysysfile.cqs")) # see the content of the sysfile str(myExSys) # tidy up file.remove( list.files(myTmpDir, all.files = TRUE, full.names = TRUE, pattern = "^myi|^myS|ex1"), recursive=TRUE ) setwd(oldWd)
The above example created a system file. 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
- The raw response data including information about the raw and key response to each item.gYData
- The regression data included in the estimation.gAllCaseEstimates
- the latent ability estimates (e.g., PVs, WLEs).matrixout
is available for several commands and will ensure data objects are saved to the system file - these can be found in gMatrixList
. For example:matrixsampler
and the option matrixout
creates the objects matrixSampler_fit
, matrixSampler_raw
, matrix_userfit
(the simulated data) in gMatrixList
.itanal
, and the option matrixout
creates the objects *_counts
, *_itemstats
, *_ptbis
, *_abilitymeansd
(where "*" is a user defined prefix declared in the option matrixout
) in gMatrixList
.estimate
and the option matrixout
... for more information see the manualUsers 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)
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.