11-07-2023, 13:04 (This post was last modified: 03-19-2026, 11:45 by kurt.)
Get Reading Measures 2 Overview
Get Reading Measures 2 (GRM2) is a tool that allows users to combine and/or shift critical interest area regions across trials and then extract dependent reading measures associated with those regions without having to manually re-define the interest area boundaries in Data Viewer. GRM2 takes Data Viewer Fixation Reports as input (i.e., a file where each row corresponds to a fixation and the columns provide information about that fixation). The output file will be like a Trial Report from Data Viewer, in that each row will represent one trial and the columns will provide the dependent reading measures for the critical region that is defined when you run the script. Importantly, GRM2 allows for flexibility in defining the critical text region for which reading measure will be output when using the script. To define the critical region, you specify a start word and end word, and these start/end can include 1) references to columns in the Fixation Report that specify the location (e.g., start/end word) of the region across trials and/or 2) simple addition/subtraction. This flexibility in the definition of the critical region provides the ability to combine interest areas into a larger region (e.g., a phrase-based rather than a word-based region) and/or shift the critical region location across trials (e.g., perhaps the critical region spans words 4-5 in one trial and words 7-12 in another trial). If you have multiple regions for which you would like to extract reading measures, then you can run GRM2 multiple times, and you don’t need to close the application within runs – just change the critical region start/end word definitions, change the name of the output file (and optionally the region label) and click Process Data again. Each time you do so it will generate a new output report where each row corresponds to a trial and the columns will provide the reading measures for that region. Any user-defined Trial Variables (i.e., the blue variables that you can include when creating the Fixation Report), like independent variables and/or behavioral data variables, will be included in the output of GRM2 as well. For an alternative method, using the existing interest areas in Data Viewer Interest Area Reports, please see the relevant Data Viewer FAQ: How do I extract Reading Measures from Data Viewer? A zip file (ORIGINAL_GRM_ARCHIVE.zip) containing the archived/original Get Reading Measures and an archived SPSS version of the original Get Reading Measures tool is attached to this post, as well. For definitions of the reading measures, see the document called "InstructionsForUseAndReadingMeasuresDefinitions.pdf" in the unzipped application directory, or the post below.
GRM2 released on Nov 7, 2023. Original GRM released in 2011.
GRM2 updated on Dec 1, 2023 to add support for Fixation Report codecs besides UTF-8 (previously only supported UTF-8 encoded Fixation Reports). This also adds support for special/non-ascii characters in variables
Using Get Reading Measures 2 Get Reading Measures 2 (GRM2) is an application created from a Python script, with compiled versions for Windows and Mac OS X (source file included in the zip file for each).
To use GRM2, first output a Fixation Report from Data Viewer. Make sure that the report includes the following variables:
RECORDING_SESSION_LABEL
TRIAL_INDEX
CURRENT_FIX_INDEX
CURRENT_FIX_DURATION
CURRENT_FIX_INTEREST_AREA_ID
Other user-defined Trial Variables (e.g., blue variables available in the Fixation Report dialog that were included when it was made), typically used to log the levels of independent variables and/or behavioral data, may also be included. All these Trial Variables will be included in the output file that GRM2 creates, and you can use any of those variables in the critical region start word/end word definitions, too. To run GRM2, download and extract the appropriate zip file attached to this post; "GetReadingMeasures2_Windows.zip" or "GetReadingMeasures2_macOS..zip". Then double-click "GetReadingMeasures2.exe" (or "GetReadingMeasures2.app" for macOS) from the extracted folder.
After running GRM2, first, choose an Input file (use Get Input File button) and an Output File (use Set Output File button). Specify the Critical Region Start Word and Critical Region End Word. Click Process Data. You should then have a new file that is like a Trial Report from Data Viewer (each row is a trial) with the reading measures appearing as columns in addition to the other Trial Variables that were included in the Fixation Report that you used as an input file.
One of the main advantages of the Get Reading Measures tool is that it provides options for how to specify the start and end word values to be used in defining the critical region:
You can use simple numbers for the start and end word values: Example:
Critical Region Start Word: 4
Critical Region End Word: 7
This will compute the reading measures for a critical region starting at word 4 and ending at word 7 for each trial in the input file.
Note: To compute reading measures for a one-word region the Critical Region Start Word and Critical Region End Word values should be the same.
You can make a reference to one or more columns in the Fixation Report that specify the locations of critical value(s) (i.e., word numbers) for each trial. References to column names should be surrounded by the @ character. Example (if the fixation report has columns called critregionstart and critregionend, which contain the word numbers for the start and end of the critical region for each trial):
Critical Region Start Word: @critregionstart@
Critical Region End Word: @critregionend@
This will compute the reading measures for a region starting at critregionstart and ending at critregionend for each trial in the input file.
You can use equations to change the region based on column(s) in the Fixation Report that specify the locations of critical value(s) (i.e., word numbers) for each trial. References to column names should be surrounded by the @ character. Example (if the Fixation Report has a column called critword):
Critical Region Start Word: @critword@
Critical Region End Word: @critword@ + 2
This will compute the reading measures for a three-word critical region starting at critword and ending one word after critword for each trial in the input file.
1. REGION_START_IA – The Interest Area ID of the first interest area in the region. 2. REGION_END_IA – The Interest Area ID of the last interest area in the region. 3. REGION_LABEL – The label of the region (optionally specified at runtime – if not specified then will be automatically generated based on the region start and end definitions. 4. SINGLE_FIXATION_DURATION – The duration of a fixation on the target region, provided that the region was fixated one time only during first pass reading, and that the one fixation did not occur after fixations on words further along in the text. Note: The value will be 0 if the region was fixated more than once during first pass reading. The value will be missing (“.”) if the region was skipped during first-pass reading. 5. FIRST_FIXATION_DURATION – The duration of the first fixation on a target region, provided that the first fixation did not occur after fixations on words further along in the text. Note: The value will be 0 if the region was skipped during first-pass reading. 6. GAZE_DURATION – The total duration of all fixations in a target region until the eyes fixate a region of text that is either progressive or regressive to the target region, provided that the first fixation on the target region does not occur after any fixations on words further along in the text. Note 1: This measure is typically referred to as “Gaze Duration” for one-word regions of text and “First Pass Duration” for multi -word regions of text. For simplicity here, this measure will be referred to as “Gaze Duration”, whether the region is one word in length or more than one word in length. Note 2: The value will be 0 if the region was skipped before during first-pass reading. 7. FIRST_PASS_FIXATION_COUNT – The number of fixations on the region during first pass reading (i.e., gaze duration reading), where first pass reading includes the first run on the region provided that the first fixation on the region did not occur after any fixations progressive to the region. 8. RIGHT_BOUNDED_DURATION – The total duration of all fixations in the target region un l the eyes fixate a region of text that is progressive to the target region, provided that the first fixation on the target region did not occur after any fixations on words further along in the text.
Note 1: This measure, as well as Regression Path Duration below, is sometimes referred to as Go Past Duration. These two definitions of Go-Past Duration are distinguished here by calling one Right Bounded Duration and the other Regression Path Duration.
Note 2: The value will be 0 if the region was skipped before during first-pass reading. 9. REGRESSION_PATH_DURATION – The total duration of all fixations that occurred, from the first fixation on a target region until the target region was exited in a progressive manner (including fixations on the target region and fixations on words regressive to the target region), provided that the first fixation on the target region did not occur a er any fixations on words further along in the text.
Note 1: This measure, as well as Right-Bounded Duration above, is sometimes referred to as Go-Past Duration. These two definitions of Go-Past Duration are distinguished here by calling one Right Bounded Duration and the other Regression Path Duration. Note 2: The value will be 0 if the region was skipped during first-pass reading.
10. REREADING_DURATION – The difference between Regression Path Duration and Gaze Duration (so, effectively including only fixations on regions regressive to the target region, and not any fixations on the target region itself).
Note: The value will be 0 if Regression Path Duration and Gaze Duration were the same for a given trial. The value will be missing (“.”) if the region was skipped during first-pass reading.
11. TOTAL_DURATION – The total duration of all fixations in the target region. Note: The value will be 0 if the region was not fixated at all during the trial.
12. TOTAL_FIXATION_COUNT – The total number of fixations in the target region. 13. RUN_COUNT – The number of runs of fixations in the region, where a run is a series of consecutive fixations on the same region. 14. RUN_DWELL_TIMES – A list of the dwell times (i.e., where dwell me is the sum of the fixation durations of the run) for each of the runs on the region. A run is a series of consecutive fixations on the same region. 15. RUN_FIXATION_COUNTS – A list of the fixation counts for each of the runs of fixations on the region, where a run is a series of consecutive fixations on the same region. 16. FIRST_PASS_REGRESSION — Whether the first fixation following fixation(s) on the target region is regressive relative to the target region or not, provided that 1) words further along in the text have not yet been fixated (i.e., the region was not skipped during first-pass reading) and that 2) the target region has not already been fixated and exited. Note: The value will be missing (“.”) if the region was skipped during first-pass reading. The value will be 1 if the fixation following first-pass fixation(s) on the target region was regressive. The value will be 0 if the fixation following first-pass fixation(s) on the target region was progressive. 17. FIRST_PASS_FIXATION – Whether the target region was fixated before any progressive text was fixated (as opposed to being skipped during first-pass reading). Note: The value will be 1 if the target region was fixated before any progressive text was fixated and 0 if the region was skipped during first-pass reading. 18. FIRST_PASS_MULTI_FIXATION – Whether the target region was fixated more than one consecutive time before any other text that is progressive or regressive to the region was fixated, provided that the target region was fixated at least once before any material progressive to the region was fixated (i.e., provided that the target region was not skipped during first-pass reading).
Note: The value will be 0 if the target region was only fixated once before any material progressive to the region was fixated (i.e., provided that the target region was not skipped during first-pass reading). The value will be missing (“.”) if the target region was skipped during first-pass reading. 19. REGRESSION_IN_COUNT – The number of regressions (i.e., movements from an interest area with a higher ID to an interest area with a lower ID) into the target region from a region with a higher ID. 20. REGRESSION_IN_PREV_IA_IDS – A list (in order of occurrence) of the IDs of the interest areas that were fixated before each regression into the target region from a region with a higher ID. 21. REGRESSION_IN_RUN_INDICES – A list (in order of occurrence) of the indices of the runs on the target region that were preceded by a regression into the target region from a region with a higher ID. A run is a series of consecutive fixations on the same region. 22. REGRESSION_OUT_COUNT – The number of regressions (i.e., movements from an interest area with a higher ID to an interest area with a lower ID) out of the target region into a region with a lower ID. 23. REGRESSION_OUT_NEXT_IA_IDS – A list (in order of occurrence) of The IDs of the interest areas that were fixated a er each regression out of the target region into a region with a lower ID. 24. REGRESSION_OUT_RUN_INIDICES – A list (in order of occurrence) of the indices of the runs on the target region that were followed by a regression out of the target region into a region with a lower ID. A run is a series of consecutive fixations on the same region. 25. PROGRESSION_IN_COUNT – The number of progressions (i.e., movements from an interest area with a lower ID to an interest area with a higher ID) into the target region from a region with a lower ID. 26. PROGRESSION_IN_PREV_IA_IDS -- A list (in order of occurrence) of the IDs of the interest areas that were fixated before each progression into the target region from a region with a lower ID. 27. PROGRESSION_IN_RUN_INDICES -- A list (in order of occurrence) of the indices of the runs on the target region that were preceded by a progression into the target region from a region with a lower ID. A run is a series of consecutive fixations on the same region. 28. PROGRESSION_OUT_COUNT -- The number of progressions (i.e., movements from an interest area with a lower ID to an interest area with a higher ID) out of the target region into a region with a higher ID. 29. PROGRESSION_OUT_NEXT_IA_IDS – A list (in order of occurrence) of the IDs of the interest areas that were fixated a er each progression out of the target region into a region with a higher ID.
30. PROGRESSION_IN_RUN_INDICES – A list (in order of occurrence) of the indices of the runs on the target region that were preceded by a progression into the target region from a region with a lower ID. A run is a series of consecutive fixations on the same region.
