Actors: Actors are the simulated users on the website that the participant believes are real.
Posts: These are the simulated posts that the simulated actors have "posted"/"made", which appear on the timeline/feed.
Notifications, or actors' simulated responses to a participant's behavior on the platform: These are simulated behaviors from actors in response to a research participant's behavior. For example: if a participant posts a picture, you may simulate other actors liking, viewing, or commenting on their post. This component of the simulation reinforces the realism of the platform and keeps the user engaged. Specifically, there are three types of actors' behaviors.
Liking a participant's post or comment (called: ‘like’)
Reading a participant's post or comment (called: ‘read’)
Commenting on a participant's post (called: ‘reply’)
How to define the simulation components
These components are defined in the csv files found in the project file directory /input.
Below is a breakdown of each csv, their columns, and a description of what simulation component the file defines.
Note: If you change any simulation content involving pictures (ex: actors' profile pictures or post pictures), you will need to change the CDNvalue in the.envfile. See the row with variable nameCDNin the table on the Additional simulation components page for more information.
How to edit the csv files in Google Sheets (Recommended)
Import the desired csv file by navigating to File > Import > Upload File in the header of a new Google Sheet file.
When prompted, designate where you would like to import the csv file. We recommend having a single Google Sheet file with 5 sheets (one for each csv file) for easy use and for easy collaboration with other researchers.
When you are done editing the csv files, you will need to download each csv sheet and replace the corresponding existing one in the project file directory /inputwith your new one, ensuring the name of the file is still the same.
How to edit the csv files in Microsoft Excel
Import the desired csv file by navigating to Data > From text/CSV > Select File in the header.
When prompted on how to load the data, choose the follow values:
File Origin: 65001: Unicode (UTF-8)
Delimiter: Comma
Then click 'Load'. This will load the content of the csv files with emojis and other values.
When you save the file, save the file as a CSV UTF-8 (Comma delimited) *.csv file. To do this, go to File > Save As > Select CSV UTF-8 (Comma delimited) (*.csv).
input/actors.csv
The actors.csv file defines the simulation actors. One row in the csv file corresponds to one actor.
To define an actor, go to the actors.csv file. For each actor, add a new row, and define the following fields under their respective columns:
username is the unique username of the actor. This username is used to associate posts and behaviors with the actor.(required field)
Note: No 2 actors can share the same username.
name is the actor's display name. (optional)
gender is the actor's gender. (optional)
age is the actor's age. (optional)
location is the actor's location. (optional)
bio is the actor's bio. (optional)
picture is the file path/ file name of the actor's profile photo, relative to the folder /profile_pictures. See below for more information:
Place all actor profile photos into the /profile_pictures folder. When filling out the actors.csv file, the value that is inputted into the 'picture' column for an actor should exactly match the file path and file name of the same actor's profile photo, relative to the folder /profile_pictures. See the current csv file for examples.
The Truman template currently has 76 profile photos in the /profile_pictures folder and more to choose from in the subfolder /profile_pictures/unused.
class can be used as a label for experimental purposes. For example, you can label certain actors as "bully" or "victim". (optional)
The Truman project base template currently defines 76 actors.
input/posts.csv
The posts.csv file defines the basic content of the simulation posts (such as the caption text, picture, actor, etc.). Simulation posts are associated with actors (the actor who creates the post). One row in the csv file corresponds to one post.
To define a post, go to the posts.csv file. For each post, add a new row, and define the following fields under their respective columns:
id is the unique identifier id of the post. These are numerical values. They could be any arbitrary number, but the base template has assigned posts with ids sequentially starting from 0. (required field)
Note: No 2 posts can share the same id.
body is the caption text of the post. It is displayed under the post's photo on the Truman Platform, similar to Instagram. (required field)
picture is the file path/ file name of the post's photo, relative to the folder /post_pictures. (required field) See below for more information:
Place all post photos into the /post_pictures folder. When filling out the posts.csv file, the value that is inputted into the 'picture' column for a post should exactly match the file path and the file name of the same post's photo, relative to the folder /post_pictures. See the current csv file for examples.
The Truman template currently has about 280 photos in this folder and more to choose from in the subfolder /post_pictures/unused.
actor is the username of the actor who "posts" this post. This value must exactly match a username value in /input/actors.csv. (required field)
likes is the # of likes this post is simulated to have. If a value is not given, then a random value will be generated for the post. (optional)
time is the timestamp the post should be simulated to have been posted. This timestamp is defined in reference to the moment the participant joined the website. It can be defined as before or after the participant joined using the format (+/-)HH:MM. (required field)
For example:
-12:30 will simulate the post to have been posted [12] hours [30] minutes before the participant joined the website.
62:31 will simulate the post to appear [62]hours and [31] minutes after the participant joined the website.
condition indicates which experimental condition this post should be displayed in. If this value is left blank, this post will be displayed in all experimental conditions. Otherwise, this post will be displayed only participants in the defined experimental condition. Ensure that the value here exactly matches one of the experimental conditions labels as defined in the .env file variable EXP_CONDITIONS_NAMES (see here for more info).
class can be used as an internal label for researcher. It is not used in the database. For example, you can label certain posts as "bully" or "victim". (optional)
Note: the comments on a post are not defined here but in input/replies.csv.
input/replies.csv
The replies.csv file defines the comments on the simulation posts. One row in the csv file corresponds to one comment.
To define a comment on a post, go to the replies.csv file. For each comment, add a new row, and define the following fields under their respective columns:
id is the unique identifier id of the comment. These are numerical values. They could be any arbitrary number, but the base template has assigned comments with ids sequentially starting from 0. (required field)
Note: No 2 comments can share the same id.
body is the text of the comment. (required field)
actor is the username of the actor who "posts" this comment. This value must match a username value in /input/actors.csv exactly. (required field)
postID is the ‘id’ of the post that the comment will appear on. This value must match a id value in /input/posts.csv exactly. (required field)
likes is the # of likes this comment is simulated to have. If a value is not given, then a random value will be generated for the comment. (optional)
time is the timestamp the comment should be simulated to have been posted, relative to the moment the participant joined the website. It can be defined as before or after the participant joined using the format (+/-)HH:MM. (required field)
For example:
-12:30 simulates the comment's posting time to be 12 hours and 30 minutes before the participant joined the website
62:31 simulates the comment's posting time to be 62 hours and 31 minutes after the participant joined the website
When defining comments, ensure that comments always appear "after" a post is made, for continuity purposes. So for example, if a post is simulated to appear at 04:10 (4 hours and 10 minutes after a participant creates their account), all comments on this post should be simulated to appear after 04:10 (i.e. times after 04:10).
condition indicates which experimental condition this comment should be displayed in. If this value is left blank, this comment will be displayed in all experimental conditions. Otherwise, this comment will be displayed only participants in the defined experimental condition. Ensure that the value here exactly matches one of the experimental conditions labels as defined in the .env file variable EXP_CONDITIONS_NAMES (see here for more info).
class can be used as a label for experimental purposes. It is not used in the database. For example, you can label certain comments as "bully" or "victim". (optional)
input/notifications (read, like).csv
The notifications (read, like).csv file defines the read and likeactor responses to a participant's post or comment on the platform. One row in the csv file corresponds to one response.
This file is named "notifications" because participants receive notifications of the actor's behavior when they happen.
To define a behavior, go to the notifications (read, like).csv file. For each behavior, add a new row, and define the following fields under their respective columns:
NOTE: For each row, only define userPostID or userReplyID (not both). This is because each row corresponds to only one actor response.
userPostID is the id indicating which participant's post the actor should perform the behavior on. (required field, mutually exclusive with userReplyID)
This is a numerical value, where 0 corresponds to the participant's first post, 1 corresponds to the participant's second post, and so on.
OR
userReplyID is the id indicating which participant's replythe actor should perform the behavior on. (required field, mutually exclusive with with userPostID)
This is a numerical value, where 0 corresponds to the participant's first reply, 1 corresponds to the participant's second reply, and so on.
type ('read' or 'like') is the type of actor response to the participant's post or comment.
actor is the username of the actor who performs this response/behavior. This value must match a username value in /input/actors.csv exactly.
Note: There is an actor called generic-joe defined in the actors.csv. You may use this actor for multiple 'read' rows to indicate and signal many people have read their post, since this actor will not appear in the profile photos of the notification (see below).
time is the timestamp the behavior should be simulated to happen. This timestamp is defined in reference to when the participant made the post or comment. Therefore, it is always positive, using the format (+)HH:MM. (required field)
For example:
00:04 (and userPost is 0, and type is 'like') simulates the actor to read the participant's first post 4 minutes after it has been posted.
condition indicates which experimental condition this notification should be displayed in. If this value is left blank, this notification will be displayed in all experimental conditions. Otherwise, this notification will be displayed only participants in the defined experimental condition. Ensure that the value here exactly matches one of the experimental conditions labels as defined in the .env file variable EXP_CONDITIONS_NAMES (see here for more info).
class can be used as a label for experimental purposes. It is not used in the database. For example, you can label certain comments as "bully" or "victim". (optional)
input/notifications (reply).csv
The notifications (reply).csv file defines the reply behaviors of actors in response to a participant's post on the platform.
This file is named "notifications" because participants receive notifications of the actor's behavior when they happen.
To define a reply behavior, go to the notifications (reply).csv file. For each reply, add a new row, and define the following fields under their respective columns:
id is the unique identifier id of the comment. These are numerical values. They could be any arbitrary number, but the base template has assigned comments sequentially starting from 0. (required field)
Note: No 2 comments can share the same id.
userPostID is the id indicating which participant's post the actor should reply to. (required field)
This is a numerical value, where 0 corresponds to the participant's first post, 1 corresponds to the participant's second post, and so on.
body is the text of the comment.
actor is the username of the actor who "posts" this comment. This value must match a username value in /input/actors.csv exactly.
time is the timestamp the comment should be simulated to be posted on the post, defined in reference to when the participant made the post. Therefore, it is always positive, using the format (+)HH:MM. (required field)
For example:
00:04 simulates the actor to comment on the participant's post 4 minutes after it has been posted.
condition indicates which experimental condition this notification should be displayed in. If this value is left blank, this notification will be displayed in all experimental conditions. Otherwise, this notification will be displayed only participants in the defined experimental condition. Ensure that the value here exactly matches one of the experimental conditions labels as defined in the .env file variable EXP_CONDITIONS_NAMES (see here for more info).
class can be used as a label for experimental purposes. It is not used in the database. For example, you can label certain comments as "bully" or "victim". (optional)
Populate your database with your simulation
After defining all the 3 components to the simulation using the 5 .csv files above, populate this information to the database so that the changes will be made to your simulation:
Ensure all of the above .csv files are located in the /input folder with the right file name.
Ensure that the MONGODB_URI value in your .env file is set to your database (See here for instructions again. If you followed the instructions to installing Truman, this should already be set to the correct value.).
In your project directory in your terminal/ command prompt: enter node populate.js.
This will connect to the MongoDB database you defined in the .env file and upload the simulation data found in the csv files in the ./input folder in the project directory to the MongoDB database you created.
You should see green and yellow lines printed in the console indicating the progress of the database population.
After it is complete, you have now completed populating your definitions for your simulation into the database! Run your project locally, visit the feed/timeline, and observe your changes!
