create_itemsInLevel: Create new items programmatically

Description Usage Arguments

View source: R/emuR-annotations_crud.R

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:

. 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

1
2
3
4
5
6
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 June 11, 2021, 5:10 p.m.