Record handwriting
WRecorder allows recording a person’s handwriting trajectories as they write on a digitizing tablet. WRecorder assumes relatively short stimuli (e.g. single words, multi-digit numbers) and records the full handwriting trajectories.
Known issues: At present, WRecorder works with the ink-less pen that ship with the tablet, but it does not work with some of the pens with ink. Specifically, WRecorder works with the WACOM inking pen, which is no longer manufactured :-(, but it does not work with the newer pens (e.g., the ballpoint pen), which switch the tablet automatically into “paper mode”. We are currently working to solve this issue.
Main features:
- Easy definition of the stimuli via an excel file with 2-3 columns. Non-English characters (Hebrew, Arabic, etc.) are supported.
- Stimuli can be played from mp3 files or dictated by the tester.
- The tester can immediately code each trial as correct or incorrect, and also specify the type of error. More detailed error coding can be done using WEncoder.
- Simple navigation between trials: easily skip trials, re-administer specific trials, or ask WRecorder to present trials over and over again until they are written without errors.
- The full handwriting trajectory is recorded as a series of time-stamped coordinates with the pen pressure in each coordinate. The pen movement above the paper between characters are recorded too.
- Simple output format (CSV files).
- Runs on Windows 10 with a WACOM pen tablet. MacOS is not supported.
Using WRecorder
General description of the application
WRecorder records handwriting in sessions. A session means that a person writes a predefined list of targets: each target is typically a word or a number, so a session consists in writing a list of words or numbers. The writing of each target is considered as a single trial.
The list of targets for a single session is defined in a targets file, which you can easily prepare according to the instructions below. A session can be administered in “one shot”, but you can also stop a session and continue it later. The handwriting results from a single session are saved in a results folder – one folder per session.
WRecorder is used in one-on-one mode: the tester runs the application on his/her computer. The participant writes the targets on a WACOM tablet, which is connected to the computer via USB. After each trial, the tester should code the participant’s writing as “OK” or “Error” (in which case the tester also specifies the error type). A more detailed coding of the handwriting, character-by-character, is done only later, using the WEncoder application. A session ends when all targets have been completed.
Before using WRecorder, make sure that the WACOM driver is installed on your computer.
To create standard writing environment, use WACOM’s stylus with ink: the participant will write on a paper that you placed on top of the tablet. Alternatively, you can use a stylus without ink: the advantage of this method is that the participants do not get visual feedback of their writing, so they cannot rely on intact reading to compensate for a dysgraphia.
Preparing a target list
The list of targets to be written in a session is defined in a targets file. This is an MS-Excel file (.xlsx, .xls) or a .csv file that specifies the list of targets. The file should contain 3 columns:
- target_id – a unique identification of each target.
- target – The stimulus to show on the tester’s screen.
- sound_file_name (optional column) – The name of an MP3 file that will be played in the beginning of the trial. Typically, the file contains a recording of you saying the word/number to be written. Specify the MP3 file name without the folder (e.g., word.mp3). You tell WRecorder the MP3 folder only when you start a session (see below).
If you define this column, you must not leave it empty in any row.
Any additional columns in the targets file are ignored.
See here example target files: Excel format, CSV format.
Starting a session
Run WRecorder and click the “Start session” button (#9 in Figure 2). You will be asked to select two things, one after another: (1) The targets file; and (2) the session’s results folder.
Next, you will see a screen that lets you configure the session’s parameters:
Figure 1. Session settings screen
Choose folder with MP3 files: If the target file specifies sound files (via the sound_file_name column), use this button to specify the folder that contains the mp3 files.
Which trials should be considered as completed: WRecorder presents the trials one after another, until all trials are completed (if the end of the trial list is reached and un-completed trials remain, WRecorder will return to these trials). This setting determines when a trial is considered as completed. If you choose that only trials coded as OK are considered completed, this means that after presenting all trials, WRecorder goes back to present again all trials marked as errors. If you choose that any coded trial is considered completed, WRecorder will present each trial (including errors) only once. In either case, after all trials are completed you can still rerun specific trials manually by navigating to this trial via the “Go to” button.
Error types: Specify here a comma-separated list of all error types. When marking a trial as an error, WRecorder lets you choose the specific error type from this list. The error type you selected is saved in the trials.csv results file.
Leaving this option empty will set the default error types: Spelling (a spelling mistake), Motor (unclear handwriting), Incomplete (the participant did not finish writing the word).
During the session
Running a trial: Once you have started the session, the first target will automatically appear on the screen. The stimulus is displayed in red (#1 in Figure 2).
Figure 2. Control toolbar
If the trials file specified a sound file, click the “Play” button to play this sound (#4 in Figure 2). WRecorder will start recording the trajectory once you clicked “Play”. If no sound file was specified, the participant can start writing immediately, and recording will begin as soon as the pen touches the tablet.
You can click “Play” only once. To play the sound file again, you must first click the “Reset trial” button (#6 in Figure 2).
Reset trial: This button (#6 in Figure 2) will restart the current trial and delete the trajectory already recorded for this trial.
Coding the result: After the participant has finished writing the stimulus, you must tag the trial either as “OK” or as “Error” (#2 in Figure 2). If you chose Error, select the error type. To add error types in mid session, choose the “Add error type” option from the “options” menu.
Navigating between trials: Use the navigation buttons (#3, #5 in Figure 2) to move to the next/previous trial. If the participant already started writing and you haven’t coded the trial’s result, the navigation buttons will be greyed out. To navigate, you must either reset the trial or code its result.
The next/previous navigation buttons skip trials that were already presented and completed (i.e., any trial that was presented, potentially also trials coded as errors – depending on the definition in the session settings).
Navigating to any trial: You can “jump” to any trial you want. By choosing it in the drop-down list and clicking the “Go to” button (#7 in Figure 2). The “Go to” button is the only way to re-present completed trials.
Adjusting display size. You can adjust the screen display using the “+”, “-” and rotate buttons (#11 in Figure 2). These buttons control the tablet display area. You can also drag the display area if you zoomed a lot and the words are out of the display boundaries.
Additional information (#8 in Figure 2):
- The path of the targets file
- The results directory
- Statistic about the current session progress: the total number of targets, completed targets, and remaining (not-yet-completed) targets.
Ending a session
Click the “End Session” button (#8 in Figure 2) to terminate the current session. You can use this button even if some trials are not yet completed: you can always re-open the session later and continue it.
If you quit the application (via the “Quit” button, #12 in Figure 2), the session is still saved and you can continue it too. The session is also saved even if the application is terminated unexpectedly.
Continuing an already-started session
To continue running trials of a session that has already started, click the “Continue Existing Session” button (#10 in Figure 2). You will be asked to choose the session’s results folder. As in the case of “Start Session”, you will see the session settings screen. Once you close the settings screen, the session will continue from the point in which it was terminated.
Errors
You might encounter an error message if something went wrong. Most errors are not critical and you can continue working.
If a critical error pops, this typically means that you would have lost the last trial’s information. We strongly advise not to continue the session after critical errors. Restart WRecorder and continue the session.
If you encounter problems or bugs, please e-mail us at writracker@mathinklab.org, and specify that the issue is in the WRecorder application.
Result files
The results folder contains the following files:
Original_targets_file_copy.csv: a copy of the targets file that was used for the current session.
Remaining_targets.csv: A copy of the targets file that contains only the not-yet-completed trials.
trials.csv: contains information about the trials written in this session. The file contains one row per trial, with the following columns:
- trial_id – the trial’s serial number
- target_id – the unique ID of the target of this trial (copied from the targets file)
- target – the target of this trial (copied from the target_value column in the targets file)
- rc – the trial’s coding: either OK or an error code.
- time_in_session – the duration (in seconds) from the time when the session target until the time in which the trial started.
- date – the date in which the trial started.
- time_in_day – the time in which the trial started (HH:MM:SS, 24-hour format).
- traj_file_name – the trajectory file name which corresponds to the trial
- sound_file_length – the duration (in seconds) of the played sound file, or an empty value of no sound file was played.
See here an example trials.csv file.
Trajectory Files: These files – one per trial – contain the full handwriting trajectory. The name of each trajectory file is trajectory_trial#_target#.csv (“#” stands for the trial ID and the target ID).
In the trajectory CSV files, each row represents the pen position and pressure in a particular time point during the trial. The file has 4 columns: X, Y, Pressure, and Time:
- X, Y are the pen coordinates. The X values range from 0 (left) to 2,000 (right). The Y values are set proportionally, according to the tablet dimensions.
- Pressure is the pen’s pressure against the tablet, as a value between 0 and 100 (0 = the pen did not touch the paper, 100 = strongest pressure).
- Time is the time relative to the trial’s start time (which is the time you clicked the “Play” button to play the trial’s sound, or – if the trial has no sound – the time when you navigated to the trial to start it).
See here an example trajectory file.