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.
regdef2ias(fname)A string containing the name of a "region definition" file, such as might be created by reg2regdef(). See Details.
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.
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.
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.
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.
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.
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)