Analysis scripts and supplementary files: Was that painful or non-painful? The Sensation and Pain Rating Scale (SPARS) performs well in the experimental context.

DESCRIPTION

This repository contains analysis scripts (with outputs), figures from the manuscript, and supplementary files for two studies on the properties of the Sensation and Pain Rating Scale (SPARS). All analysis scripts (and their outputs -- /outputs subdirectory) are found in SPARS.zip, while PDF copies of the analysis outputs that are cited in the manuscript as supplementary material are found in the relevant supplement_*.pdf.

Note: Participant consent did not provide for the publication of their data, and hence neither the original nor cleaned data have been made available. However, we do not wish to bar access to the data unnecessarily and we will judge requests to access the data on a case-by-case basis. Examples of potential use cases include independent assessments of our analyses, and secondary data analyses. Please contact Peter Kamerman (peter.kamerman@gmail.com), Dr Tory Madden (torymadden@gmail.com, or open an issue on the GitHub repo (https://github.com/kamermanpr/SPARS/issues).

BIBLIOGRAPHIC INFORMATION

Repository citation

Kamerman P, Madden V, Bellan V, Catley M, Russek L, Camfferman D, Moseley L. Analysis scripts and supplementary files: Was that painful or non-painful? The Sensation and Pain Rating Scale (SPARS) performs well in the experimental context. Figshare, 2018. DOI: 10.6084/m9.figshare.6561743.

Manuscript citation

Madden V, Kamerman P, Bellan V, Catley M, Russek L, Camfferman D, Moseley L. The Sensation and Pain Rating Scale (SPARS) performs well in the experimental context. Journal of Pain [in press].

Manuscript abstract

In experiments on pain perception, participants are frequently exposed to non-painful and painful stimuli, yet the conventional pain-rating scales lack a non-painful range and a clear point of transition from non-painful to painful events. The Sensation and Pain Rating Scale (SPARS) is a 0-100 scale that assesses the full stimulus intensity range, extending from no sensation (rating: -50) to worst pain imaginable (rating: +50), and it explicitly identifies pain threshold (rating: 0). Here, we tested the SPARS in two experiments using laser heat stimuli to establish its stimulus-response characteristics (Experiment 1, n = 19, 13 stimulus intensities applied 26 times each across a 1-4J range), and to compare it to 0-100 scales that access non-painful (0: no sensation, 100: painful) and painful (0: not painful, 100: worst pain imaginable) events (Experiment 2, n = 7, 9 stimulus intensities applied 36 times each across a 1.5-4.5J range). Despite high inter- and intra-individual variation, we found a reasonably consistent curvilinear stimulus-response relationship (the curve flattens around pain threshold), with stable response characteristics across the range of the scale. SPARS ratings tended to be lower than the 0-100 pain rating scale in the noxious stimulus intensity range, and greater than the 0-100 non-painful sensation scale in the non-noxious stimulus range; likely reflecting differences in scale dimensionality. The SPARS overcomes limitations of scale range inherent in conventional pain rating scales and, as such, is well suited to experimental studies in which distinguishing between painful and non-painful events is a priority.

USING DOCKER TO RUN THE SPARS ANALYSIS SCRIPTS

These instructions are for running the analysis on your local machine.

You need to have Docker installed on your computer. To do so, go to docker.com (https://www.docker.com/community-edition#/download) and follow the instructions for downloading and installing Docker for your operating system. Once Docker has been installed, follow the steps below, noting that Docker commands are entered in a terminal window (Linux and OSX/macOS) or command prompt window (Windows). Windows users also may wish to install GNU Make (http://gnuwin32.sourceforge.net/downlinks/make.php) (required for the `make` method of running the scripts) and Git (https://gitforwindows.org/) version control software (not essential).

Download the latest image

Enter: `docker pull kamermanpr/docker-spars:v1.1.2`

Download the repository

Download the compressed zip file from GitHub (kamermanpr/SPARS (https://github.com/kamermanpr/SPARS), or from figshare [DOI: 10.6084/m9.figshare.6561743 (https://doi.org/10.6084/m9.figshare.6561743)].

Run the container

Enter: `docker run --name spars -d -p 8787:8787 -e USER=user -e PASSWORD=password kamermanpr/docker-spars:v1.1.2`

Login to RStudio Server

- Open a web browser window and navigate to: `localhost:8787`

- Use the following login credentials:

- Username: _user_

- Password: _password_

Prepare the SPARS directory

On the Files tab in the bottom right panel of RStudio, click on the 'Upload' button, navigate to the downloaded zip file, and upload the file (it will self extract).

The SPARS directory comes with the outputs for all the analysis scripts in the /outputs directory (html and md formats). However, should you wish to run the scripts yourself, there are several preparatory steps that are required:

1. Acquire the data. The data required to run the scripts have not been included in the repo because participants in the studies did not consent to public release of their data. However, the data are available on request from Tory Madden (torymadden@gmail.com) or Peter Kamerman (peter.kamerman@gmail.com). We will send you a zip file with the data. Using the directory tree in the Files tab of RStudio, open the SPARS directory. Repeat the upload procedure described above, but upload the zipped data file we supplied you with into the SPARS directory.

2. In the SPARS directory, double-click on the SPARS.Rproj file, and follow the prompts (RStudio will reload).

3. Clean the /outputs and /figures directories by entering `make clean` in the Terminal tab in bottom right panel of RStudio.

Run the SPARS analysis scripts

To run all the scripts (including the data cleaning scripts), enter `make` in the Terminal tab.

To run individual RMarkdown scripts (\*.Rmd files)

1. Generate the cleaned data using one of the following methods:

- Enter `make data-cleaned/SPARS_A.rds` and then `make data-cleaned/SPARS_B.rds` in the Terminal tab;

- Enter `source('0A-clean-data.R')` and then `source('0B-clean-data.R')` in the Console tab in bottom left panel of RStudio.

- Open 0A-clean-data.R and 0B-clean-data.R scripts through the File tab, and then click the 'Source' button on top of the panel on the top left of RStudio for each script.

2. Run the individual script using one of the following methods:

- Enter `make outputs/.html` in the Terminal tab;

- Open the relevant \*.Rmd file through the File tab, and then click the 'knit' button on the top of the panel on the top left of RStudio.

Shutting down

Once done, log out of RStudio and enter the following into a terminal to stop the Docker container: `docker stop spars`. If you then want to remove the container, enter: `docker rm spars`. If you also want to remove the Docker image you downloaded, enter: `docker rmi kamermanpr/docker-spars:v1.1.2`