.top-container { background-color: #f1f1f1; padding: 30px; text-align: center; }
.header { padding: 10px 16px; background: #FFFFFF; color: #000000; }
.content { padding: 16px; }
.sticky { position: fixed; top: 0; width: 100%; }
.sticky + .content { padding-top: 102px; }
.back-to-top { position: fixed; right: 2rem; bottom: 2rem; }
</style>This documentation briefly introduces some basic lab management for LEEPS lab, UCSC. It explains how to recruit, expand, and maintain our subject pool. How to use Orsee. It also explains how we can use lab software to conduct economic experiments.
This section introduces how we should maintain our subject pools for our lab. There are three steps we need to do:
Step 1: Find the subjects' information. We need to use MyUCSC to download students' names and email addresses to send them emails to invite them to register into our Orsee system.
Step 2: Clean the data. The data we find from step 1 cannot be used directly for sending emails. We must first clean the date using some R code.
Step 3: Send out mass emails for registration invitations. See step 3 below for details of how we do it.
Acquiring Subjects Information
First of all, go to "My UCSC". On the top, change “student homepage” to “faculty homepage”. See below:
Then click on “Faculty Center”:
Then From “My schedule”, find out the class number. Go to “search all class rosters”, enter that class number (be careful with the terms, search the right terms you are looking for, otherwise there is not result). You’ll see the list of all students in that class. On the same page, you will find a option to download students' information as an excel sheet, click that to download it. See below:
Now you have downloaded the data you need. Go to next section "Data Cleaning" to find the R code to clean the data.
Data Cleaning
First of all, you need to re-save all the downloaded data to .csv file. Then follow the R code below to clean the data.
# First, read your .csv data in R (two examples below):
dta_1 <- read.csv(file = 'D:/zwang/Research/Leeps Lab/2023-winter-recruiting/data/all_data/Econ1.csv')
dta_2 <- read.csv(file = 'D:/zwang/Research/Leeps Lab/2023-winter-recruiting/data/all_data/Econ2.csv')
# After uploading your data to R, combine them together:
dta <- rbind(dta_1,dta_2)
# Next, exclude duplicated students:
dta_unique <- dta[!duplicated(dta$ID), ]
# You don't need all the columns:
dta_unique <- dta_unique[c(-1,-2,-7,-8,-9,-11,-12,-13)]
dta_1 and dta_2 in the above code are data of Econ 1 and Econ 2. Of course, you will find a lot more classes than that. Say, you've found 100 classes from all different majors in total; each class has, on average, 200 students. In this case, your dta_unique will have approximately (but less than, due to excluding duplicated id) 20,000 unrepreated students.
The following R explains how to divide them into smaller .csv files that contain only 300 students each. When sending mass emails (see next section), you might want to constrain the number of emails to send out each day to 300, otherwise, google might automatically categorize the emails as spam.
# Your dta_unique contains tens of thousands of students. First, shuffle all your students id:
dta_unique <- dta_unique[sample(nrow(dta_unique)),]
# Then save the first 300 students into another separate .csv file and call it students_s1:
students_s1 <- dta_unique[1:300,]
# Right below the above code, add your own name and email (in this example, I add myself Zhaoqi as one of the receivers), Kristian's email, and leeps lab's email into the .csv file:
library(tidyverse)
students_s1 <- students_s1 %>%
add_row(ID = 1000000, First.Name="Zhaoqi", Middle.Name="", Last.Name = "Wang",
Level="", Gender..Pronoun="", Email.Address="zwang153@ucsc.edu")
students_s1 <- students_s1 %>%
add_row(ID = 1000000, First.Name="Kristian", Middle.Name="", Last.Name = "Lopez Vargas",
Level="", Gender..Pronoun="", Email.Address="klopezva@ucsc.edu")
students_s1 <- students_s1 %>%
add_row(ID = 1000000, First.Name="Leeps", Middle.Name="", Last.Name = "Lab",
Level="", Gender..Pronoun="", Email.Address="leeps@ucsc.edu")
# After adding the above three new contacts, save the .csv file:
write.csv(students_s1,"D:/zwang/Research/Leeps Lab/2023-winter-recruiting/data/combined_data/students_s1.csv", row.names = FALSE)
The above code explains steps to divide the first 300 students into a new .csv file. Of course, you need to repeat that many times until you divide all your dta_unique into many separate .csv files. Those files, named as "students_s1", "students_s2", "students_s3", and so on, are the .csv you need to use to send out mass emails each day.
Note that adding your own email is necessary because you need to receive the email everyday yourself to check if the email was sent successfully. Including Kristian and Leeps as well so that they are both informed.
Now, you have all the data ready. Follow the steps in next section to send out mass emails everyday.
Recruiting New Subjects via Email
We use Qualtrics Website to send out the emails. Click the link and you need to login using the following user id and password:
ID: leeps
Password: "You know it..."
Follow the steps to prepare and send the emails.
1. Prepare Emails
1.1 Go to Directories
1.2. Click on "Create a List"
1.3. Assign it a name describing the current number of batch
1.4. Choose Upload a File
1.5. Choose the right delimiter
1.6. For the First/LastName and Email fields, choose manually their respective categories and click on Upload the File.
1.7. Click on Add your contacts.
2. Sending the emails
2.1. Go to the Test project from Qualtrics.
2.2. Click on Distributions.
2.3. Click on Emails.
2.4. Click on Compose email.
2.5. Fill the requested fields with its respective information.
2.6. Choose the contacts you would like to send the email to.
2.7. Choose when to send the email and send the email.
This section introduces some basic usage of the Orsee system. The first part explains creating a new experiment and inviting subjects for the sessions. The last three parts explain some valuable tools to help us resolve potential problems when using Orsee.
Create a New Experiment
1. Login to Leeps Lab ORSEE.3. Then Click Experiments_My Experiments:
2. If you are starting a new project with a new game, click “Add new experiment” at the center top of “My Experiment” box. Then you will reach the following pic.
You can enter “Internal name” and “Public name” for your new project’s game and click “Add”.
3. If you want to run more experiments for existing projects (game), then in step 1, click the name of that project. Here I use None Bayesian Game as an example. Click “None Bayesian Game” and go to the following picture.
Here, you can see how many experiments you’ve done for this project and the time of each experiment. If you plan to do another new experiment for this project, at “Sessions” box, click “Create new” to go next step.
4. Set the time you want for this experiment. For “Send session reminder email”, set “when as many participants registered as needed, else manually” so that it will send remind email to registered participants.
“Required participants” is how many subjects you need for this experiment.
“Reserve participants” is 2 or 3 extra participants in case required ones are not all coming. (We might need to reserve more participants after the pandemic)
“Signup deadline (hours before start)”: set this “0” so that they can register and come anytime they want even if it’s 1 min before the game.
“Session status”: when you are done with the above settings, set this “live”. (default is “planned”, but set it to “live”).
Then click “Add”.
5. Then go back to step 3, which is the main page for None Bayesian Game. Go to “Participants” box and click “Send invitation emails”, which shows below.
6. Now you’ve reached the following figure. Don’t worry about anything, just click the very last button.
You are all set!
Orsee "Options"
"Options" in Orsee provide many tools for us to manage the Orsee system. Click that and go to the next a few sections to see what problems it can help us with.
What If the Email Queue Got Stuck?
Go to "Options" and find the following "System Setup".
Click "Regular Tasks (cron)".
Then from the figure below, find "process_mail_queue" and click "Run Now". This might help force the email to be sent out.
Other Useful Options
Go to "Option", under "Communication and site content" (see figure below), we can change public content (what participants see from the orsee public website). Also, "Email Templates" is also helpful, we can use that to change email contents for each experiments. You can change the experiment type (online or in-person), change what you want to say in the reminder email, and so on.
Contact Orsee
ORSEE was written by Professor Ben Greiner. If we encounter some Orsee issues, we have tried our best and still could not fix the bugs by ourselves. We can try to contact him.
This section introduces some basic codes you need to use to run your game in lab's computers. The first subsection explains how to do it assuming you have already uploaded your game to the lab. The following subsections explains how to upload your game to lab's computer from LEEPS Github repository.
How to Start a Session on lab's Computers
Here I assume you have already uploaded your game from your local computer to the lab's main computer.
First of all, you need to start your game on Lab's main computer. Please use the following code to execute.
Open a command prompt and type the following code. Please note that the folder you use to store your game in the lab's computer might be different. Here, I use Zhaoqi's folder (zhaoqi-mb) as an example.
source zhaoqi-mb/bin/activate
cd Zhaoqi-MB/markets
unset DATABASE_URL
OTREE_PRODUCTION=1 otree runprodserver
Now, your game should be running on the main computer. Next, on google chrome, open loalhost:8000, and click Rooms Leeps Lab. Your game is running on the main computer, but you need to turn on other computers and let them open the links of your game so that subjects can play the game on their own assigned computers. Follow the next step.
Turn on another command prompt and type the following code:
cd Dropbox/Admin/
./launch_otree_local.sh 1 – 8
What the above code does is to launch other computers in the lab and computer 1 - 8 will open your games' links automatically (here, I assume your game requires 8 subjects). Of course, if you want to use certain computers, type this code: ./launch_otree_local.sh 1, 2, 3, 4, 5, 6, 8, 9, which means you are using computer 1 - 6, and 8, 9, but not using computer 7. You can choose whichever computers you want by specifying the computer numbers in this way.
If you have not upload your game to the lab's computer. Please follow the next sections to learn how to do it.
How to Add a New Game to Lab's Computers
Assuming there is a new project and it’s in a repo in the GitHub of LEEPS lab. First, open the terminal and type the following code. Here, I assume you are going to clone your game from Github to the folder "Zhaoqi-MB/markets".
cd Zhaoqi-MB/markets
git clone https://github.com/Leeps-Lab/<repo_name>.git ./<name_for_the_new_folder>
Open setting.py by:
nano settings.py
Save the edit by pressing Ctrl+O.
Close the editor by pressing Ctrl+X.
Add new entry under the list of SESSION_CONFIGS:
dict (
name= '<new_folder_name>',
display_name = '<Any Name You Like>',
num_demo_participants = <num of players>,
app_sequence = ['<new_folder_name>'],
config_file = '<demo.csv>',
),
Reset the database within the virtual environment (See how to run your game in virtual environment in the next section).
Working Inside The Virtual Environment
Getting into virtual environment: First, open the terminal:
source zhaoqi-mb/bin/activate
Then Start server:
cd Zhaoqi-MB/markets
unset DATABASE_URL
OTREE_PRODUCTION=1 otree runprodserver
Reset Database:
otree resetdb
If it shows error or something. Try
del db.sqlite3
Working Outside The Virtual Environment
Please refer to the previous section and ensure the terminal is not under virtual environment.
Update an existing game
Once you have done your edit to your game's program and have pushed the changes to Leeps Github repo. Do the following: In the command prompt, type the following. Again, I assume you uploaded your game to the folder "Zhaoqi-MB/markets".
cd Zhaoqi-MB/markets
cd <game_folder_name>
git pull