DOI: 10.6084/m9.figshare.6561743.v2
title: 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: <b>DESCRIPTION</b><b><br></b>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 -- <i>/outputs</i> subdirectory) are found in <i>SPARS.zip</i>, while PDF copies of the analysis outputs that are cited in the manuscript as supplementary material are found in the relevant <i>supplement_*.pdf. </i><b><br></b><b>Note: </b>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).<b><br></b><b>BIBLIOGRAPHIC INFORMATION</b><b><br></b><b>Repository citation</b>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.<b><br></b><b>Manuscript citation</b>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. <i>Journal of Pain </i>[in press].<br><b>Manuscript abstract</b>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.<br><br><b>USING DOCKER TO RUN THE SPARS ANALYSIS SCRIPTS</b>These instructions are for running the analysis on your local machine.<br>You need to have <i>Docker </i>installed on your computer. To do so, go to <i>docker.com </i>(https://www.docker.com/community-edition#/download) and follow the instructions for downloading and installing Docker for your operating system. Once <i>Docker</i> has been installed, follow the steps below, noting that <i>Docker</i> commands are entered in a terminal window (<i>Linux</i> and <i>OSX/macOS</i>) or command prompt window (<i>Windows</i>). <i>Windows</i> users also may wish to install <i>GNU Make </i>(http://gnuwin32.sourceforge.net/downlinks/make.php) (required for the `make` method of running the scripts) and <i>Git </i>(https://gitforwindows.org/) version control software (not essential). <br><b>Download the latest image</b>Enter: `docker pull kamermanpr/docker-spars:v1.1.2`<br><b>Download the repository</b>Download the compressed <i>zip</i> file from <i>GitHub</i> (<i>kamermanpr/SPARS </i>(https://github.com/kamermanpr/SPARS), or from <i>figshare</i> [DOI: 10.6084/m9.figshare.6561743 (https://doi.org/10.6084/m9.figshare.6561743)]. <br><b>Run the container</b>Enter: `docker run --name spars -d -p 8787:8787 -e USER=user -e PASSWORD=password kamermanpr/docker-spars:v1.1.2`<br><b>Login to RStudio Server</b>- Open a web browser window and navigate to: `localhost:8787`<br>- Use the following login credentials: - Username: _user_ - Password: _password_ <b><br></b><b>Prepare the SPARS directory</b>On the <b>Files</b> tab in the bottom right panel of <i>RStudio</i>, click on the <b>'Upload'</b> button, navigate to the downloaded <i>zip</i> file, and upload the file (it will self extract).<br><br>The <i>SPARS</i> directory comes with the outputs for all the analysis scripts in the <i>/outputs</i> directory (<i>html</i> and <i>md</i> 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 <i>zip</i> file with the data. Using the directory tree in the <b>Files</b> tab of <i>RStudio</i>, open the <i>SPARS</i> directory. Repeat the upload procedure described above, but upload the zipped data file we supplied you with into the <i>SPARS</i> directory.2. In the <i>SPARS</i> directory, double-click on the <i>SPARS.Rproj</i> file, and follow the prompts (<i>RStudio</i> will reload).3. Clean the <i>/outputs</i> and <i>/figures</i> directories by entering `make clean` in the <b>Terminal</b> tab in bottom right panel of <i>RStudio</i>.<br><b>Run the SPARS analysis scripts</b>To run all the scripts (including the data cleaning scripts), enter `make` in the <b>Terminal</b> tab.<br><br>To run individual RMarkdown scripts (<i>\*.Rmd</i> 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 <b>Terminal</b> tab; - Enter `source('0A-clean-data.R')` and then `source('0B-clean-data.R')` in the <b>Console</b> tab in bottom left panel of <i>RStudio</i>. - Open <i>0A-clean-data.R</i> and <i>0B-clean-data.R</i> scripts through the <b>File</b> tab, and then click the <b>'Source'</b> button on top of the panel on the top left of <i>RStudio</i> for each script. 2. Run the individual script using one of the following methods: - Enter `make outputs/.html` in the <b>Terminal</b> tab; - Open the relevant <i>\*.Rmd</i> file through the <b>File</b> tab, and then click the <b>'knit' </b>button on the top of the panel on the top left of <i>RStudio</i>. <br><b>Shutting down</b>Once done, log out of <i>RStudio</i> and enter the following into a terminal to stop the <i>Docker</i> container: `docker stop spars`. If you then want to remove the container, enter: `docker rm spars`. If you also want to remove the <i>Docker</i> image you downloaded, enter: `docker rmi kamermanpr/docker-spars:v1.1.2`<br>