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.
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
)A data.frame containing region specifications, as read from a region file ("*.region.csv").
Screen width in pixels (integer).
Screen height in pixels (integer).
Font name used for stimulus text.
Nominal font size in points for text display.
Letter width in pixels.
Nominal letter height in pixels.
Line spacing in pixels for multi line texts. Multi line texts are not currently supported.
Baseline positions for each line of text. Measured in pixels from the top of the screen. Multi line texts are not currently supported.
Top margin in pixels.
Left margin in pixels.
Bottom margin in pixels.
Right margin in pixels.
Extent of regions of interest above baseline in pixels.
Extent of regions of interest below baseline in pixels.
Expand leftmost region on each line leftward by this amount in pixels.
Expand rightmost region on each line rightward by this amount in pixels.
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.
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.
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).
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 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.