utils (utils.R)

Melting GCT objects

Transform a GCT object to long form (aka ‘melt’).

melt.gct(g, suffixes=NULL, remove_symmetries=F, keep_rdesc=T, keep_cdesc=T)

@description Utilizes the \code{\link{data.table::melt}} function to transform the
  matrix into long form. Optionally can include the row and column
  annotations in the transformed \code{\link{data.table}}.

@param g the GCT object
@param keep_rdesc boolean indicating whether to keep the row
  descriptors in the final result
@param keep_cdesc boolean indicating whether to keep the column
  descriptors in the final result
@param remove_symmetries boolean indicating whether to remove
  the lower triangle of the matrix (only applies if \code{g@mat} is symmetric)
@param suffixes the character suffixes to be applied if there are
  collisions between the names of the row and column descriptors

@return a \code{\link{data.table}} object with the row and column ids and the matrix
  values and (optinally) the row and column descriptors

@examples
# simple melt, keeping both row and column meta
head(melt.gct(ds))

# update row/colum suffixes to indicate rows are genes, columns experiments
head(melt.gct(ds, suffixes = c("_gene", "_experiment")))

# ignore row/column meta
head(melt.gct(ds, keep_rdesc = F, keep_cdesc = F))

@family GCT utilities

Concatenating

Merge two GCT objects

merge.gct(g1, g2, dimension="row", matrix_only=F)

@param g1 the first GCT object
@param g2 the second GCT object
@param dimension the dimension on which to merge (row or column)
@param matrix_only boolean idicating whether to keep only the
  data matrices from \code{g1} and \code{g2} and ignore their
  row and column meta data

@examples
# take the first 10 and last 10 rows of an object
# and merge them back together
(a <- subset.gct(ds, rid=1:10))
(b <- subset.gct(ds, rid=969:978))
(merged <- merge.gct(a, b, dimension="row"))

@family GCT utilities
@export

Slicing

Slice a GCT object using the provided row and/or column ids

subset.gct(g, rid=NULL, cid=NULL)

@param g a gct object
@param rid a vector of character ids or integer indices for ROWS
@param cid a vector of character ids or integer indices for COLUMNS

@examples
# first 10 rows and columns by index
(a <- subset.gct(ds, rid=1:10, cid=1:10))

# first 10 rows and columns using character ids
(b <- subset.gct(ds, rid=ds@rid[1:10], cid=ds@cid[1:10]))

identical(a, b) # TRUE

@family GCT utilities

Annotating

Given a GCT object and either a data.frame or a path to an annotation table, apply the annotations to the GCT using the given keyfield.

annotate.gct(g, annot, dimension="row", keyfield="id")

@description Given a GCT object and either a \code{\link{data.frame}} or
a path to an annotation table, apply the annotations to the
gct using the given \code{keyfield}.

@param g a GCT object
@param annot a \code{\link{data.frame}} or path to text table of annotations
@param dimension either 'row' or 'column' indicating which dimension
  of \code{g} to annotate
@param keyfield the character name of the column in \code{annot} that
  matches the row or column identifiers in \code{g}

@return a GCT object with annotations applied to the specified
  dimension

@examples
\dontrun{
 g <- parse.gctx('/path/to/gct/file')
 g <- annotate.gct(g, '/path/to/annot')
}

@family GCT utilities

Transpose

transpose.gct(g)

@param g the \code{GCT} object

@return a modified verion of the input \code{GCT} object
  where the matrix has been transposed and the row and column
  ids and annotations have been swapped.

@examples
transpose.gct(ds)

@family GCT utilties
@export

Math

Convert values in a matrix to ranks

rank.gct(g, dim="row")
@param g the \code{GCT} object to rank
@param dim the dimension along which to rank
  (row or column)

@return a modified version of \code{g}, with the
  values in the matrix converted to ranks

@examples
(ranked <- rank.gct(ds, dim="column"))
# scatter rank vs. score for a few columns
plot(ds@mat[, 1:3], ranked@mat[, 1:3],
  xlab="score", ylab="rank")

@family GCT utilities