annotations: Annotation functionality

Description

Objects that contain analytical results (kwic objects, objects inheriting from the textstat class) can be annotated by creating an annotation layer using the annotations-method. The augmented object can be annotated using a shiny gadget by invoking the edit-method on it. Note that operations are deliberately in-place, to prevent an unwanted loss of work.

Usage

annotations(x, ...)
# S4 method for kwic
annotations(x, i, j, value)
# S4 method for textstat
annotations(x, i, j, value)
annotations(x) <- value
# S4 method for kwic,list
annotations(x) <- value
# S4 method for textstat,list
annotations(x) <- value
# S4 method for textstat
edit(name, viewer = shiny::paneViewer(minHeight =
  550), ...)

Arguments

An object to be annotated, a kwic class object, or an object inheriting from the textstat class.

...

Passed into rhandsontable::rhandsontable, can be used for settings such as height etc.

The row number (single integer value) of the data.table where a new value shall be assigned.

The column number (single integer value) of the data.table where a new value shall be assigned.

value

A value to assign.

name

An S4 object to be annotated.

viewer

The viewer to use, see viewer.

Value

The modified input object is returned invisibly.

Details

The edit-method is designed to be used in a RStudio session. It generates a shiny gadget (see https://shiny.rstudio.com/articles/gadgets.html) shown in the viewer pane of RStudio.

The edit-method returns the modified input object. Note however that changes of annotations are deliberately in-place operations: The input object is changed even if you do not close the gadget "properly" by hitting the "Done" button and catch the modified object. That may be forgotten easily and would be painful after the work that may have been invested.

Consult the examples for the intended workflow.

Examples

Run this code

# NOT RUN {
use("polmineR")

# upon initializing a kwic object, there is a minimal labels object
# in the labels slot of the kwic object, which we can get using the
# annotations-method
o <- kwic("REUTERS", query = "oil")
annotations(o) # see the result (a data.table)

# assign new annotations as follows, using the reference semantics of the
# data.table you get by calling the labels-method on an object 
annotations(o) <- list(name = "class", what = factor(x = "a", levels = c("a", "b", "c")))
annotations(o) <- list(name = "description", what = "")
annotations(o) # inspect the result

# assign values; note that is an in-place operation using the reference
# semantics of the data.table
# annotations(o, i = 77, j = 1, value = FALSE)
# annotations(o, i = 78, j = 1, value = FALSE)
annotations(o)

# }
# NOT RUN {
edit(o)
annotations(o) # to see changes made

# maybe we want additional metadata
enrich(o, s_attributes = "places")
edit(o)
annotations(o)

# to get some extra context
o <- enrich(o, extra = 5L, table = TRUE)
edit(o)

# lineview may be better when you use a lot of extra context
options(polmineR.lineview = TRUE)
o <- kwic("REUTERS", "oil")
o <- enrich(o, extra = 20L)
edit(o)

x <- cooccurrences("REUTERS", query = "oil")
annotations(x) <- list(name = "keep", what = TRUE)
annotations(x) <- list(name = "category", what = factor("a", levels = letters[1:10]))
edit(x)
# }