emuR (version 2.4.0)

autobuild_linkFromTimes: Autobuild links between two levels using their time information

Description

Autobuild links between two time levels. This is typically done when converting from a database / annotation format that allows parallel time tiers / levels but does not permit annotational units to be linked to each other, except by matching time information (such as Praat's TextGrid format). The super-level has to be of the type SEGMENT and the sub-level either of type EVENT or of type SEGMENT. If this is the case and a according link definition is defined for the emuDB, this function automatically links the events or segments of the sub-level which occur within (startSample to (startSample + sampleDur)) the segments of the super-level to those segments.

Usage

autobuild_linkFromTimes(
  emuDBhandle,
  superlevelName,
  sublevelName,
  rewriteAllAnnots = TRUE,
  convertSuperlevel = FALSE,
  backupLevelAppendStr = "-autobuildBackup",
  newLinkDefType = NULL,
  verbose = TRUE
)

Arguments

emuDBhandle

emuDB handle as returned by load_emuDB

superlevelName

name of level to link from (link definition required in emuDB)

sublevelName

name of level to link to (link definition required in emuDB)

rewriteAllAnnots

should changes be written to file system (_annot.json files) after completing autobuild process (intended for expert use only)

convertSuperlevel

if set to TRUE a backup of the superlevel will be created and the actual superlevel will be converted to a level of type ITEM

backupLevelAppendStr

string appended to level name for backup level

newLinkDefType

type of new linkDefinition (either "ONE_TO_MANY", "MANY_TO_MANY" or "ONE_TO_ONE") which is passed to add_linkDefinition. If NULL (the default) add_linkDefinition isn't called and a linkDefintion is expected to be present.

verbose

show progress bars and further information

Details

The type of link definition (ONE_TO_MANY, MANY_TO_MANY, ONE_TO_ONE) is relevant whether a link is generated or not (e.g. overlapping segments are linked in a MANY_TO_MANY relationship but not in a ONE_TO_MANY relationship). For more information on the structural elements of an emuDB see vignette(emuDB).

See Also

add_linkDefinition

Examples

if (FALSE) {

##################################
# prerequisite: loaded myTGcolDB emuDB 
# (see ?create_emuRdemoData, ?convert_TextGridCollection, 
#  and vignette(emuR_intro) for more information)

# add linkDefinition as one has to be present for
# the autobuild function to work
add_linkDefinition(emuDBhandle = myTGcolDB, 
                   type = "ONE_TO_MANY",
                   superlevelName = "Syllable",
                   sublevelName = "Phoneme")
  
# envoke autobuild function to build hierarchy for converted TextGridCollection
autobuild_linkFromTimes(emuDBhandle = myTGcolDB, 
                        superlevelName = "Syllable",
                        sublevelName = "Phoneme",
                        convertSuperlevel = TRUE)

}