refTable-class: Class '"refTable"'

In Rgb: The R Genome Browser

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())

Rgb documentation built on Aug. 18, 2023, 5:05 p.m.