A server to host studies and host study data.
Project description
PsyServer
A server to host your online studies on.
PsyServer is a simple, easy to setup server on which you can host your online studies safely and conveniently without committing to a certain framework to code the experiments. Eliminate the need to put excessive time into setting up backends and servers!
Setup
To setup a fully functional server to host studies on, you will require following things:
- A host machine to run the server on
- Installing PsyServer
- Get a domain (optional)
- Setup HTTPS (optional)
- Run the Server
Host machine
PsyServer Setup
PsyServer comes as a python package, meaning that installing it is as easy as installing a python package!
# 1. create psyserver folder
mkdir server
cd server
# 2. set up conda environment (optional)
conda create -n psyserver python=3.11
conda activate psyserver
# 3. install package
pip install psyserver
# 4. create example config/structure
psyserver init
# 5. configure server
# open psyserver.toml with your editor of choice, e.g. vim
vim psyserver.toml
# 6. run server
psyserver run
Domain Name
HTTPS
To setup up a https server, you can use a reverse proxy or setup the uvicorn instance running
Running setup
Systemd
Configuration
The server is configured in the file psyserver.toml
.
This file has to be in the directory from which you call psyserver run
.
The configuration has two groups:
- psyserver
- uvicorn
psyserver config
[psyserver]
studies_dir = "studies"
data_dir = "data"
Here you can configure following fields:
studies_dir
: path to directory which contains studies. Any directory inside will be reachable via the url. E.g. a study in<studies_dir>/exp_cute/index.html
will have the url<host>:<port>/exp_cute/index.html
.data_dir
: directory in which study data is saved. E.g. data submissions to the url<host>:<port>/exp_cute/save
will be saved in<data_dir>/exp_cute/
. Has to be different fromstudies_dir
.
uvicorn config
[uvicorn]
host = "127.0.0.1"
port = 5000
log_level = "info"
This configures the uvicorn instance runnning the server. You can specify the host
, port
and https.
For all possible keys, go to the uvicorn settings documentation.
How to save data to psyserver
Participant data sent to the server needs to adhere to a certain format.
We recommend using jquery to post the data.
Generally, data is sent to /<study>/save
.
Save as json
// example data
participant_data = {
id: "debug_1",
condition: "1",
experiment1: [2, 59, 121, 256],
// ...
};
// post data to server
$.ajax({
url: "/exp_cute/save",
type: "POST",
data: JSON.stringify(participant_data),
contentType: "application/json",
success: () => {
console.log("Saving successful");
// success function
},
}).fail(() => {
console.log("ERROR with $.post()");
});
Note that you need to call JSON.stringify
on your data. Without this, you will get an unprocessable entity
error.
Save as csv
If you want to save your data as .csv
, you can call /<study>/save/csv
.
The transmitted json
object is required to have following parameters:
id
: The participant id, used as a filename.trialdata
: A list of dict-like objects. The keys of the first row of this list is used to determine the csv header. If new keys are encountered, an422 - unprocessable entity
error will be raised.fieldnames
: A list of strings containing the names . Keys encountered in trialdata will be saved in this order. This field is useful if you have varying keys intrialdata
, and do not want to modify the first entry to have all keys.
Example without fieldnames
// example data
participant_data = {
id: "debug_1",
trialdata: [
{ trial: 1, time: 120230121, correct: true },
{ trial: 2, time: 120234001, correct: false },
{ trial: 3, time: 120237831, correct: true },
// ....
],
};
// post data to server
$.ajax({
url: "/exp_cute/save/csv",
type: "POST",
data: JSON.stringify(participant_data),
contentType: "application/json",
success: () => {
console.log("Saving successful");
// success function
},
}).fail(() => {
console.log("ERROR with $.post()");
});
Will be saved as <data_dir>/exp_cute/debug_1_CURRENTDATETIME.csv
:
trial,time,correct
1,120230121,true
2,120234001,false
3,120237831,true
Example with fieldnames
This
// example data
participant_data = {
id: "debug_1",
trialdata: [
{ trial: 1, time: 120230121, correct: true },
{ trial: 2, time: 120234001, correct: false, extra: "field" },
{ trial: 3, time: 120237831, correct: true },
// ....
],
fieldnames: ["trial", "time", "correct", "extra"],
};
// post data to server
$.ajax({
url: "/exp_cute/save/csv",
type: "POST",
data: JSON.stringify(participant_data),
contentType: "application/json",
success: () => {
console.log("Saving successful");
// success function
},
}).fail(() => {
console.log("ERROR with $.post()");
});
Will be saved as <data_dir>/exp_cute/debug_1_CURRENTDATETIME.csv
:
trial,time,correct,extra
1,120230121,true,,
2,120234001,false,field
3,120237831,true,
Development
Setup
# 1. set up conda environment
conda create -n psyserver python=3.11
conda activate psyserver
# 2. clone
git clone git@github.com:GabrielKP/psyserver.git
cd psyserver
# 3. install in editor mode
pip install -e .
Testing
# normal test
pytest . -v
# coverage
coverage run -m pytest
# html report
coverage html
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for psyserver-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6d2a5f07731ca0ef5ed50d28987dbd928b0714ab6ab32bf7a8f87694e6bba05e |
|
MD5 | 29ca0ac642fc1897884ce9065c536555 |
|
BLAKE2b-256 | 466ad6234fd0097ae7166594cf9b4bd0e0c6771a8aa9e21b88cb9f7331653e3a |