Jump to content

GuiltTask: Difference between revisions

From BCI2000 Wiki
Lingling (talk | contribs)
320 edits
Created page with "==Synopsis== In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task. During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots. After..."
 
Lingling (talk | contribs)
320 edits
 
(25 intermediate revisions by the same user not shown)
Line 5: Line 5:


==Timeline==
==Timeline==
<gallery mode="packed" widths=1000px heights=500px>
<gallery mode="packed" widths=1500px heights=1200px>
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
File:Guilty_task_time_line.png|Figure 1: Single Trial Timeline.
</gallery>
</gallery>


== Visual Representation ==
== Visual Representation ==
<gallery mode="packed" widths=750px heights=421px>
<gallery mode="packed" widths=800px heights=450px>
File:xx.gif|Figure 2: Visual Representation
File:GuiltTaskVideo.gif|Figure 2: Visual Representation
</gallery>
</gallery>


Line 41: Line 41:
The batch file is located in ./batch/CommunicationTask.bat.  
The batch file is located in ./batch/CommunicationTask.bat.  
<gallery mode="packed" widths=600px heights=200px>
<gallery mode="packed" widths=600px heights=200px>
File:CommunicationTask batch.png|Figure 5: Batch File.
File:xxx.png|Figure 5: Batch File.
</gallery>
</gallery>


Line 64: Line 64:
==Parameters==
==Parameters==
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.
There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.


===Shared Parameters===
===Shared Parameters===
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.
You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.


====StimuliMatrix====
====Stimuli====
Shared parameter, matrix of stimulus information, including:<br>
Shared parameter, stimulus information, including:<br>
1. ImageReceiver and ImageSender(the path of images).<br>
1. ImagePath(the path of dots images).
2. Sender(the role of players),1 is the sender), 2 is the receiver.<br>
 
3. Jitter(the duration to present the role).<br>
====MyStimuliSequence====
4. CorrectResponse(1: left, 2:right).<br>
The sequence of dots images.
5. Training(1: training, 0: main task).<br>
 
6. Category(1: object, 2: animal).<br>
====StimuliSequencePractice====
7. Difficulty(1: easy, 2: moderate, 3: hard).<br>
Practice trial stimuli sequence
8. Dimension1a and Dimension1b(bar#1 left text and right text).<br>
9. Dimension2a and Dimension2b(bar#2 left text and right text).<br>
10. Option1 and Option2(left option text and right option text).


====BreakTrialSequece====
====InstructionPathTrans====
The sequence of break trials, a break will happen after the break trial.
Transgressor instruction image path


====FeedbackDuration====
====InstructionPathVicT====
Duration of feedback(ITI). Indicate the receiver to make a correct or incorrect guess.<br><br>
Victim instruction image path


The server will generate the InitialTrialNumber and StimuliSequence, and save them into a parameter file named by IP addresses on the server. You don't need to worry about these two parameters. Unlike the parameters described above, they are saved on the server rather than on local computers.
====FeedbackPathList====
Feedback icon path list


====InitialTrialNumber====
====TrialSequece1, TrialSequece2====
The trial number to begin with. We provide the resume option, allowing clients to pause and resume the game from where they stop. After one of the clients quits the game, the server will discover it and save the current trial number and sequence. When the same clients(same IP address) reconnect the server again, the server will send the previous trial number to them. Otherwise, the InitialTrailNumber will be initialized by 0. Usually, you don't need to touch this parameter.
There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID".<br>
Sequence of trial type.<br>
1: both correct<br>
2: victim incorrect<br>
3: transgressor incorrect<br>
4: both incorrect


====StimuliSequence====
====InstructionImagesSequence====
The sequence of stimuli(images). The server will generate a random stimuli sequence for every pair of clients (identified by the IP address).
The sequence of instruction images path.


===Local Parameters===
====FixationDurationList====
Duration of Fixation(ITI) list.
 
====DotsDuration====
Duration of displaying the dots
 
====ResponseDuration====
The maximum time allows the subject to make a response.
 
====OutcomeDuration====
The duration to display the outcome.
 
====CompensationDuration====
The duration to display the compensation.
 
====EnablePractice====
Enable the practice trial or not
 
====StartPoints====
The initial total points of the game
 
====GuessDots====
INstruction of the guessing the number of the dots
 
====DotsNumber====
Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.


====StimuliWidth====
====optionOne, optionTwo====
StimulusWidth in percent of screen width (zero for original pixel size).
guess option one/two, for example "Greater" and "Less"


====InstructionImagesSeque====
====CompensationQuestion====
The sequence of instruction images path.
Instruction of compensation phase


====InstructionWidth====
====CompensationOne, CompensationTwo, CompensationThree, CompensationFour====
Instruction width in percent of screen width (zero for original pixel size).
Compensation options


====SliderWidth====
====ForgivenessQuestion====
SliderWidth in percent of screen width (zero for original pixel size).
Instruction of forgiveness phase


====BarColor====
====ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour====
Color of the slider bar.
Forgiveness options


====AxeActiveColor====
Unlike the parameters described above, they are saved on the server rather than on local computers.
Color of active slider axe.


====AxeInActiveColor====
===Local Parameters===
Color of inactive slider axe.


====DimensionFontColor====
====FontSize, FixationSize====
Color of the text under the slider.
Font/Fixation size.


====DimensionHeight====
====FontColor, FixationColor====
Height of text in percent of the screen height.
Color of the font/fixation.


====OptionFontActiveColor====
====FontActiveColor====
Color of the active options.
Color of the active font(be selected)


====OptionFontInActiveColor====
====GUIScale====
Color of the inactive options.
Scale the GUI, 1 is maximum, 0 is minimium


====OptionHeight====
====TrialTypeSequenceID====
Height of text in percent of the screen height.
Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"


====RoleFontColor====
====ProgressBar====
Color of the role text.
Display progress bar.


====RoleHeight====
====ProgressBarHeight, ProgressBarWidth====
Height of text in percent of the screen height.
Progress bar height/width in pixels.


====FeedbackWidth====
====ProgressBarBackgroundColor, ProgressBarForegroundColor====
Width of feedback in percent of screen width.
Color of progress bar background/foreground.


====PhotoDiodePatch====
====PhotoDiodePatch====
Line 164: Line 189:
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.
Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.


===PhaseNumber===
===Shared State===
The index of phase in each trial. (8 bits) <br> 
[0] indicates the instruction at the beginning of the experiment. (When the 10 slides instruction images are present on the screen)<br>
[1] indicates the client is waiting for the other client to push the button to start the game. ( We are waiting for another player; once she/he is ready, we're ready to go!)<br>
[2] When the role text is present on the screen.(Sender or Receiver).<br>
[3] When the sliders and stimulus are present on the screen.<br>
[4] Feedback: After the receiver locks the answer, it comes to phase [4], showing whether the answer is correct.<br>
[5]Break: (Well done! Are you ready for the next block? \n\n Press SPACEBAR)<br>
[6]End: (Well done! You have finished all the trials.)


===TrialNumber===
====isReadyStart0, isReadyStart1====
Index of trials. (8 bits)
Check if client0/client1 is ready to move to the next phase or trial.


===BarOneValue===
====ClientNumber====
Value of slider#1. (32 bits)
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)<br>
0: Transgressor.    1: Victim


===BarTwoValue===
====Compensation====
Value of slider#2. (32 bits)
The compensation that the transgressor gives in each trial


===BarOneActive, BarTwoActive===
====Forgiveness====
0: slider is not selected.  1: slider is selected. (8 bits)
The forgiveness that the victim gives in each trial


===ResponseValue===
===Local State===
1: object.   2: animal. (8 bits)
====PhaseNumber====
The index of phase in each trial. (8 bits) <br> 
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen)<br>
[1] present the instruction showing the end of the practice trial<br>
[2] present the fixation on the screen.<br>
[3] present the dots on the screen.<br>
[4] The subject estimates the number of dots.<br>
[5] Display the outcome.<br>
[6] reset the states and GUI<br>
[7] Choose the compensation/forgiveness level.<br>
[8] display the compensation/forgiveness that another player selects<br>
[9] The end of the game, shows the total score, compensation and average forgiveness.<br>
[10] End: (Well done! You have finished all the trials.)<br>
[11] none, the initial value of the state.<br>


===SenderLock, ReceiverLock===
====TrialNumber====
0: client is moving the slider/making a guess. 1: client has locked the answer. (8 bits)
Index of trials. (8 bits)
 
===isReadyStart0, isReadyStart1===
0: client isn't ready to start/resume/continue the game(not yet pushing the button).  1: client is ready to start/resume/continue the game(push the button). (8 bits)
 
===ClientNumber===
The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)
 
==Example==
The hyperscanning application module is almost the same as a BCI2000 application module, except that the typical BCI2000 module is inherited from ApplicationBase, and the hyperscanning application module is inherited from HyperscanningApplicationBase. Basically, the HyperscanningApplicationBase class is the same as ApplicationBase class with adding the communication with the server. So instead of using  Publish, Preflight, Process, etc. We are using SharedPublish, SharedPreflight, SharedProcess, etc. These methods behave in the exact same way, except they also call the client loops which interact with the server.
 
 
Communication_task_dualTask.h:
<pre>
#include "ApplicationBase.h"
#include "Slider.h"
#include <map>
#include <vector>
#include <string>
#include "TextStimulus.h"
#include "ImageStimulus.h"
#include "Shapes.h"
#include "HyperscanningApplicationBase.h"
 
class Communication_task_dualTask : public HyperscanningApplicationBase
{
public:
  Communication_task_dualTask();
  ~Communication_task_dualTask();
  void SharedPublish() override;
  void SharedPreflight( const SignalProperties& Input, SignalProperties& Output ) const override;
  void SharedInitialize( const SignalProperties& Input, const SignalProperties& Output ) override;
  void SharedAutoConfig( const SignalProperties& Input ) override;
  void SharedStartRun() override;
  void SharedProcess( const GenericSignal& Input, GenericSignal& Output ) override;
  void SharedStopRun() override;
  void SharedHalt() override;
 
private:
  //define your own private members here
  ApplicationWindow& mrDisplay;


  //define your own private methods here
====TrialType====
1: both correct<br>
2: victim incorrect<br>
3: transgressor incorrect<br>
4: both incorrect


};
====StimulusCode====
</pre>
The id of the stimulus in each trial


====ResponseValue====
1: greater.    2: smaller. (8 bits)


Manipulate the shared state is the same as the BCI2000 state. "isReadyStart1" is a shared state.
====FixationDuration====
<pre>
The duration of the fixation phase in each trial.
  State("isReadyStart1") = 1; // assign 1 to "isReadyStart1"
</pre>


Get the value of the shared state "isReadyStart1"
====Photodiode====
<pre>
1: active;
  //Both of the two players are ready, move to the next phase
2: non-active
  if (State("isReadyStart0") && State("isReadyStart1")) {
            m_instruction_container->Conceal();
            m_role_txt->Conceal();
            my_phase = role_text;
            m_block_in_phase = 0;
  }
</pre>

Latest revision as of 20:38, 3 March 2025

Synopsis

In the interpersonal task, you will team up with another participant in a different room (referred to as “partner”). You do not know each other before, and you will not see each other after the task. During this task, the two of you will complete multiple rounds of “dot-estimation” together. Specifically, both you and the partner will see an array of white dots scattered on the screen. Your task is to estimate the total number of these dots. After the dots disappear, you will see a number on the screen. Now you need to guess whether the number of dots you just saw is greater or smaller than the number on the screen. If you think the number of dots is smaller than the number on the screen, then press the left arrow button to select “Smaller”; if you think the number of dots is larger than the number on the screen, then press the right arrow button to select “Greater”. You will need to make the choice within 3 seconds, otherwise your responses will be recorded as “incomplete” will be reminded to respond faster next round.

Timeline

  • Figure 1: Single Trial Timeline.
    Figure 1: Single Trial Timeline.

Visual Representation

  • Figure 2: Visual Representation
    Figure 2: Visual Representation

Versioning

Authors

Hongbo Yu <hongbo.yu@psych.ucsb.edu> and Shuo Wang <wangshuo45@gmail.com> conceived this paradigm.
Huiling Huang (huiling@neurotechcenter.org) implemented the paradigm into BCI2000.

Set up

Deploy the Server

You will need a Linux or macOS computer to run the server. Currently, the Windows OS is not supported. The following steps are for deploying the server on the local network. If you want to deploy the server on AWS, please refer to https://www.bci2000.org/mediawiki/index.php/BCI2000_Hyperscanning#Important_Notes_2.
First, please ensure all the computers are connected to the same local network. Then open the terminal(Mac OS or Linux) and run the command below to clone the server code from GitHub. 

git clone https://github.com/MaxwellMarcus/hyperscanning-backend

Go the hyperscanning directory 

cd hyperscanning

Compile the project by 

make -B
  • Figure 3: Download and Compile the Server.
    Figure 3: Download and Compile the Server.

Run the server with 

./application
  • Figure 4: Launch the Server.
    Figure 4: Launch the Server.

The application will only run as long as the experiment and will have to be restarted.

Batch File

The batch file is located in ./batch/CommunicationTask.bat.

Unlike the normal bci2000 task, we define the shared states in the batch file(line 35) by beginning with"--SharedStates=". The form is: 

--SharedStates=<state-1>,<state-1-size>&<state-2>,<state-2-size>&<state-3>,<state-3-size>...

IPAddress and Port indicate the server computer.

Run the experiment on the client computer

Go to the./batch, find the "CommunicationTask.bat", and double click it. After pushing "Set Config," the BCI2000 will try to connect the server. If it successfully connects to the server, the System Log will print "Connected to server." If only one client connects to the server, the "Start" button in the operator will turn gray until another client connects.

  • Figure 6: Launch the BCI2000.
    Figure 6: Launch the BCI2000.

Troubleshooting

After you quit the server from the terminal and restart it again, you might see this error message. That means the server is still running. You need to kill the "application" process.

  • Figure 7: Kill the Server.
    Figure 7: Kill the Server.

Parameters

There are two kinds of parameters: shared and local. The shared parameter is the one you want to synchronize between two clients, like the stimulus sequence, the sequence of break trials you wish to take a break after this trial, etc. It should be saved on the server as a parameter file and passed to the clients through messages as a parameter. The local parameter is that you want to customize the parameter locally, like GUI. The local parameter is the regular BCI2000 parameter file saved under the local BCI2000 project folder.

Shared Parameters

You must upload the parameters below to the server as a parameter file. When the client connects to the server, it will automatically download the parameter file from the server and save it locally. You can indicate the download path in the Application tab, ParamterPath. Please do not modify the parameter file. Otherwise, the synchronization between two clients can't be guaranteed.

Stimuli

Shared parameter, stimulus information, including:
1. ImagePath(the path of dots images).

MyStimuliSequence

The sequence of dots images.

StimuliSequencePractice

Practice trial stimuli sequence

InstructionPathTrans

Transgressor instruction image path

InstructionPathVicT

Victim instruction image path

FeedbackPathList

Feedback icon path list

TrialSequece1, TrialSequece2

There are two sequences of trial types, for each experiment, we can run them alternatively, we can specify the sequence through the Parameter "TrialTypeSequenceID".
Sequence of trial type.
1: both correct
2: victim incorrect
3: transgressor incorrect
4: both incorrect

InstructionImagesSequence

The sequence of instruction images path.

FixationDurationList

Duration of Fixation(ITI) list.

DotsDuration

Duration of displaying the dots

ResponseDuration

The maximum time allows the subject to make a response.

OutcomeDuration

The duration to display the outcome.

CompensationDuration

The duration to display the compensation.

EnablePractice

Enable the practice trial or not

StartPoints

The initial total points of the game

GuessDots

INstruction of the guessing the number of the dots

DotsNumber

Guess the number of dots is greater or less than the "DotsNumber", "DotsNumber" is the number to be compared with.

optionOne, optionTwo

guess option one/two, for example "Greater" and "Less"

CompensationQuestion

Instruction of compensation phase

CompensationOne, CompensationTwo, CompensationThree, CompensationFour

Compensation options

ForgivenessQuestion

Instruction of forgiveness phase

ForgivenessOne, ForgivenessTwo, ForgivenessThree, ForgivenessFour

Forgiveness options

Unlike the parameters described above, they are saved on the server rather than on local computers.

Local Parameters

FontSize, FixationSize

Font/Fixation size.

FontColor, FixationColor

Color of the font/fixation.

FontActiveColor

Color of the active font(be selected)

GUIScale

Scale the GUI, 1 is maximum, 0 is minimium

TrialTypeSequenceID

Specify the trial type sequence, see Parameter "TrialSequece1 and TrialSequece2"

ProgressBar

Display progress bar.

ProgressBarHeight, ProgressBarWidth

Progress bar height/width in pixels.

ProgressBarBackgroundColor, ProgressBarForegroundColor

Color of progress bar background/foreground.

PhotoDiodePatch

Display a photodiode patch on the stimulus window. Recording from a photodiode located on that patch will allow triggering on actual stimulus delivery (see User_Reference: P3TemporalFilter#OnsetExpression).

PhotoDiodePatchHeight, PhotoDiodePatchWidth

Photodiode patch height/width in relative coordinates (between 0 and 1).

PhotoDiodePatchLeft, PhotoDiodePatchTop

Photodiode patch left/top position in relative coordinates (between 0 and 1).

PhotoDiodePatchShape

Photodiode patch shape: 0 rectangle, 1 ellipse.

PhotoDiodePatchActiveColor

Photodiode patch color when active (RGB color in format 0xrrggbb).

PhotoDiodePatchInactiveColor

Photodiode patch color when inactive, (RGB color in format 0xrrggbb, use 0xff000000 for transparent).

States

Shared states are converted to BCI2000 states asynchronously through events using the HyperscanningApplicationBase class. We declared shared states in the batch file as "--SharedStates=state1_name,state1_size&state2_name,state2_size&...", which is appended to the end of the application module.

Shared State

isReadyStart0, isReadyStart1

Check if client0/client1 is ready to move to the next phase or trial.

ClientNumber

The client’s ID, is assigned by the server. Either 0 or 1. (8 bits)
0: Transgressor. 1: Victim

Compensation

The compensation that the transgressor gives in each trial

Forgiveness

The forgiveness that the victim gives in each trial

Local State

PhaseNumber

The index of phase in each trial. (8 bits)
[0] indicates the instruction at the beginning of the experiment. (When the slides instruction images are present on the screen)
[1] present the instruction showing the end of the practice trial
[2] present the fixation on the screen.
[3] present the dots on the screen.
[4] The subject estimates the number of dots.
[5] Display the outcome.
[6] reset the states and GUI
[7] Choose the compensation/forgiveness level.
[8] display the compensation/forgiveness that another player selects
[9] The end of the game, shows the total score, compensation and average forgiveness.
[10] End: (Well done! You have finished all the trials.)
[11] none, the initial value of the state.

TrialNumber

Index of trials. (8 bits)

TrialType

1: both correct
2: victim incorrect
3: transgressor incorrect
4: both incorrect

StimulusCode

The id of the stimulus in each trial

ResponseValue

1: greater. 2: smaller. (8 bits)

FixationDuration

The duration of the fixation phase in each trial.

Photodiode

1: active; 2: non-active

Retrieved from "http://www.bci2000.org/mediawiki/index.php?title=GuiltTask&oldid=11748"