7.8 KiB
Data Storage
There are two very different kinds of data storage: data stored in memory and data stored permanently. Data stored permanently exists even after the browser running jsPsych closes, typically in a database or in a file on a web server. Data stored in memory exists only as long the browser window running jsPsych is open.
jsPsych has many features for interacting with data stored in memory, but relatively few for permanent data storage. This is a deliberate choice, mainly because there are dozens of ways that data could be stored permanently and this strategy avoids locking in one particular solution. However, saving data permanently is obviously a crucial component of any experiment, and this page contains a few suggestions on how to accomplish permanent data storage.
Interacting with data in memory
Storing data permanently as a file
This is one of the simplest methods for saving jsPsych data on the server that is running the experiment. It involves a short PHP script and a few lines of JavaScript code. This method will save each participant's data as a CSV file on the server.
This method uses a simple PHP script to write files to the server:
<?php
// the $_POST[] array will contain the passed in filename and data
// the directory "data" is writable by the server (chmod 777)
$filename = "data/".$_POST['filename'];
$data = $_POST['filedata'];
// write the file to disk
file_put_contents($filename, $data);
?>
The file_put_contents($filename, $data) method requires permission to write new files. An easy way to solve this is to create a directory on the server that will store the data and use the chmod command to give all users write permission (chmod 777) to that directory. In the above example, I append the directory data/ to the filename, and that directory is writable.
To use the PHP script, the JavaScript that runs jsPsych needs to send the filename and filedata information. jQuery has an easy to use method that enables JavaScript<->PHP communication. Here's an example:
function saveData(filename, filedata){
$.ajax({
type:'post',
cache: false,
url: 'save_data.php', // this is the path to the above PHP script
data: {filename: filename, filedata: filedata}
});
}
// call the saveData function after the experiment is over
jsPsych.init({
// code to define the experiment structure would go here...
on_finish: function(data){ saveData("filename.csv", jsPsych.data.dataAsCSV()) }
});
To use this in an actual experiment, it would be important to tie the filename to some unique identifier like a subject number.
Storing data permanently in a MySQL database
The ideal solution for storing data generated by jsPsych is to write it to a database.
There are dozens of database options. MySQL is one of the most popular relational databases, is free to use, and relatively easy to install. This page will assume that you have a MySQL database installed on your server that is hosting the jsPsych experiment, and that your server is able to execute PHP code.
Step 1
To communicate with a MySQL database, you will need a server-side script, such as a PHP script. The following script should work for all jsPsych data. Copy the code below into a PHP file and give it an appropriate name (e.g. savedata.php). Put the PHP file on your server in a convenient location.
<?php
// Submit Data to mySQL database
// Josh de Leeuw, August 2012
// Usage:
// You need to POST the following variables to the script (e.g. using jQuery.ajax)
// "table": name of the mysql table to insert data into
// "json": json-encoded object that contains the data
// "opt_data": an associative array of additional variables to write into each row (e.g. subject ID)
//
//
//
// EDIT THE FIRST LINE OF CODE BELOW TO CONNECT TO YOUR DATABASE
//
// The script you link should contain the following two lines:
//
// $dbc = mysql_connect('localhost', 'username', 'password');
// mysql_select_db('databasename', $dbc);
//
include('database_connect.php');
// You should not need to edit below this line
function mysql_insert($table, $inserts) {
$values = array_map('mysql_real_escape_string', array_values($inserts));
$keys = array_keys($inserts);
return mysql_query('INSERT INTO `'.$table.'` (`'.implode('`,`', $keys).'`) VALUES (\''.implode('\',\'', $values).'\')');
}
// get the table name
$tab = $_POST['table'];
// decode the data object from json
$trials_obj = json_decode($_POST['json']);
// get the optional data (decode as array)
$opt_data = json_decode($_POST['opt_data'], true);
$opt_data_names = array_keys($opt_data);
// go through each element of the trials object to see if there is data
// (some plugins may not have data associated with them)
$trials = $trials_obj[0];
for($i=1; $i<count($trials_obj); $i++)
{
if(count($trials_obj[$i])>0){
// if there is data, merge that data into the $trials array
$trials = array_merge($trials, $trials_obj[$i]);
}
}
// this outputs the trials array as a string. Useful for debugging in the JavaScript console.
var_dump($trials);
// for each element in the trials array, insert the row into the mysql table
for($i=0;$i<count($trials);$i++)
{
$to_insert = (array)($trials[$i]);
// add any optional, static parameters that got passed in (like subject id or condition)
for($j=0;$j<count($opt_data_names);$j++){
$to_insert[$opt_data_names[$j]] = $opt_data[$opt_data_names[$j]];
}
$result = mysql_insert($tab, $to_insert);
}
// confirm the results
if (!$result) {
die('Invalid query: ' . mysql_error());
} else {
print "successful insert!";
}
?>
Step 2
To use the above PHP script, you'll need to provide the credentials for your MySQL database. The PHP script is expecting the credentials to be stored in a separate PHP file called 'database_connect.php', located in the same directory as the PHP script. This file should look like:
<?php
$dbc = mysql_connect('localhost', 'username', 'password');
mysql_select_db('databasename', $dbc);
?>
Replace the username and password strings with your database credentials, and replace the databasename string with the name of the database you are connecting to. For example, if my username is 'josh', my password is 'abc123', and the database is 'myresearch' then the file should look like:
<?php
$dbc = mysql_connect('localhost', 'josh', 'abc123');
mysql_select_db('myresearch', $dbc);
?>
Step 3
To use this PHP script, you need to invoke it from JavaScript code within your experiment page. Here's an example of how to do that.
// data parameter should be either the value of jsPsych.data()
// or the parameter that is passed to the on_data_update callback function for the core library
// jsPsych.data() contains ALL data
// the callback function will contain only the most recently written data.
function save_data(data){
var data_table = "my_experiment_table"; // change this for different experiments
$.ajax({
type:'post',
cache: false,
url: 'path/to_php/file.php', // change this to point to your php file.
// opt_data is to add additional values to every row, like a subject ID
// replace 'key' with the column name, and 'value' with the value.
data: {
table: data_table,
json: JSON.stringify(data),
opt_data: {key: value}
},
success: function(output) { console.log(output); } // write the result to javascript console
});
}
Note that you'll need to change the script above to reference the table in your mysql database that will store the data, the path to the PHP file created in step 1, and change the opt_data line to include any data you want to append to the table, such as a subject ID (or remove this line entirely if you have no additional data).