PALILA GUI

Graphical user interface for listening experiments in the PsychoAcoustic LIstening LAboratory (PALILA) at the Delft University of Technology, Faculty of Aerospace Engineering.

Developed by:

• Josephine Pockelé
  • PhD Candidate, TU Delft, Aerospace Engineering.
  • Email: j.s.pockele@tudelft.nl

  - LinkedIn: Josephine Pockelé

  Requirements

• Windows 10 or 11.
• Python version 3.11 or newer.
  • Enable 'Add Python to PATH' while installing.
• A touchscreen device with a resolution of 1920 x 1200 at 150% screen scaling.
  • Other resolutions will result in visual defects.

Installation

1. Download this software to the desired location, by:
   • using git clone on this repository.
   • downloading the zip file and unpacking it.
2. Run setup.bat. In case this script does not work:
   • create a Python virtual environment in the .\venv directory.
   • install the required packages in support_scripts\requirements.txt.

Now you can run the GUI using PALILA.bat

Copyright notice

Technische Universiteit Delft hereby disclaims all copyright interest in the program “PALILA GUI”, a graphical user interface software for psychoacoustic listening epxeriments, written by the Author(s).

Copyright 2025, Josephine Siebert Pockelé

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Citation

If you use this code for published research, please cite it as below: Pockelé, J.S. (2025). Graphical User Interface for the Psychoacoustic Listening Laboratory (PALILA GUI) (version v1.2.1). Zenodo. DOI: 10.5281/zenodo.11028965.

Experiment Configuration

IMPORTANT: this section of the README is not up-to-date since v1.2.0. It will be fully replaced by the user manual in a future version.

The experiment configuration consists of the following files, where <experiment name> represents the name you use for your experiment: - An experiment configuration file (<experiment name>.palila) - Defines the experiment (audios, questions, etc.). - An example can be found in gui_dev.palila. - The structure of this file is described in the following section. - An experiment file directory (.\<experiment name>) - Contains the audio samples and the responses of the experiment. - See for example the .\gui_dev directory.

The script NEW_EXPERIMENT.bat will create the configuration file and experiment file directory for you, and do the necessary modification in the code for it to run.

Config file structure (.palila)

```

======================================================================================================================

pid mode = # -> Mode to set the Participant ID (auto, input). welcome = (optional) # -> Optional welcome message for the first screen. goodbye = (optional) # -> Optional goodbye message for the final screen. randomise = (optional) # -> Switch to randomise the order of the experiment parts. demo = (optional) # -> Show a demonstration for participants before the welcome screen.

======================================================================================================================

[questionnaire] # -> Required section defining the questionnaire at the start of the experiment. # Will always show up, but if empty: there will only be a default message. default = (optional) # -> Switch to set up the questionnaire with default questions. # Extra questions can be added to the default list, be aware they require # a manual screen value. manual split = (optional) # -> Switch to set manual splitting of the questions over the screens. # In case of manual splitting, each question requires a manual screen value.

[[question <string>]] (optional)    # -> SubSection defining a question in the questionnaire. 
                                    #   <string> defines the name.

    type = <string>                     # -> Defines the type of question. See below for specifics of each types.
    text = <string>                     # -> Defines the question text.
    manual screen = <integer>           # -> In case of manual split = yes, this defines the screen to 
                                        #   put the question. Has no effect if manual split = no.

    unlocked by = <string>  (optional)            # -> Question ID of another questionnaire question, which locks 
                                                  #   this question until the answer in the other question equals 
                                                  #   the value in 'unlock condition'.
    unlock condition = <string>  (optional)       # -> The value the answer of the unlocking question has to take 
                                                  #   to unlock this question.

======================================================================================================================

[part ] # -> Required section defining a part of the experiment (grouping of audios). # Multiple parts per experiment are allowed. randomise = (optional) # -> Switch to randomise the order of the audios within the part.

[[breaks]] (optional)               # -> Optional breaks to allow for resting in the experiment part.
    text = <string> (optional)          # -> Optional custom message for during the breaks.
    interval = <integer>                # -> Number of audios between breaks.
                                        #   [0]: Adds a break only at the end of the part.
                                        #   [1, ...]: Adds a break every n audios and at the end of the part.
                                        #   [-1, ...]: Same, but a break at the end of the part is omitted.
    time = <integer>                    # -> Duration of the breaks in seconds.

[[intro]] (optional)                # -> Optional introduction message to the experiment part.
    text = <string>                     # -> Introduction message text.
    time = <integer>                    # -> Duration of the intro timer in seconds.

[[questions]] (optional)            # -> Optional SubSection to define the questions for all audios in this part.
                                    #   See below how to define questions. Questions in [Audio <string>] will be 
                                    #   ignored if this SubSection is defined.

[[audio <string>]]                  # -> SubSection defining the screen for one audio sample.
                                    #   Multiple audios per part are allowed
    filename = <string>                 # -> Name of the audio file inside the experiment directory.
    filename_2 = <string> (optional)    # -> Optional second audio file for comparisons. Will add an extra play 
                                        #   button to the AudioQuestionScreen.
    max replays = <integer> (optional)  # -> Defines the maximum number of times a sample can be replayed.
                                        #   Defaults to 1.
    repeat = <integer> (optional)       # -> Defines the number of times this audio is repeated in the part.
                                        #   Defaults to 1.

    unlocked by = <string>  (optional)            # -> Question ID of another audio question, which locks 
                                                  #   this question until the answer in the other question 
                                                  #   equals the value in 'unlock condition'.
    unlock condition = <string>  (optional)       # -> The value the answer of the unlocking question has to take 
                                                  #   to unlock this question.

    [[[question <string>]]]             # -> SubSubSection defining a single question for the audio sample.
        type = <string>                     # -> Defines the type of question. 
                                            #   See below for specifics of each types.
        text = <string>                     # -> Defines the question text.

[[questionnaire]] (optional)        # -> SubSection defining the optional questionnaire of this experiment part.
                                    #   See the main questionnaire for syntax. Keyword 'default' is disabled.

======================================================================================================================

```

Some definitions of the data types:

| Value type | Explanation | |:---------------:|:-----------------------------------------------------:| | <string> | Any sequence of characters | | <boolean> | Binary operator (yes, true, on, 1; no, false, off, 0) | | <integer> | Any number without decimal point | | <float> | Any number with decimal point |

The questionnaire question types:

• FreeNumber: Question asking for a freely entered numerical value.

  • Requires no additional arguments.

• FreeText: Question asking for a freely entered answer (can be anything, maximum 2 lines).

  • Requires no additional arguments.

• MultipleChoice: Multiple choice question with buttons.

  • Requires: choices = <string>, <string>, ... -> Defines the choice buttons.
  • Recommended limit of 4-5 choices.
  • To allow for multiple answers, set multi = yes.

• Spinner: Multiple choice question with a dropdown menu.

  • Requires: choices = <string>, <string>, ... -> Defines the dropdown items.

The audio question types:

• Text: Just text, no question.

  • Requires no additional arguments.

• MultipleChoice: Multiple choice question with buttons.

  • Required arguments:\ choices = <string>, <string>, ... -> Defines the choice buttons.
  • Recommended limit of 4-5 choices.

• Spinner: Multiple choice question with a dropdown menu.

  • Requires: choices = <string>, <string>, ... -> Defines the dropdown items.

• IntegerScale: Rating question with an integer numerical scale.

  • Required arguments:\ min = <integer> -> Defines the minimum value of the scale.\ max = <integer> -> Defines the minimum value of the scale.
  • Optional arguments:\ left note = <string> -> Defines the text on the left side of the scale.\ right note = <string> -> Defines the text on the right side of the scale.
  • Recommended range:\ 4 <= max - min <= 8 with left and right note, else 6 <= max - min <= 10

• Annoyance: Subtype of the IntegerScale containing the standardised 11-point annoyance question.

  • Requires no additional arguments.
  • IMPORTANT:\ text MUST be set as text = '' for this question to work.
  • Optional arguments:\ text -> Defines a custom question text for the annoyance scale.

• Slider: Rating question with a slider input.

  • Required arguments:\ min = <float> -> Defines the minimum value of the scale.\ max = <float> -> Defines the minimum value of the scale.\ step = <float> -> Defines the steps of the slider scale.
  • Optional arguments:\ left note = <string> -> Defines the text on the left side of the scale.\ right note = <string> -> Defines the text on the right side of the scale.
  • Recommended to use only when IntegerScale does not suffice in resolution.

Output file format

Results from an experiment will be stored as individual .csv files in the directory .\<experiment name>\responses\.\ Results are ONLY STORED after completion of the full experiment.\ The .csv files contain a table with the following structure:

| | <question ID> | <question ID> | ... | Timer | |:--------:|:-------------------:|:-------------------:|-----|:---------------------------:| | response | <answer> | <answer> | ... | <Completion Time> [s] |

The individual response files can be merged into a single .csv file using the .\merge_responses.bat script.\ The resulting .\<experiment_name>\responses_table.csv file contains a table with the following structure:

| | <question ID> | <question ID> | ... | Timer | |:---:|:-------------------:|:-------------------:|-----|:---------------------------:| | 0 | <answer> | <answer> | ... | <Completion Time> [s] | | 1 | <answer> | <answer> | ... | <Completion Time> [s] | | ... | ... | ... | ... | ... |

Standardised question IDs

For all questions, a standardised <question ID> will be generated. The format is defined: - In the main questionnaire: main-questionnaire-<question name>. - In part questionnaires: <part name>-questionnaire-<question name>. - For audio questions: <part name>-<audio name>-<question name>. - All question, audio and part names will be adjusted to at least 2 characters with str().zfill(2).

The names (part, audio and question) are the <string> values defined in the brackets of the input file.\ NOTE: When repeat is set in an [audio] section, a two digit (01, 02, ...) <repetition index> is added between the audio and question name as follows:<part name>-<audio name>_<repetition index>-<question name>.

Audio replay counters

In case an audio sample can be replayed, the number of replays is stored under the following <question ID> format: - For audio screens with 1 sample: <part name>-<audio name>(_<repetition index>)-replays - For audio screens with 2 samples: <part name>-<audio name>(_<repetition index>)-replays-left and <part name>-<audio name>(_<repetition index>)-replays-right, where 'left' and 'right' correspond to filename and filename_2, respectively.