reg2regdef: Convert region file to region definition file.

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

Convert region file to region definition file.

Description

Convert a file containing full region description into a region definition file. The latter is suitable for hand editing and can be used to generate alternative region specifications (e.g., multi word regions) for text stimuli.

Usage

reg2regdef(reg, scrnW = NA, scrnH = NA, fnt.name = NA, fnt.size = NA,
  chrW = NA, chrH = NA, ln.space = NA, baseline = NA, mrgn.top = NA,
  mrgn.left = NA, mrgn.bottom = NA, mrgn.right = NA, rgn.maxH = NA,
  rgn.minH = NA, rgn.padL = NA, rgn.padR = NA)

Arguments

reg	A data.frame containing region specifications, as read from a region file ("*.region.csv").
scrnW	Screen width in pixels (integer).
scrnH	Screen height in pixels (integer).
fnt.name	Font name used for stimulus text.
fnt.size	Nominal font size in points for text display.
chrW	Letter width in pixels.
chrH	Nominal letter height in pixels.
ln.space	Line spacing in pixels for multi line texts. Multi line texts are not currently supported.
baseline	Baseline positions for each line of text. Measured in pixels from the top of the screen. Multi line texts are not currently supported.
mrgn.top	Top margin in pixels.
mrgn.left	Left margin in pixels.
mrgn.bottom	Bottom margin in pixels.
mrgn.right	Right margin in pixels.
rgn.maxH	Extent of regions of interest above baseline in pixels.
rgn.minH	Extent of regions of interest below baseline in pixels.
rgn.padL	Expand leftmost region on each line leftward by this amount in pixels.
rgn.padR	Expand rightmost region on each line rightward by this amount in pixels.

Details

We aspire to handle input files (region files) for multi line texts, but at present only region files for single line texts are handled.

File parameter values are used to fill in parameters written to the yaml block of the region definition file. Note that few of these parameters are important when the region definition file is used to create a new region file. Three parameters are critical to proper region definitions.

chrW

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). If not specified in the function call, chrW is estimated from contents of region.csv file, and will probably be correct most of the time. Regardless, it should be checked and corrected if necessary (i.e., specified in the function call).

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.

mrgn.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 optional parameters (rgn.minH, rgn.maxH, rgn.padL, rgn.padR) can be used to control various aspects of region extent.

To Do:

ToDo: This function presently does not work for regioning multi-line text stimuli. Fix that. stims.

ToDo: Make a simuliar function to read/parse SRR IAS files and build region defs based on them.

Value

A vector of strings containing the region definition. The vector includes a yaml block with values for each of the function parameters except for "reg". In addition to the yaml block, the vector will include 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 dots ("."), and pipe ("|") characters. Pipes indicate the beginnings of regions. By default, the region definition file will specify that each text line be exhaustively dividied into space delimited regions (i.e. there will be a pipe character corresponding to each space character in the paired text line.

This vector can be written to file and hand edited to add or correct information in the yaml block, or to re-specify region placements.

Author(s)

Dave Braze [e-mail]

See Also

regdef2ias

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