R: Get or set document-level variables

docvars {quanteda} | R Documentation

## Get or set document-level variables

### Description

Get or set variables associated with a document in a corpus, tokens or dfm object.

### Usage

    docvars(x, field = NULL)

    docvars(x, field = NULL) <- value

    ## S3 method for class 'corpus'
    x$name

    ## S3 replacement method for class 'corpus'
    x$name <- value

    ## S3 method for class 'tokens'
    x$name

    ## S3 replacement method for class 'tokens'
    x$name <- value

    ## S3 method for class 'dfm'
    x$name

    ## S3 replacement method for class 'dfm'
    x$name <- value

### Arguments

`x` | corpus, tokens, or dfm object whose document-level variables will be read or set
`field` | string containing the document-level variable name
`value` | a vector of document variable values to be assigned to `name`
`name` | a literal character string specifying a single docvars name

### Value

`docvars` returns a data.frame of the document-level variables, dropping the second dimension to form a vector if a single docvar is returned.

`docvars<-` assigns `value` to the named `field`

### Accessing or assigning docvars using the `$` operator

As of quanteda v2, it is possible to access and assign a docvar using the `$` operator. See Examples.

### Note

Reassigning document variables for a tokens or dfm object is allowed, but discouraged. A better, more reproducible workflow is to create your docvars as desired in the corpus, and let these continue to be attached "downstream" after tokenization and forming a document-feature matrix. Recognizing that in some cases, you may need to modify or add document variables to downstream objects, the assignment operator is defined for tokens or dfm objects as well. Use with caution.

### Examples

    # retrieving docvars from a corpus
    head(docvars(data_corpus_inaugural))
    tail(docvars(data_corpus_inaugural, "President"), 10)
    head(data_corpus_inaugural$President)

    # assigning document variables to a corpus
    corp <- data_corpus_inaugural
    docvars(corp, "President") <- paste("prez", 1:ndoc(corp), sep = "")
    head(docvars(corp))
    corp$fullname <- paste(data_corpus_inaugural$FirstName,
                           data_corpus_inaugural$President)
    tail(corp$fullname)

    # accessing or assigning docvars for a corpus using "$"
    data_corpus_inaugural$Year
    data_corpus_inaugural$century <- floor(data_corpus_inaugural$Year / 100)
    data_corpus_inaugural$century

    # accessing or assigning docvars for tokens using "$"
    toks <- tokens(corpus_subset(data_corpus_inaugural, Year <= 1805))
    toks$Year
    toks$Year <- 1991:1995
    toks$Year
    toks$nonexistent <- TRUE
    docvars(toks)

    # accessing or assigning docvars for a dfm using "$"
    dfmat <- dfm(toks)
    dfmat$Year
    dfmat$Year <- 1991:1995
    dfmat$Year
    dfmat$nonexistent <- TRUE
    docvars(dfmat)

[Package quanteda version 3.0.0 Index]