Skip to content

Quick Start: Running Scripts in rs-py in Python

Script 1

write_choice_file_detailed.run

Use this function to convert raw subject data into a detailed .mat choice file.

Import

from src.rs_py.scripts.write_choice_file_detailed import run

Minimal usage

params = {
    "input_path": "/path/to/raw/subject-data/AJ",
    "output_dir": ".",
}

run(params)

Add metadata when you want the output file to be named with the experiment and subject.

from src.rs_py.scripts.write_choice_file_detailed import run

params = {
    # Required: folder containing the raw subject data
    "input_path": "/path/to/raw/subject-data/AJ",

    # Required: where the output .mat file will be written
    "output_dir": ".",

    # Optional: helps populate output naming and metadata fields
    "metadata": {
        "exp_name": "texture",
        "subject": "AJ",
        "num_sessions": 10,
        "num_trials": 222 # e.g., in this experiment there were 222 unique trials which were repeated
    },
}

run(params)

Parameters

Required

  • input_path Path to the raw data directory for one subject.

  • output_dir Directory where the output .mat file should be saved.

Optional

  • metadata A dictionary of extra information used to label the output and populate the saved metadata.

Common metadata fields include:

  • exp_name: experiment name, such as "texture"
  • subject: subject ID, such as "AJ"
  • num_sessions: number of sessions, such as 10
  • num_trials: number of unique trials
  • num_judgments: number of comparisons between pairs of stimuli
  • judgment_type: 'triadic' or 'tetradic' (see Note below)
  • stim_list: these are autopopulated from raw data - do not provide at this stage

Other metadata fields may be left blank or omitted if they are not available.

What the script does

The script reads the raw data, builds the detailed choice structure, and saves a .mat file in the output directory.

If metadata is omitted or incomplete, the script still runs, but the output filename may be generic.

Output files

The function writes a .mat file to output_dir.

Example outputs:

  • ./_detailed_choices_.mat Saved when metadata does not provide experiment and subject names.

  • ./texture_detailed_choices_AJ.mat Saved when metadata["exp_name"] = "texture" and metadata["subject"] = "AJ".

Note on judgment_type:

Use triadic for the CSV format obtained if you collect data from the Waraich and Victor (2022) paradigm.

The script expects each trial row to contain a ref column and a clicks column. clicks must be a Python-list string of stimulus column names in click order, and each name must correspond to a column in the same row. The parser reads that list, looks up the clicked stimuli, and generates all pairwise comparisons among the clicked items relative to the reference.

Use tetradic only for pair-vs-pair comparisons. In the current code, this affects only how comparisons are standardized and written to the .mat file. It is not a separate raw-input format for the Waraich and Victor (2022) click-order CSVs.

Assumptions made:

This script is only for use with files generated by the Waraich and Victor (2022) paradigm. Each row in the CSV files is one trial, trial numbers are assigned sequentially across files, and stimulus labels are mapped to numeric IDs in sorted order before the file is saved.

Script 2

write_choice_file.run

Use this function to convert a detailed choices .mat file into the combined choice format.

This is the next step after write_choice_file_detailed.run. If you included metadata there, the subject and experiment names can carry through here and help name the output file.

Import

from src.rs_py.scripts.write_choice_file import run

Basic usage

params = {
    # Required: path to the detailed choices .mat file
    "input_path": "./texture_detailed_choices_AJ.mat",

    # Required: directory where the combined file will be saved
    "output_dir": ".",
}

run(params)

What it does

This script reads the detailed choices file and writes a combined file in triadic or tetradic format, depending on the input.

Output

If the detailed file does not contain usable metadata, the output may fall back to generic names such as:

./_choices_.mat

If metadata is available, the saved file will use those names instead.

Input assumptions

This script expects the detailed .mat file produced by write_choice_file_detailed.run, or an equivalent file with responses, responses_colnames, and metadata.

The input comparisons should already be standardized and stored with numeric stimulus IDs. The script does not re-canonicalize comparisons or merge differently ordered versions of the same comparison. It only combines exact repeated rows.

It detects the file type from responses_colnames: if ref is present, it writes the triadic combined format (ref, s1, s2); otherwise, it writes the tetradic combined format (s1, s2, s3, s4).

The output file is saved as {exp_name}_choices_{subject}.mat.

Using Custom Choice Files

If you bring your own choice file into script 3, include stim_list so the script can map stimulus IDs back to names. stim_list must contain one complete stimulus name per entry, stored as a string array or a cell array of character vectors. Do not save it as a padded character matrix, or Python may read each entry as individual characters instead of a full string.

The same rule applies to responses_colnames.

For coordinate files, the equivalent field is stim_labels. It should list the stimuli in the same order as the coordinate data, so each label matches the correct row or column.

stim_list is required. If it is empty, downstream modeling will fail.

Script 3

model_fitting.run

Use this function to fit Euclidean models to a combined choices .mat file.

Import

from src.rs_py.scripts.model_fitting import run

Minimal usage

filepath = "./samples/choice_files/bdce3pt_choices_MC_sess01_10.mat"

run({
    "filepath": filepath,
    "output_dir": ".",
})

If you only pass filepath and output_dir, the script can still run, but exp_name and subject may be blank in the output names unless you provide them yourself.

filepath = "./samples/choice_files/bdce3pt_choices_MC_sess01_10.mat"

params = {
    "filepath": filepath,
    "output_dir": ".",
    "exp_name": "bdce",
    "subject": "MC",
    "model_dimensions": [2],
    "max_iterations": 100,
}

run(params)

Parameters

Required

  • filepath: path to the combined choice file for one participant
  • output_dir: directory where output files will be saved

Common optional parameters

  • exp_name: used in output filenames
  • subject: used in output filenames
  • model_dimensions: list of model dimensions to fit, such as [1, 2, 3, 4, 5]
  • sigma: noise scale for the comparison model
  • filter_trials: number of unique triads to use; omit or set to all data to use everything
  • max_iterations: optimization limit
  • learning_rate: optimizer step size
  • tolerance: stopping criterion
  • minimization: optimization method, typically "gradient-descent" or "nelder-mead"

Output files

The script writes: * a .mat file containing fitted coordinates and likelihoods * a .csv summary of model log-likelihoods * a .npy file separately for each model. This is redundant with the .mat file, but is a convenient option for viewing coordinates quickly in Python if needed.