create_itemsInLevel: Create new items programmatically

In emuR: Main Package of the EMU Speech Database Management System

Create new items programmatically

Description

Allows creating annotation items programmatically on a single level. You have to pass in a data frame describing the new items. Each new item is identified by its session, bundle, level, and depending on the level type either:

• sequence index (start_item_seq_idx): when level type = ITEM

• start: start time in ms * 1000 (see output of query) when level type = EVENT

• start: start time in ms * 1000 () when level type = SEGMENT (creates gapless segment groups where the last segment ends at the end of the audio file)

. The level with its associated attributes determines how many labels must be provided. You must provide a label for every existing attribute.

Sessions, bundles, levels and attributes must exist beforehand. The sequence index is explained below.

Within each bundle, there can be multiple annotation items on every level. Their order within the level is given by their sequence index. All *existing* items have a natural-valued sequence index and there are no gaps in the sequences (i.e. if a level contains N annotation items, they are indexed 1..N).

Any newly created item must be given a sequence index. The sequence index may be real-valued (it will automatically be replaced with a natural value). To prepend the new item to the existing one, pass a value lower than one. To append it to the existing items, you can either pass NA or any value that you know is greater than n (the number of existing items in that level). It does not need to be exactly n+1. To place the new item between two existing ones, use any real value between the sequence indexes of the existing neighbors.

If you are appending multiple items at the same time, every sequence index (including NA) can only be used once per session/bundle/level combination (because session/bundle/level/sequence index are a unique identifier of an item's ).

After creating the items, all sequence indexes (which may now be real-valued, natural-valued or NA) are sorted in ascending order and then replaced with the values 1..n, where n is the number of items on that level. While sorting, NA values are placed at the end.

Usage

create_itemsInLevel(
  emuDBhandle,
  itemsToCreate,
  rewriteAllAnnots = TRUE,
  verbose = TRUE
)

Arguments

emuDBhandle	emuDB handle as returned by load_emuDB
itemsToCreate	A data frame with the columns session, bundle, level, start_item_seq_idx(start_item_seq_idx is used instead of seq_idx so that the result of a query call can be used directly. query can return a sequence of items defined by start_item_seq_idx and end_item_seq_idx which have the same value if single items are returned), attribute, and labels. *None* of the columns should be factors. sequenceIndex must be numeric (can be real-valued or natural-valued), all other columns must be of type character.
rewriteAllAnnots	should changes be written to file system (_annot.json files) (intended for expert use only)
verbose	if set to TRUE, more status messages are printed

emuR documentation built on Nov. 4, 2023, 1:06 a.m.