NumberLie Game

# The NumberLie Game:
## Game description
Interactive numbers’ group game that relies on good deception / good truth telling and accurate lie detection.   
The game follows a simple scheme:  
1. At each turn a player is given a number (randomly).
2. They pass ***a number*** to the next player using a free sentence: “My name is Jill, I have number *X*, and I pass it on to Jude”.
3. The next player (e.g. Jude) decides if to trust the previous player (e.g. Jill) or not.
    1. If they **trust**, they continue with the game from point (1.). (To trust the player simply continues playing).
    2. If they **doubt**, the previous player’s statement is checked (lie or not). (Doubting has to be explicit).  
### Rules:  
- The number must keep increasing throughout the round ($n_{t} > n_{t-1}$).
- Players are **required** to tell the truth if they can ($n_{t} > n_{t-1}$).
- Players must always produce the sentence correctly and in a short amount of time within reason. Failure will result in a penalty of **-1** points.

### Scoring system:  
The scoring system is currently based on cooperation and altruism theory (evolutionary game-theory); moderate reward for successful cooperation for both players and moderate penalty for both players in case of unsuccessful cooperation, while high reward and high penalty for either successful deception - unsuccessful detection and successful detection - unsuccessful deception. This can be tweaked to measure different strategies or phonological outcomes in production depending on the reward.

All players start the game with **10** points.

| presenter\receiver | TRUST | DOUBT |
| --- | --- | --- |
| TRUTH | +2 \ + 2| 0 \ -1 |
| LIE | +3 \ -1 | -1 \ +2 |

### Compensation:
At the end of the game all player scores > 0 are summed together.  
Each player with a score > 0 will then be awarded the relative (in CHF 5 increments) amount of the prize pool that corresponds to their relative scored compared to the sum of all positive scores. (Note: this is automatic and will be shown directly at the end of the game to the players).

# Code description:
## v1.0: interactive game (used for second pilot recordings and main data collection): [``numberlie-game``](numberlie-game/)
  1. [`server_side_v2.py`](mem_scratch/server_side_v2.py): main script to run the game (this should be run on the controller machine i.e. the one used by the experimenter).
  2. [``client_side.py``](mem_scratch/client_side.py): client script to be run on the players' machines (rPis in the original implementation).
  3. [``output_table.py``](mem_scratch/output_table.py): output table class invoked by `server_side_v2.py`.
  4. [`player.py`](mem_scratch/player.py): player class invoked by `server_side_v2.py`.
  5. [`send_clients_cmd.py`](mem_scratch/send_clients_cmd.py): helper script to remotely shutdown client machines.
  6. [`message_boards`](mem_scratch/message_boards/): JSON dictionaries containing the translations of the various game messages to players in the different languages.
*all other scripts are deprecated or were part of testing and are retained only as a back-log*
## [Post-processing scrips](post_processing_scripts/)
Scripts used to automate parts of of the post-processing phases.
Each processing step takes as arguments an input and an optional output directories. 
All subdirectories (sessions) are processed and the same directory tree is recreated in the output directory.  
Apart from the first script (`auto-rename.py`) and the last script (`align_all_data.py`), all intermediate scripts delete the sessions which have been processed. All scripts allow to turn off this feature and allow for an overwrite flag.  
Each script also saves a log file in the corresponding output directory.

### Post-processing steps
1. [`auto-rename.py`](post_processing_scripts/auto-rename.py): renames files based on participant registration data and session metadata, so that recordings have the following file naming structure: `sp{participantID}_sess{sessionID}_{age}_{sex}_{native language code}_{experiment language}.wav`. All other session data is renamed as follows: `sess{sessionID}_np{number of players}_{experiment language}`.
2. [`psychopy-alignment.py`](post_processing_scripts/psychopy-alignment.py): uses the session data (turns data) to create approximately aligned turn transcriptions in the form of 1 (interval) tier TextGrids. TextGrids have the same name as the associated recording. Turns that resulted in a penalty are skipped. WARNING: manual correction of these TextGrids is needed to deal with disfluencies and is essential for precise forced-alignment in the following step.
3. [`mfa_alignment.py`](post_processing_scripts/mfa_alignment.py): uses the previously created approximate aligned transcriptions to create Montreal-forced-aligner forced-aligned transcriptions, resulting in 3 (2 depending on the MFA arguments parsed to the script) TextGrids with the same name as the associated recording. WARNING: for the next steps to work appropriately it is necessary to keep the original transcriptions by parsing the MFA argument `--include_original_text`; (in the script `--mfa_args "--include_original_text"`)
4. [`align_all_data.py`](post_processing_scripts/align_all_data.py): uses the previously created TextGrids, in conjunction with the session data to re-align the transcribed turn sentence and additionally add tiers such as `truth`, `is_trusted`, `score`. It additionally aligns 3 tiers to the corresponding MFA alignment (in the words tier): `spokenNumber`, `player`, `nextPlayer`. It also creates a general table with all turns data; saved in the parent output directory (parent to the sessions subdirectories).
5. [`extract_utterances.py`](post_processing_scripts/extract_utterances.py): extracts utterances from recordings using the provided tokens in the specified tier of the associated TextGrids. It also creates a metadata table if provided in the parameters, containing metadata for each utterance.