class_container_extractors: Container: extract parts of a Container object
In jeanmathieupotvin/cargo: Data containers, schemas and prototypes

Description Usage Arguments Details Value Note See Also Examples

Usual operators to subset and manipulate an object of class Container.

## S4 method for signature 'Container,missing,missing,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'Container,expression,expression,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'Container,expression,missing,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'Container,missing,expression,missing'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'Container,ANY,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'Container,ANY,missing'
x[[i, j, ...]]

## S4 method for signature 'Container,ANY,ANY'
x[[i, j, ...]]

## S4 method for signature 'Container'
x$name

## Convenient wrapper for expressions
e(expr)

`x`	an object of class `Container`.
`i, j`	elements to subset on and/or extract. These can be: integer, logical or character vector or an expression wrapped into function `e()`. Check the descriptions of arguments `i` and `j` of `data.table`.
`...`	optional arguments passed to `[.data.table` such as `by`, `.SDcols`, etc.
`drop`	a logical. If `TRUE`, the result is coerced to the lowest possible dimension. Never use this argument if expressions are passed to `i` and/or `j`.
`name`	a column `name` in slot `table`.
`expr`	an `expression`.

To modify subsets of the table stored in an instance of class Container, use either data.table's :=() operator or set() function. Modifications are done by reference.

Package cargo needs to know you are passing (unevaluated) data.table expressions to the operator [. To do so, wrap arguments i and j with function e(). See examples below.

All operators works on the table slot.

They are not endomorphism and do not return objects of class Container. Instead, a subset of slot table is returned in various ways that depends on the operator and on the arguments' signature.

Operator [ always returns a data.table, sometimes invisibly. This depends on what is passed to argument j.
Operators [[ and $ both return a vector with a class that matches the extracted column's class.

This note is irrelevent for most users, but must still appear somewhere.

The data.table class relies on the non-standard evaluation mechanism of R: expressions passed to functions arguments are not evaluated upon a function call. Instead, R evaluates them only when it is forced to.

Unfortunately, package methods' dispatch mechanism breaks this feature, because it needs to know the arguments' signature to dispatch a method on it. This is very problematic for what cargo is trying to achieve.

The workaround is to protect expressions from early evaluation. R only needs to know they are proper expressions, not their result. Hence, the solution is to wrap expressions passed to i and j arguments, so that they can be evaluated within the frame of table later. The function e() is a convenient shortcut doing just that.

Other Container: Container-accessors, Container-class, Container-methods, Container-validators, is_container()

## Construct an object of class Container from a data.table and a Schema.
myTable <- data.table::data.table(
    field1 = c("s1", "s2", "s3"),
    field2 = c(1L, 2L, 3L),
    field3 = c(47.13, 48.72, 53.32),
    field4 = c(-122.56, -79.12, -114.67)
)

mySchema <- Schema(
    inputs = c("field1", "field2", "field3", "field4"),
    prototypes = list(
        Prototype(character()),
        Prototype(integer()),
        Prototype(numeric()),
        Prototype(numeric()))
)

myCont <- Container(myTable, mySchema)

## Say we need to compute conditional sums of values in numeric columns.
myTable[field2 > 0L, base::colSums(.SD),
        .SDcols = c("field2", "field3", "field4")]

## The cargo way would be to write
myCont[cargo::e(field1 > 0L), cargo::e(base::colSums(.SD)),
       .SDcols = c("field2", "field3", "field4")]

## The latter is equivalent to writing this expression.
cargo::table(myCont)[field1 > 0L, base::colSums(.SD),
                     .SDcols = c("field2", "field3", "field4")]