regdef2ias: Convert region definition file to SRR Interest Area file.

In davebraze/FDBeye: Functions to Ease Work with Eyetracker Data

Convert region definition file to SRR Interest Area file.

Description

Convert a region definition file to an SRR Interest Area file (*.ias). The latter can be hand edited to specify alternative region specifications (e.g., multi word regions) for text stimuli.

Usage

regdef2ias(fname)

Arguments

fname

A string containing the name of a "region definition" file, such as might be created by reg2regdef(). See Details.

Details

regdef2ias can handle region definitions for either single-line or multi-line texts.

Parameter values are read from the yaml block of the region definition file. Note that a few of these parameters are important when translating region definitions to interest areas.

A region definition file contains 2 parts. The first is a yaml block, which is followed by a region block.

Yaml Block:

Three parameters in the yaml block are critical to proper region definitions. Four others are also useful, but optional.

character$width

This parameter is used to translate region boundaries in x dimension from letter positions (as specified in the region definition file) to pixel positions (as required for the region or ias file). Character width (in pixels) is not explicitly encoded in a region file, but is typically estimated from contents of region.csv file, and will probably be correct most of the time. Regardless, it should be checked and, if necessary, manually edited in the resulting region definition file.

lines$baseline

Accurate baseline positions are also critical to determining the y positions of regions. Baselines are read directly from the region.csv file and should be accurate. Note that baseline positions, in pixels, are measured from the TOP of the screen.

margins$left

The left margin is an x offset that will be applied to all regions. There is no easy way to read this from a region file, so it will need to be specified in the function call. In most cases, it will be the same for all stimulus items.

Four additional parameters in the yaml block of the region definition file will be used to modify regions. They are: regions$maxH, regions$minH, regions$padL, and regions$padR.

Before running regdef2ias on a file, its yaml block can be hand edited to add or correct information. However, the easiest way to fill information in the yaml block will probably be to specify it in the form of parameters to reg2regdef or similar function used to create the region definition file in the first place.

Region Block:

The second part of a region definition file is the region block. This block contains a pair of lines for each line of text in the stimulus. The first element of each pair is the text displayed on that line. The second element is a regioning string made up of square brackets ("[", "]"), and pipe ("|") characters. An opening bracket ("[") indicates the start of a line and a closing bracket ("]) indicates the end of a line. Pipes ("|") indicate region boundaries within a line. By default, the region definition file will specify that each text line be exhaustively divided into space delimited regions (i.e. there will be a pipe character corrponding to each space character in the paired text line.)

Pairs of lines are required to be separated by at least one blank line for regdef2ias to parse multi-line texts.

Before running regdef2ias on a file, its region block can be hand edited to add or correct information to specify region placements.

Value

A data.frame specifying the content of an SRR interest area file (*.ias). Use readr::write_delim(..., delim="\n", col_names=FALSE) to save the interest area specification to file.

Author(s)

Dave Braze [e-mail]

Monica Li [e-mail]

See Also

reg2regdef

Examples

regdef_story1 <- system.file("extdata/story01-regdef.txt", package="FDBeye")

## Peek at regdef file.
peek <- readLines(regdef_story1)

## Generate an SRR DV compatible IAS file from the regdef file.
ias_story1 <- regdef2ias(regdef_story1)

davebraze/FDBeye documentation built on April 28, 2022, 1:20 a.m.