refTable-class {Rgb} | R Documentation

## Class `"refTable"`

### Description

This class is similar to the `data.frame` standard R class, following the object-oriented paradigm. The use of Reference Class system allows significative memory and time saving, making this class more suitable than `data.frame` to handle large tabular data.

Objects can be created by two distincts means :

- The `refTable` constructor, similar to the `data.frame` constructor. It imports a single `data.frame` or a collection of vectors into the object, and check immediatly for validity.

- The `new` function (standard behavior for S4 and reference classes), which produces an empty object and do NOT check for validity. You can provide as arguments the values to use as the new object fields, if you know what you are doing.

### Extends

All reference classes extend and inherit methods from `envRefClass`.

### Implementation

#### Data storage

refTable objects store data into their `values` field as vectors. As `values` is an environment, manipulating a refTable implies a pass-by-reference paradigm rather than the standard R pass-by-copy, i.e. data duplication (and so time and memory wasting) is widely reduced. As an example, updating a single cell in a `data.frame` leads to the duplication of the whole table in memory ('before' and 'after' versions), while in a refTable the duplication is limited to the involved column.

#### Column names

To facilitate column renaming, the vectors in `values` are not named according to the user-level column names, but according to references stored in the `colReferences` field (integers greater than 0 converted to characters). Rename a column only updates the `colNames` field and leave the `values` one alone, as the column reference does not change.

#### Data extraction

Data extracted from refTable are usually returned as `data.frame`, for a more comfortable R usage. The extraction mechanism handles `data.frame` extraction mechanisms, and relies on the `indexes` method to handle the others.

- Rows and columns may be selected by a numeric vector, as for R `data.frame` and vectors.

- They also may be selected by a logical vector, defining for each row / column if it is to be selected (`TRUE`) or not (`FALSE`). Such vectors are recycled if not long enough to cover all the rows / columns.

- A character vector defining the names of the rows / columns to select may also be used to extract data.

- The `NULL` value may be used to select all rows / columns.

- An unevaluated expression, as returned by `expression` or `parse` may be used to select rows in the table environment. See 'examples'.

### Fields

`colCount`:

  Single `integer` value, the amount of rows in the table.

`colIterator`:

  Single `integer` value, last column reference used.

`colNames`:

  `Character` vector, the names of all rows (may be empty).

`colReferences`:

  `Character` vector, the column names in the `values` environment.

`rowCount`:

  Single `integer` value, the amount of rows in the table.

`rowNamed`:

  Single `logical` value, whether row names should be considered or not.

`rowNames`:

  `Character` vector, the names of all rows (may be empty).

`values`:

  An `environment` storing the columns as vectors.

### Methods

`addColumn(content, name, after = )`:

  Adds a column in the table
  - content : values to fill in the new column, as a vector.
  - name : name of the new column, as character.
  - after : where to add the column, as the index (numeric) or name (character) of the column on its left

`addDataFrame(dataFrame)`:

  Adds a data.frame content to the refTable
  - dataFrame : the data to add.

`addEmptyRows(amount, newNames)`:

  Add rows filled with NA at the bottom of the table.
  - amount : single integer value, the amount of rows to add.
  - newNames : character vector, the names of the new rows. Ignored if the table is not row named.

`addList(dataList, row.names)`:

  Adds a list content to the refTable
  - dataList : the data to add.
  - row.names : character vector with the names of the enw rows.

`addVectors(..., row.names)`:

  Adds vectors to the refTable
  - ... : named vectors to add.

`check(warn = )`:

  Raises an error if the object is not valid, else returns TRUE

`coerce(j = , class, levels, ...)`:

  Coerces a single column to a different class
  - j : column index (numeric) or name (character).
  - class : name of the class to coerce 'j' to.
  - levels : if 'class' is factor, the levels to use.
  - ... : further arguments to be passed to the 'as' method (for atomics) or function (for other classes).

`colOrder(newOrder, na.last = , decreasing = )`:

  Reorder the columns of the tables (duplication / subsetting are NOT handled)
  - newOrder : new order to apply, as an integer vector of character vector of column names.

`delColumns(targets)`:

  Deletes a column from the table
  - targets : character vector, the name(s) of the column(s) to delete.

`erase()`:

  Remove all the rows and columns in the table.

`extract(i = , j = , drop = , asObject = )`:

  Extracts values into a data.frame or vector
  - i : row selection, see indexes() for further details.
  - j : column selection, see indexes() for further details.
  - drop : if TRUE and querying a single column, will return a vector instead of a data.frame.
  - asObject : if TRUE results will be served in the same class as the current object.

`fill(i = , j = , newValues)`:

  Replaces values in a single column
  - i : row indexes (numeric) or names (character). NULL or missing for all rows.
  - j : column index (numeric) or name (character).
  - newValues : vector of values to put in the object

`getColCount()`:

  'colCount' field accessor.

`getColNames()`:

  'colNames' field accessor.

`getLevels(j = )`:

  Get levels of a factor column
  - j : column index (numeric) or name (character).

`getRowCount()`:

  'rowCount' field accessor.

`getRowNames()`:

  'rowNames' field accessor.

`indexes(i, type = )`:

  Checks row or column references and return numeric indexes
  - i : reference to the rows or columns to select (NA not allowed), as :
  - missing or NULL (all rows or columns)
  - vector of numeric indexes to select
  - vector of character indexes to select (if the dimension is named)
  - vector of logical with TRUE on each value to select, FALSE otherwise
  - expression object (as returned by e(...)), to be evaluated in the 'values' environment

`initialize(rowCount = , rowNames = , rowNamed = , colCount = , colNames = , colReferences = , colIterator = , values = , ...)`:
`metaFields()`:

  Returns a character vector of fields that do not directly depend on the tabular content, for clonage.

`rowOrder(newOrder, na.last = , decreasing = )`:

  Reorder the rows of the tables (duplication / subsetting are handled)
  - newOrder : new order to apply, as an integer vector of row indexes or a character vector of column names.
  - na.last : to be passed to order(), if 'newOrder' is a column name vector.
  - decreasing : to be passed to order(), if 'newOrder' is a column name vector.

`setColNames(j, value)`:

  Replaces one or many column names.
  - j : subset of columns to rename.
  - value : new column names to use, as a character vector.

`setLevels(j = , newLevels)`:

  Get or replace levels of a factor column
  - j : column index (numeric) or name (character).
  - newLevels : new levels to use, as a character vector.

`setRowNames(value)`:

  Replaces the entire row names set.
  - value : new row names to use in the table, as a character vector. NULL will disable row naming.

`types(j = )`:

  Returns classes of selected columns
  - j : column indexes or names (NULL for all columns)

The following methods are inherited (from the corresponding class):

- callSuper (envRefClass)

- copy (envRefClass, overloaded)

- export (envRefClass)

- field (envRefClass)

- getClass (envRefClass)

- getRefClass (envRefClass)

- import (envRefClass)

- initFields (envRefClass)

- show (envRefClass, overloaded)

- trace (envRefClass)

- untrace (envRefClass)

- usingMethods (envRefClass)

### Author(s)

Sylvain Mareschal

### Examples

      # New empty refTable
      tab <- new("refTable")
      tab$addColumn(1:5, "C1")
      tab$addColumn(letters[1:5], "C2")
      tab$setRowNames(LETTERS[11:15])

      # New filled refTable (same content)
      tab <- refTable(C1=1:5, C2=letters[1:5], row.names=LETTERS[11:15])

      # Whole table print
      print(tab$extract())

      # Data update
      tab$fill(c(2,4), 2, c("B","D"))

      # Data extraction
      print(tab$extract(1:3))
      print(tab$extract(c(TRUE, FALSE)))
      print(tab$extract("K", "C1"))

      # Expression-based extraction
      expr <- expression(C1 %% 2 == 1)
      print(tab$extract(expr))

      # Table extension
      tab$addEmptyRows(5L, LETTERS[1:5])
      tab$fill(6:10, "C1", 6:10)
      print(tab$extract())

      # Filling from R objects
      tab <- new("refTable")
      print(tab$extract())
      tab$addVectors(C1=1:5, C2=letters[1:5])
      print(tab$extract())
      tab$addList(list(C1=6:8, C3=LETTERS[6:8]))
      print(tab$extract())

      # Beware of recycling !
      tab$addVectors(C1=9:15, C3=LETTERS[9:10])
      print(tab$extract())

[Package Rgb version 1.6.1 Index]