# Experiment for Form-Meaning Association

This is a simple task to test the association between the form of a stimuli and its mental representation.
A stimuli is a short video of one or several creatures, that have a face, a colour, a movement and a sound.

10 creatures have associated names, known by the participant. The other 20 don't have names.

Each time, a creature is presented and the participant has to name by speaking in the microphone.

## Requirements

- Python ≥ 3.9
- PsychoPy **2024.2.5** (pinned — the `.psyexp` files were authored with this
  version; other versions may break Builder compatibility). See
  `requirements.txt`.

## Install

Clone the repo:

```bash
git clone https://gitlab.pavlovia.org/HugoFara/task-form-meaning
cd task-form-meaning
```

Then install the pinned dependencies into a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

Alternatively, open either `session_1.psyexp` or `session_2.psyexp` in the
PsychoPy Builder GUI (version 2024.2.5).

The repo contains two experiment files: `session_1.py` and `session_2.py`.
See the [description section](#description) for details.

## Usage

Both section can run on your computer. The session 2 has also native support to be ran in a web browser, for instance using [Pavlovia](https://pavlovia.org/).

## Description

### Session 1

This session happens in the laboratory.
First, an example image is presented (a dog or a cat).
Then, the list of the 10 known creatures is presented and the participant should name them.
Then, a mix of the known creatures, as well as 20 unknown are presented.

### Session 2

This session happens in the laboratory.
The first part of this session is the same as session 1.

During the second part, a description of the creatures happens before it is presented.
The rest of the experiment happens as in the first session.

## Files structure

The file structure is the following, under the main folder:

```text
resources/      # contains video files
├ examples/     # examples videos: chien.mp4 and chat.mp4
├ learned/      # learned stimuli: bamelu.mp4, carrudo.mp4, etc.
└ unlearned/    # unlearned stimuli: qtnsr.mp4, rjchb.mp4, etc.
conditions/     # variations of experimental conditions
├ examples.csv  # list files in resources/examples/
├ learned.csv   # list files in resources/learned/
└ mixed variations.csv # list files from resources/learned/ in pseudo-random order multiple times
session_1.py    # experiment for the first session
session_2.py    # experiment for the second session
readme.md       # explanations files
```

After running the code a first time, new files will be added.

## Change the experiment

### Local experiment

First, let's start be changing the local experiment.
If you need change a video, simply substitute the video with the same name in `resources/`.
If you want add a *new* video, add it somewhere in `resources`, and reference it in the `conditions/` file used in the experiment.
Then run the experiment.

If you want to change the experiment's conditions, change the associated conditions file in `conditions/`. Then run the experiment.

### Online experiment

Forst, make sure to change the conditions in the [local experiment](#local-experiment).
Then, make sure you have a Pavolvia account, and that the online adress of the experiment has your account name in it.
If your account name is "my-acount-name", the online URL you can edit should be <https://pavlovia.org/my-account-name/experiment-name>.

Once both conditions are checked, instead of running the "session_2" experiment in *Python mode*, run it in *Browser mode*.
It will create new files in your folder.

Then, click the "Synchronize with Pavlovia" button.
The new experiment should be updated online.

## Audios renaming

The audios format used by PsychoPy may not be the most straightforward to use.
A file `audios_renamer.py` was provided to make things more simple.

Just drop the file where you have your PsychoPy data, and add the main CSV as an argument.
For instance `python -m audios_renamer your_psychopy_data.csv`.

It will copy & rename all the audio files in a `your_psychopy_data_renamed_audios/` folder.

## Links

Original developer: Hugo Farajallah (<mailto:hugo.farajallah@unige.ch>).
Maintainer/owner: Julie Franco (<mailto:julie.franco@unige.ch>).
