requery_seq: Requery sequential context of segment list in an emuDB

Description

Function to requery sequential context of a segment list queried from an emuDB

Usage

requery_seq(
  emuDBhandle,
  seglist,
  offset = 0,
  offsetRef = "START",
  length = 1,
  ignoreOutOfBounds = FALSE,
  resultType = "tibble",
  calcTimes = TRUE,
  timeRefSegmentLevel = NULL,
  verbose = FALSE
)

Value

result set object of class emuRsegs or tibble

Arguments

emuDBhandle: emuDB handle as returned by load_emuDB
seglist: segment list to requery on (type: 'tibble' or 'emuRsegs')
offset: start item offset in sequence (default is 0, meaning the start or end item of the input segment)
offsetRef: reference item for offset: 'START' for first and 'END' for last item of segment
length: item length of segments in the returned segment list
ignoreOutOfBounds: ignore result segments that are out of bundle bounds
resultType: type of result (either 'tibble' == default, 'emuRsegs')
calcTimes: calculate times for resulting segments (results in NA values for start and end times in emuseg/emuRsegs). As it can be very computationally expensive to calculate the times for large nested hierarchies, it can be turned off via this boolean parameter.
timeRefSegmentLevel: set time segment level from which to derive time information. It is only necessary to set this parameter if more than one child level contains time information and the queried parent level is of type ITEM.
verbose: be verbose. Set this to TRUE if you wish to choose which path to traverse on intersecting hierarchies. If set to FALSE (the default) all paths will be traversed (= legacy EMU behaviour).

Details

Builds a new segment list on the same hierarchical level and the same length as the segment list given in seglist. The resulting segments usually have different start position and length (in terms of items of the respective level) controlled by the offset, offsetRef and length parameters. A segment here is defined as a single item or a chain of items from the respective level, e.g. if a level in a bundle instance has labels 'a', 'b' and 'c' in that order, 'a' or 'a->b' oder 'a->b->c' are all valid segments, but not 'a->c'. offsetRef determines if the position offset is referenced to the start or the end item of the segments in the input list seglist; parameter offset determines the offset of the resulting item start position to this reference item; parameter length sets the item length of the result segments. If the requested segments are out of bundle item boundaries and parameter ignoreOutOfBounds is FALSE (the default), an error is generated. To get residual resulting segments that lie within the bounds the ignoreOutOfBounds parameter can be set to TRUE. The returned segment list is usually of the same length and order as the input seglist; if ignoreOutOfBounds=FALSE, the resulting segment list may be out of sync.

Examples

Run this code

if (FALSE) {

##################################
# prerequisite: loaded ae emuDB 
# (see ?load_emuDB for more information)

## Requery previous item of 'p' on level 'Phonetic'
sl1 = query(ae, "Phonetic == p")

requery_seq(ae, sl1, offset = -1)

## Requery context (adding previuos and following elements) 
## of 'p' on phonetic level

requery_seq(ae, sl1, offset = -1, length = 3)

## Requery previous item of n->t sequence
sl2 = query(ae, "[Phoneme == n -> Phoneme == t]")

requery_seq(ae, sl2, offset = -1)

## Requery last item within n->t sequence

requery_seq(ae, sl2, offsetRef = 'END')

## Requery following item after n->t sequence

requery_seq(ae, sl2, offset = 1, offsetRef = 'END')

## Requery context (previous and following items) of n->t sequence

requery_seq(ae, sl2, offset = -1, length = 4)

## Requery next word contexts (sequence includes target word)

sl3 = query(ae, "Text == to")
requery_seq(ae, sl3, length = 2)

## Requery following two word contexts, ignoring segment 
## sequences that are out of bundle end bounds 
requery_seq(ae, sl3, length = 3, ignoreOutOfBounds = TRUE)

}