copydraw.CopyDraw
copydraw.copydraw.CopyDraw(
data_dir,
script_dir,
screen_ix=None,
screen_size=(1680, 1050),
flip=True,
for_calibration=False,
serial_nr='COM4',
)Class that implements the copydraw paradigm.
This class implements the copydraw paradigm where participants trace over template shapes displayed on screen. It handles stimulus presentation, user input tracking, data collection, and experiment flow control.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| data_dir | str | Directory path for storing experimental data and results. | required |
| script_dir | str | Directory path containing experiment scripts and template files. | required |
| screen_ix | int | Screen index for display. If None, uses default screen. | None |
| screen_size | tuple[int, int] | Screen resolution as (width, height). Default is (1680, 1050). | (1680, 1050) |
| flip | bool | Whether to flip stimuli horizontally. Default is True. | True |
| for_calibration | bool | If True, adds calibration elements to the display. Default is False. | False |
| serial_nr | str | Serial port identifier for trigger box communication. Default is ‘COM4’. | 'COM4' |
Attributes
| Name | Type | Description |
|---|---|---|
| log | logging.Logger | Logger instance for recording experiment events. |
| vpp | VPPort | Virtual parallel port for sending trigger signals. |
| paths | dict | Dictionary containing file and directory paths for the experiment. |
| win_settings | dict | Display window configuration settings. |
| stimuli | dict | Dictionary containing stimulus data and parameters. |
Methods
| Name | Description |
|---|---|
| add_calibration_frame_elements | Add calibration-specific visual elements to the frame. |
| create_frame | Create all visual elements and stores it in the frame dict. |
| draw_and_flip | Render all frame elements to the display and update the screen. |
| exec_block | Execute a complete block of copy-drawing trials. |
| exec_trial | Execute a single copy-drawing trial. |
| get_stimuli | Retrieve and prepare a specific stimulus template for display. |
| init_block | Initialize a block of trials. |
| init_screen | Initialize the PsychoPy display window with the specified settings. |
| init_session | Sets the session name and result path for the experiment. |
| load_stimuli | Load stimulus templates from MATLAB file. |
| save_block_settings | Save block settings to a YAML file. |
| save_trial | Save the current trial results to a YAML file. |
| scale_stimuli | Scale stimulus coordinates to normalized display units. |
| set_block_settings | Configure settings for a block of trials. |
add_calibration_frame_elements
copydraw.copydraw.CopyDraw.add_calibration_frame_elements(
stimuli_idx,
scale,
size=1.5,
)Add calibration-specific visual elements to the frame.
Creates additional visual elements for calibration mode including a template overlay, calibration grid points, and corner markers to assist with system calibration and validation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| stimuli_idx | int | Index of the stimulus template to use for calibration overlay. | required |
| scale | bool | Whether to apply coordinate scaling to the stimulus. | required |
| size | float | Scaling factor for calibration elements. Default is 1.5. | 1.5 |
create_frame
copydraw.copydraw.CopyDraw.create_frame(
stimuli_idx,
scale=True,
for_calibration=False,
)Create all visual elements and stores it in the frame dict.
Sets up the complete visual display including template, bounding box, cursor, trace elements, instructions, and UI components. For calibration mode, adds additional calibration-specific elements.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| stimuli_idx | int | Index of the stimulus template to display. | required |
| scale | bool | Whether to apply coordinate scaling to the stimulus. Default is True. | True |
| for_calibration | bool | If True, adds calibration dots and grid elements. Default is False. | False |
draw_and_flip
copydraw.copydraw.CopyDraw.draw_and_flip(exclude=[])Render all frame elements to the display and update the screen.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| exclude | list | List of element names to skip during drawing. Default is empty list. | [] |
exec_block
copydraw.copydraw.CopyDraw.exec_block(
block_nr=None,
stim=None,
block_config=None,
data_root=None,
)Execute a complete block of copy-drawing trials.
Initializes the block with configuration settings, runs all n trials in sequence, saves trial data, and performs cleanup.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| block_nr | int | Block number identifier. If None, auto-generates based on existing data. | None |
| stim | str | Stimulus identifier prefix for file naming. If None, uses ‘UNKNOWN’. | None |
| block_config | dict | Configuration dictionary for block settings. If None, loads from config file. | None |
| data_root | str | Override for data storage root directory. | None |
Returns
| Name | Type | Description |
|---|---|---|
| int | 0 if block executed successfully |
Notes
Processing a file name is not implemented to keep the nomenclature consistent.
exec_trial
copydraw.copydraw.CopyDraw.exec_trial(stimuli_idx, scale=True)Execute a single copy-drawing trial.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| stimuli_idx | int | Index specifying which stimulus template to use for this trial. | required |
| scale | bool | Whether to apply coordinate scaling to stimulus. Default is True. | True |
Notes
This method handles the complete trial flow including frame initialization, drawing loop execution, timing control, and data collection.
get_stimuli
copydraw.copydraw.CopyDraw.get_stimuli(stimuli_idx, scale=True)Retrieve and prepare a specific stimulus template for display.
Loads the specified stimulus template, applies scaling and interpolation if enabled, and sets the initial cursor position.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| stimuli_idx | int | Index of the stimulus template to retrieve. | required |
| scale | bool | Whether to apply coordinate scaling. Default is True. | True |
Returns
| Name | Type | Description |
|---|---|---|
| np.ndarray | The processed stimulus coordinates as a 2D array. |
init_block
copydraw.copydraw.CopyDraw.init_block()Initialize a block of trials.
Sets up the display window, creates output folders, loads stimuli, and prepares the trial sequence.
init_screen
copydraw.copydraw.CopyDraw.init_screen(win_color=(-1, -1, -1))Initialize the PsychoPy display window with the specified settings.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| win_color | tuple[int, int, int] | RGB color values for window background. Default is (-1, -1, -1). | (-1, -1, -1) |
init_session
copydraw.copydraw.CopyDraw.init_session(session_name=str)Sets the session name and result path for the experiment.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| session_name | str | Name identifier for the experimental session. | str |
load_stimuli
copydraw.copydraw.CopyDraw.load_stimuli(path, short=True, size=35)Load stimulus templates from MATLAB file.
Loads pre-defined drawing templates from a .mat file and stores them for use in trials. Template selection is based on length and size parameters.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| path | str or Path | Directory path containing stimulus template files. | required |
| short | bool | If True, loads short templates, otherwise loads standard templates. Default is True. | True |
| size | int | Size identifier for template selection. Default is 35. | 35 |
save_block_settings
copydraw.copydraw.CopyDraw.save_block_settings()Save block settings to a YAML file.
save_trial
copydraw.copydraw.CopyDraw.save_trial()Save the current trial results to a YAML file.
scale_stimuli
copydraw.copydraw.CopyDraw.scale_stimuli()Scale stimulus coordinates to normalized display units.
Transforms stimulus coordinates from pixel space to normalized 2D coordinates in the range (-0.5, 0.5) for both x and y axes. Also handles coordinate flipping if enabled in settings.
set_block_settings
copydraw.copydraw.CopyDraw.set_block_settings(
n_trials=1,
letter_time=2.2,
finish_when_raised=False,
n_letters=3,
stim_size=35,
size=0.5,
interp=True,
shuffle=True,
block_nr=None,
)Configure settings for a block of trials.
Sets up various parameters that control the experiment behavior including trial count, timing, stimulus properties, and block identification.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| n_trials | int | Number of trials in the block. Default is 1. | 1 |
| letter_time | float | Time duration per letter in seconds. Default is 2.2. | 2.2 |
| finish_when_raised | bool | Whether to finish trial when stylus is raised. Default is False. | False |
| n_letters | int | Number of letters in the stimulus. Default is 3. | 3 |
| stim_size | int | Size identifier for stimulus templates. Default is 35. | 35 |
| size | float | Scaling factor for stimulus display (0-1). Default is 0.5. | 0.5 |
| interp | bool | Whether to interpolate stimulus paths. Default is True. | True |
| shuffle | bool | Whether to shuffle trial order. Default is True. | True |
| block_nr | int | Block number identifier. If None, automatically determines the next block number. | None |