Annotation functionality — annotations • polmineR

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.

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

x	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.
i	The row number (single `integer` value) of the `data.table` where a new value shall be assigned.
j	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

use("polmineR")
#> ... activating corpus: GERMAPARLMINI (version: 0.0.1 | build date: 2019-02-23)
#> ... activating corpus: REUTERS
a <- 2
# 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)
#>     match_id
#>  1:        1
#>  2:        2
#>  3:        3
#>  4:        4
#>  5:        5
#>  6:        6
#>  7:        7
#>  8:        8
#>  9:        9
#> 10:       10
#> 11:       11
#> 12:       12
#> 13:       13
#> 14:       14
#> 15:       15
#> 16:       16
#> 17:       17
#> 18:       18
#> 19:       19
#> 20:       20
#> 21:       21
#> 22:       22
#> 23:       23
#> 24:       24
#> 25:       25
#> 26:       26
#> 27:       27
#> 28:       28
#> 29:       29
#> 30:       30
#> 31:       31
#> 32:       32
#> 33:       33
#> 34:       34
#> 35:       35
#> 36:       36
#> 37:       37
#> 38:       38
#> 39:       39
#> 40:       40
#> 41:       41
#> 42:       42
#> 43:       43
#> 44:       44
#> 45:       45
#> 46:       46
#> 47:       47
#> 48:       48
#> 49:       49
#> 50:       50
#> 51:       51
#> 52:       52
#> 53:       53
#> 54:       54
#> 55:       55
#> 56:       56
#> 57:       57
#> 58:       58
#> 59:       59
#> 60:       60
#> 61:       61
#> 62:       62
#> 63:       63
#> 64:       64
#> 65:       65
#> 66:       66
#> 67:       67
#> 68:       68
#> 69:       69
#> 70:       70
#> 71:       71
#> 72:       72
#> 73:       73
#> 74:       74
#> 75:       75
#> 76:       76
#> 77:       77
#> 78:       78
#>     match_id

# 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
#>     match_id class description
#>  1:        1     a            
#>  2:        2     a            
#>  3:        3     a            
#>  4:        4     a            
#>  5:        5     a            
#>  6:        6     a            
#>  7:        7     a            
#>  8:        8     a            
#>  9:        9     a            
#> 10:       10     a            
#> 11:       11     a            
#> 12:       12     a            
#> 13:       13     a            
#> 14:       14     a            
#> 15:       15     a            
#> 16:       16     a            
#> 17:       17     a            
#> 18:       18     a            
#> 19:       19     a            
#> 20:       20     a            
#> 21:       21     a            
#> 22:       22     a            
#> 23:       23     a            
#> 24:       24     a            
#> 25:       25     a            
#> 26:       26     a            
#> 27:       27     a            
#> 28:       28     a            
#> 29:       29     a            
#> 30:       30     a            
#> 31:       31     a            
#> 32:       32     a            
#> 33:       33     a            
#> 34:       34     a            
#> 35:       35     a            
#> 36:       36     a            
#> 37:       37     a            
#> 38:       38     a            
#> 39:       39     a            
#> 40:       40     a            
#> 41:       41     a            
#> 42:       42     a            
#> 43:       43     a            
#> 44:       44     a            
#> 45:       45     a            
#> 46:       46     a            
#> 47:       47     a            
#> 48:       48     a            
#> 49:       49     a            
#> 50:       50     a            
#> 51:       51     a            
#> 52:       52     a            
#> 53:       53     a            
#> 54:       54     a            
#> 55:       55     a            
#> 56:       56     a            
#> 57:       57     a            
#> 58:       58     a            
#> 59:       59     a            
#> 60:       60     a            
#> 61:       61     a            
#> 62:       62     a            
#> 63:       63     a            
#> 64:       64     a            
#> 65:       65     a            
#> 66:       66     a            
#> 67:       67     a            
#> 68:       68     a            
#> 69:       69     a            
#> 70:       70     a            
#> 71:       71     a            
#> 72:       72     a            
#> 73:       73     a            
#> 74:       74     a            
#> 75:       75     a            
#> 76:       76     a            
#> 77:       77     a            
#> 78:       78     a            
#>     match_id class description

# 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)
#>     match_id class description
#>  1:        1     a            
#>  2:        2     a            
#>  3:        3     a            
#>  4:        4     a            
#>  5:        5     a            
#>  6:        6     a            
#>  7:        7     a            
#>  8:        8     a            
#>  9:        9     a            
#> 10:       10     a            
#> 11:       11     a            
#> 12:       12     a            
#> 13:       13     a            
#> 14:       14     a            
#> 15:       15     a            
#> 16:       16     a            
#> 17:       17     a            
#> 18:       18     a            
#> 19:       19     a            
#> 20:       20     a            
#> 21:       21     a            
#> 22:       22     a            
#> 23:       23     a            
#> 24:       24     a            
#> 25:       25     a            
#> 26:       26     a            
#> 27:       27     a            
#> 28:       28     a            
#> 29:       29     a            
#> 30:       30     a            
#> 31:       31     a            
#> 32:       32     a            
#> 33:       33     a            
#> 34:       34     a            
#> 35:       35     a            
#> 36:       36     a            
#> 37:       37     a            
#> 38:       38     a            
#> 39:       39     a            
#> 40:       40     a            
#> 41:       41     a            
#> 42:       42     a            
#> 43:       43     a            
#> 44:       44     a            
#> 45:       45     a            
#> 46:       46     a            
#> 47:       47     a            
#> 48:       48     a            
#> 49:       49     a            
#> 50:       50     a            
#> 51:       51     a            
#> 52:       52     a            
#> 53:       53     a            
#> 54:       54     a            
#> 55:       55     a            
#> 56:       56     a            
#> 57:       57     a            
#> 58:       58     a            
#> 59:       59     a            
#> 60:       60     a            
#> 61:       61     a            
#> 62:       62     a            
#> 63:       63     a            
#> 64:       64     a            
#> 65:       65     a            
#> 66:       66     a            
#> 67:       67     a            
#> 68:       68     a            
#> 69:       69     a            
#> 70:       70     a            
#> 71:       71     a            
#> 72:       72     a            
#> 73:       73     a            
#> 74:       74     a            
#> 75:       75     a            
#> 76:       76     a            
#> 77:       77     a            
#> 78:       78     a            
#>     match_id class description

if (FALSE) {
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)
}