README.md

In jasp-stats/jasptools: Helps preview and debug JASP analyses

jaspTools

R package which aids developers with writing JASP analyses.

Installation

You can install the R package with the use of remotes:

install.packages("remotes")
remotes::install_github("jasp-stats/jaspTools")

Note: On some macs, it seems to be hard to build the dependency "data.table" from source resulting in the error message "clang: error: unsupported option '-fopenmp'". One hack to get around this is to select no when asked to install the package from source. This will install an older version of data.table without openmp support, which suffices for jaspTools. Alternatively, you might want to upgrade clang.

After loading jaspTools with library(jaspTools), you need to call setupJaspTools(). This is required once after every reinstall of jaspTools.

Functionality

At the moment jaspTools has three classes of functions. Each of these functions has documentation you may view by the usual syntax, e.g., ?runAnalysis.

The general classes are:

1. Modifying jaspTools' settings

• viewPkgOptions: views options in the package
• setPkgOption: change an options in the package (e.g., what module you are working on)

After setupJaspTools() retrieves all the necessary dependencies (packages, html, data files), the paths to a number of these dependencies are stored inside of the pkgOptions. You will generally not need to change them. However, what you must usually do is tell jaspTools what modules you are working on (unless your working directory already points to a module):

setPkgOption("module.dirs", c("/path/to/module1", "/path/to/module2"))

jaspTools will use these to locate R functions, tests, etc. The module(s) that you specify are automatically reinstalled every time you change your R, NAMESPACE or DESCRIPTION files.

2. Running JASP analyses

• runAnalysis: run a JASP analysis
• view: view output of a JASP analysis
• analysisOptions: create options used by runAnalysis

Obtaining options

There are three general procedures to obtaining the options to run an analysis with in jaspTools.

Procedure 1

The first procedure uses the .qml files to create option lists. These lists will almost always require further editing.

Example

#create default options
options <- analysisOptions("BinomialTest")

#we want to perform the binomial test on 'contBinom'
options[["variables"]] <- "contBinom"
runAnalysis("BinomialTest", dataset="debug.csv", options=options)

Procedure 2

And so the second procedure might be preferred. You can set the options to your liking in JASP and then save the .jasp file (it may contain several analyses). You can then let jaspTools read the .jasp file to extract the options from.

Example

#fetch all the options from all analyses in a .jasp file
options <- analysisOptions("~/path/to/file.jasp")

#we want to use the options of the first analysis (note that you may omit the analysis name argument)
runAnalysis(dataset="debug.csv", options=options[[1]])

Procedure 3

The third procedure uses syntax generated by Qt and doesn't require you to save the .jasp file, but instead can be done in real-time. To use this enable "Log to file" in JASP > Preferences > Advanced > Logging options. Press on "Show logs" and then run the analysis you're interested in in JASP. Once you've set the analysis options to your liking go to the log directory. There will be multiple log files. Search for the set of most recent "Engine .log" files. Then go to "*Engine 1.log" (it's usually in the first engine unless you were running multiple analyses at the same time) and scroll to the bottom, under "Engine::receiveAnalysisMessage:" you will find a json string. Copy the json, including the "{" and "}" and insert this into analysisOptions.

Example

#create options from the Qt json string
options <- analysisOptions('{
   "dynamicModuleCall" : "",
   "id" : 1,
   "jaspResults" : true,
   "name" : "BinomialTest",
   "options" : {
      ".meta" : {
         "variables" : {
            "containsColumn" : true
         }
      },
      "VovkSellkeMPR" : false,
      "confidenceInterval" : false,
      "confidenceIntervalInterval" : 0.950,
      "descriptivesPlots" : false,
      "descriptivesPlotsConfidenceInterval" : 0.950,
      "hypothesis" : "notEqualToTestValue",
      "plotHeight" : 320,
      "plotWidth" : 480,
      "testValue" : "0.5",
      "variables" : [ "contBinom" ]
   },
   "perform" : "run",
   "revision" : 1,
   "rfile" : "",
   "title" : "Binomial Test",
   "typeRequest" : "analysis"
}')
runAnalysis("BinomialTest", dataset="debug.csv", options=options)

jaspTools comes bundled with all the datasets from JASP, so you may simply refer to them by name (e.g., "debug.csv"). It is not necessary to use a JASP dataset (such as the debug.csv file we showed in the examples), however, you may provide any data.frame to the dataset argument of the runAnalysis function.

3. Testing JASP analyses

• testAll: test all analyses
• testAnalysis: test a specific analysis
• manageTestPlots: validate a new plot or inspect differing test plots
• makeTestTable: transform the output of a JASP table to short, testable list

To ensure that no aspects of JASP are accidentally broken, we use unit testing. These tests check if all tables still produce the same results, plots can be made, errors are caught, etc. If an analysis is changed, it's a good idea to check that no unit test returns an error. To this purpose jaspTools offers convenience functions for testing.

To create unit tests you can read this guide.

Known limitations:

• Click actions in the browser are not supported (e.g., "save as")
• State is ignored

jasp-stats/jasptools documentation built on May 6, 2024, 1:07 p.m.