Package 'ribiosExpression'

Description

The function annotates an object of eSet, or a vector of characters representing probesets.

Usage

annotate(object, target, check.target, ...)

Arguments

Details

Once successfully annotated, the annotation slot of the eSet object is set to the value of target.

Value

An eSet, or a data.frame containing annotation information of the probesets.

Author(s)

Jitao David Zhang <[email protected]>

Examples

data(ribios.ExpressionSet)
myset <- ribios.ExpressionSet[100:105,]

## eSet
## Not run: 
annotate(myset, "HG_U95AV2")
annotate(myset, "HG_U_95AV2", check.target=TRUE)

## End(Not run)

## characters
## Not run: 
annotate(featureNames(myset), "HG_U95AV2")

## End(Not run)

Description

Assert whether a matrix is of full rank numerically

Usage

assertFullRank(matrix)

Arguments

Value

If not full rank, the function stops. Otherwise, an invisible TRUE is returned

Examples

myMat <- matrix(c(1,1,1,0,1,1), ncol=2, byrow=FALSE)
assertFullRank(myMat)

Description

Extract the contrast annotation data.frame from an object

Usage

contrastAnnotation(object)

## S4 method for signature 'DesignContrast'
contrastAnnotation(object)

## S4 replacement method for signature 'DesignContrast'
contrastAnnotation(object) <- value

Arguments

Value

A data.frame annotating contrasts

Methods (by class)

• contrastAnnotation(DesignContrast): Return the contrast annotation data.frame from a DesignContrast object

• contrastAnnotation(DesignContrast) <- value: Assign a contrast annotation data.frame to a contrastContrast object

Description

Assign contrast annotation to an object

Usage

contrastAnnotation(object) <- value

Arguments

Value

The modified object

Description

Extract the contrast matrix from an object

Usage

contrastMatrix(object)

## S4 method for signature 'DesignContrast'
contrastMatrix(object)

## S4 replacement method for signature 'DesignContrast'
contrastMatrix(object) <- value

## S4 method for signature 'MArrayLM'
contrastMatrix(object)

Arguments

Value

A numeric contrast matrix

Methods (by class)

• contrastMatrix(DesignContrast): Return the contrast matrix from a DesignContrast object

• contrastMatrix(DesignContrast) <- value: Assign a contrast matrix to a contrastContrast object

• contrastMatrix(MArrayLM): Extract contrast matrix from an object of MArrayLM

Description

Assign contrast matrix to an object

Usage

contrastMatrix(object) <- value

Arguments

Value

The modified object

Description

Extract contrastNames from an object

Usage

contrastNames(object)

## S4 method for signature 'DesignContrast'
contrastNames(object)

## S4 method for signature 'MArrayLM'
contrastNames(object)

Arguments

Value

A character vector of contrast names

Methods (by class)

• contrastNames(DesignContrast): Return contrast names, i.e., column names of the contrast matrix

• contrastNames(MArrayLM): Extract contrast names from an object of MArrayLM

Description

Return indices of samples involved in the given contrast of two or more coefficients

Usage

contrastSampleIndices(object, contrast)

## S4 method for signature 'DesignContrast,character'
contrastSampleIndices(object, contrast)

## S4 method for signature 'DesignContrast,numeric'
contrastSampleIndices(object, contrast)

Arguments

Value

An integer vector, indices of samples that are involved, sorted by the ascending order of the coefficients of the contrast

Methods (by class)

• contrastSampleIndices(object = DesignContrast, contrast = character): Use character string to specify the contrast

• contrastSampleIndices(object = DesignContrast, contrast = numeric): Use integer indices to specify the contrast

Examples

## one-way ANOVA
myDesCon <- parseDesignContrast(sampleGroups="As,Be,As,Be,As,Be",
   groupLevels="Be,As", dispLevels="Beryllium,Arsenic", contrasts="As-Be")
contrastSampleIndices(myDesCon, 1L)
myInterDesCon <- DesignContrast(
    designMatrix=matrix(c(rep(1,6), rep(0,2), rep(1,2), rep(0,2),
           rep(0,4), rep(1,2)), nrow=6, byrow=FALSE),
    contrastMatrix=matrix(c(0,1,0, 0,0,1, 0,-1,1), byrow=FALSE, nrow=3),
    groups=factor(rep(c("As", "Be", "Cd"), each=2)),
    dispLevels=c("Arsenic", "Beryllium", "Cadmium"))
cont1Ind <- contrastSampleIndices(myInterDesCon, 1L)
cont2Ind <- contrastSampleIndices(myInterDesCon, 2L)
cont3Ind <- contrastSampleIndices(myInterDesCon, 3L)
stopifnot(identical(cont1Ind, 1:4))
stopifnot(identical(cont2Ind, c(1:2, 5:6)))
stopifnot(identical(cont3Ind, c(3:6)))

Description

Build a data.frame from two vectors of potential different lengths

Usage

dataFrameTwoVecs(vec1, vec2, col.names = c("Vec1", "Vec2"))

Arguments

Value

A data.frame of two columns. The row count matches the longer vector

Examples

dataFrameTwoVecs(LETTERS[1:5], letters[2:9])

Description

Infer groups from a design matrix

Usage

design2group(designMatrix)

Arguments

Value

A factor vector giving the groups inferred from the design matrix

A naive logic is used: samples of the same design vectors are of the same group.

The inference is known to fail when control variables, such as age or RIN numbers, vary between samples of the same group.

Examples

myDesign <- model.matrix(~gl(3,3))
design2group(myDesign)

Description

Contrast a DesignContrast object

Usage

DesignContrast(
  designMatrix,
  contrastMatrix = NULL,
  groups = NULL,
  dispLevels = NULL,
  contrastAnnotation = NULL
)

Arguments

Value

A DesignContrast object

Examples

myFac <- gl(3,3, labels=c("baseline", "treat1", "treat2"))
myDesign <- model.matrix(~myFac)
colnames(myDesign) <- c("baseline", "treat1", "treat2")
myContrast <- limma::makeContrasts(contrasts=c("treat1", "treat2"), levels=myDesign)
DesignContrast(myDesign, myContrast, groups=myFac)
DesignContrast(myDesign, myContrast, groups=myFac, dispLevels=c("C", "T1", "T2"))

Description

The DesignContrast class represents key information in a designed experiment

Usage

## S4 method for signature 'DesignContrast'
show(object)

Arguments

Functions

• show(DesignContrast): The show method

Slots

design

A numeric matrix. The number of rows equals the sample size. The columns corresponds to the variables of design

contrasts

A numeric matrix. The number of rows equals the number of columns in the design matrix. The columns corresponds to the comparisons one wishes to make.

groups

A factor vector, giving sample groups. The length equals the number of samples.

dispLevels

A character vector, used for displaying sample groups. The length equals the number of levels of the groups factor.

contrastAnnotation

A data.frame, used to annotate the contrasts.

Objects from the Class

Objects can be created by calls of the function DesignContrast. However, the users should not directly call this function. Instead, parseDesignContrast should be called.

Description

Extract the design matrix from an object

Usage

designMatrix(object)

## S4 method for signature 'DesignContrast'
designMatrix(object)

## S4 replacement method for signature 'DesignContrast'
designMatrix(object) <- value

## S4 method for signature 'MArrayLM'
designMatrix(object)

Arguments

Value

A numeric design matrix

Methods (by class)

• designMatrix(DesignContrast): Return the design matrix from a DesignContrast object

• designMatrix(DesignContrast) <- value: Assign a design matrix to a DesignContrast object

• designMatrix(MArrayLM): Extract design matrix from an object of MArrayLM

Description

Assign design matrix to an object

Usage

designMatrix(object) <- value

Arguments

Value

The modified object

Description

Extract design variable names from an object

Usage

designVariables(object)

## S4 method for signature 'DesignContrast'
designVariables(object)

Arguments

Value

A character vector of variable names

Methods (by class)

• designVariables(DesignContrast): Return the names of variables (column names) in the design matrix of a DesignContrast object

Description

Extract displayed group labels from an object

Usage

dispGroups(object)

## S4 method for signature 'DesignContrast'
dispGroups(object)

Arguments

Value

A factor of display group labels

Methods (by class)

• dispGroups(DesignContrast): Return the sample groups from a DesignContrast object , using display labels

Description

Transform eSet to long data.frame

Usage

eSetToLongTable(
  x,
  exprsFun = function(eset) Biobase::exprs(eset),
  includeOtherAssayData = FALSE
)

Arguments

Details

The function extracts exprs (and other values in the assayData environment), and return it in a long data.frame format with phenotypic data

Value

A data.frame in long format.

Examples

data(ribios.ExpressionSet, package="ribiosExpression")
exprsLongTbl <- eSetToLongTable(ribios.ExpressionSet)
seLongTbl <- eSetToLongTable(ribios.ExpressionSet, 
   exprsFun=function(eset) Biobase::assayData(eset)$se.exprs)

Description

Transform an expression matrix to long table

Usage

exprsToLong(x, ...)

## S4 method for signature 'matrix'
exprsToLong(
  x,
  idvar = "illID",
  timevar = "hybridID",
  valuevar = "value",
  ids = rownames(x),
  valueType = "raw"
)

## S4 method for signature 'eSet'
exprsToLong(x)

Arguments

Value

A data.frame

Methods (by class)

• exprsToLong(matrix): The method for matrix as input

• exprsToLong(eSet): The method for eSet as input

Description

Fix design matrix colnames so that they are legal variable names

Usage

fixDesignMatrixColnames(
  designMatrix,
  interceptChar = "_",
  removeContrastNames = TRUE
)

Arguments

Value

The matrix with fixed colum names.

Examples

myFac1 <- gl(6,2, labels=sprintf("Fac1_%d", 1:6))
myFac2 <- gl(2,6, labels=c("Ctrl", "Dis"))
myVar <- rnorm(12)
myDesign <- model.matrix(~myFac1 * myFac2 + myVar)
head(myDesign)
head(fixDesignMatrixColnames(myDesign))

Description

Detect if any column has an empty string as name and fix

Usage

fixEmptyColumnName(df, prefix = "X")

Arguments

Details

If any column has an empty string as name, its replaced by the prefix appended by an index starting from 1

Value

A data.frame with fixed column names.

Examples

testDf <- data.frame("Col1"=LETTERS[1:3], "Col2"=letters[2:4])
colnames(testDf) <- c("", "")
testDf
fixEmptyColumnName(testDf)
fixEmptyColumnName(testDf, prefix="fData")

Description

Resulting string(s) can be exported into GMT file by writeLines

Usage

formatGmt(title, comment, genes)

## S4 method for signature 'character,character,character'
formatGmt(title, comment, genes)

## S4 method for signature 'character,missing,character'
formatGmt(title, genes)

## S4 method for signature 'character,character,list'
formatGmt(title, comment, genes)

## S4 method for signature 'character,missing,list'
formatGmt(title, genes)

Arguments

Value

One or more lines of GMT file

Methods (by class)

• formatGmt(title = character, comment = character, genes = character): title, comment, and genes are one character string

• formatGmt(title = character, comment = missing, genes = character): title and genes are both one character string, comments are missing

• formatGmt(title = character, comment = character, genes = list): title and comments are both vectors of character strings, genes are a list of the same length

• formatGmt(title = character, comment = missing, genes = list): title is vectors of character strings, comments are missing, genes are a list of the same length as the title

Author(s)

Jitao David Zhang <[email protected]>

Examples

formatGmt(title="GeneSet0", comment="My geneset", genes=c("MAPT", "MAPK", "AKT1"))
formatGmt(title="GeneSet0", genes=c("MAPT", "MAPK", "AKT1"))

formatGmt(title=c("GeneSet0", "GeneSet1"),
          comment=c("My geneset 0", "My geneset 1"),
          genes=list(c("MAPT", "MAPK", "AKT1"), c("EGFR", "CDC42")))
formatGmt(title=c("GeneSet0", "GeneSet1"),
          comment="My genesets",
          genes=list(c("MAPT", "MAPK", "AKT1"), c("EGFR", "CDC42")))
formatGmt(title=c("GeneSet0", "GeneSet1"),
          genes=list(c("MAPT", "MAPK", "AKT1"), c("EGFR", "CDC42")))

Description

Extract sample groups from an object

Usage

groups(object)

## S4 method for signature 'DesignContrast'
groups(object)

Arguments

Value

A factor of sample groups

Methods (by class)

• groups(DesignContrast): Return the raw sample groups from a DesignContrast object

Description

GRP files are used by Connectivity Map on-line tool, which stores the information of a rank-ordered list of probesets. They are simply one-column text files, each line containing one probeset. grpFiles2gmt convert GRP files into GMT-formatted strings, which can be written in GMT files to be used by GSEA and other tools.

Usage

grp2gmt(txt, chiptype, name)

grpFiles2gmt(..., chiptype, n = -1L)

Arguments

Details

The function grp2gmt, called by grpFiles2gmt internally, annotates probesets when chiptype is supported by GTI, and transform them into the GMT format.

If chiptype is provided, the annotate function is called to fetch probeset annotations from the databank.

Value

A vector of character strings, each containing one line of a GMT file. They can be written to a file with the writeLines function.

Note

It is user's responsibility to check that all GRP files do exist and are readable.

Author(s)

Jitao David Zhang <[email protected]>

References

See https://www.broadinstitute.org/connectivity-map-cmap for the use of GRP files in the Connectivity Map web tool.

Examples

up.file <- system.file("extdata/tags_up.grp", package="ribiosExpression")
down.file <- system.file("extdata/tags_down.grp", package="ribiosExpression")
grp2gmt(readLines(up.file, n=-1))
grpFiles2gmt(c(up.file, down.file), n=3)

## Not run: 
grp2gmt(readLines(up.file, n=-1), chiptype="HG_U95AV2")
grpFiles2gmt(c(up.file, down.file), n=-1L, chiptype="HG_U95AV2")

## End(Not run)

Description

Test whether the input design matrix is consistent with the sample names

Usage

isInputDesignConsistent(descon, sampleNames)

Arguments

Value

A invisible logical value. TRUE if and only if the sample names match perfectly.

Description

The function filters features (commonly probesets) in an ExpressionSet object. It does not affect genes with only one feature present, or genes without an valid annotation (see details below). For genes with multiple probesets, the function calculates the statistic of each probeset across all samples and filter probesets by only keeping the one with the maximum of variance. Thereby an ExpressionSet returned by the function has only one probeset matching each gene.

Usage

keepMaxStatProbe(
  eset,
  probe.index.name,
  keepNAprobes = TRUE,
  stat = function(x) mean(x, na.rm = TRUE),
  ...
)

Arguments

Details

Names of probesets are determined by the featureNames(eset) function.

The column of probe.index.name in the fData(eset) data.frame determines the index of genes, for example the Entrez GeneID, to which probesets are matched. Those genes without a valid index, whose index is either an empty string or NA, can be set to be left out by keepNAprobes=FALSE. If the option is set as TRUE, then these genes are kept in the returning object.

The stat function should only return one statistic, most favorably not NA, by taking a vector of numerical values. Most statistics can be calculated in a robust way by setting na.rm=TRUE. This option should be always used whenver possible. Otherwise when there is one or more missing value of a probeset, its statistic will probably be NA and this will lead to discard the probeset. Even worse, when all probesets matching to a gene have NAs, the gene will be totally filtered out, which is usually not desired. Therefore, set na.rm=TRUE through the ... option (see examples below) whenever possible.

Value

An filtered ExpressionSet.

Note

Note that when the statistics of two or more probesets tie (having the same value), the probeset chosed could be random (the probeset with its name ranked first when multiple names are converted into a factor vector).

Author(s)

Jitao David Zhang <[email protected]>

Examples

library("Biobase")

example.mat <- matrix(c(1,1,3,4, 2,2,3,3, 4,5,6,7, 7,8,9,10), ncol=4, byrow=TRUE)
example.eset <- new("ExpressionSet", exprs=example.mat)

featureNames(example.eset) <- c("1a","1b","2","3")
fData(example.eset)$geneid <- c(1,1,2,3)

## keep probesets with the maximal variance
example.sd <- keepMaxStatProbe(example.eset, probe.index.name="geneid", stat=sd)
featureNames(example.sd)

## keep probesets with the maximal Median Absolute Deviation (MAD)
example.mad <- keepMaxStatProbe(example.eset, probe.index.name="geneid", stat=mad)
featureNames(example.mad)

## keep probesets with the maximal mean value
example.mean <- keepMaxStatProbe(example.eset,
probe.index.name="geneid", stat=mean)
featureNames(example.mean)

## note that NA value may cause problems, it is a good practice to make
## the stat function _resist_ to NA
na.eset <- example.eset
exprs(na.eset)[1,1] <- NA

## Not run: 
## prone to error
na.mean <- keepMaxStatProbe(na.eset,
probe.index.name="geneid",stat=mean)
featureNames(na.mean)
## better
na.mean.narm <- keepMaxStatProbe(na.eset,
probe.index.name="geneid",na.rm=TRUE)
featureNames(na.mean.narm)

## End(Not run)

Description

Return dgeTable from a marrayLM object

Usage

limmaDgeTable(marrayLM, contrast = NULL, confint = TRUE)

Arguments

Value

A data.frame

Description

Transform limma::topTable results to a DGEtable

Usage

limmaTopTable2dgeTable(limmaTopTable)

Arguments

Value

A data.frame known as DGEtable which has controlled column names

Examples

example.sd <- 0.3*sqrt(4/rchisq(100,df=4))
example.y <- matrix(rnorm(100*6,sd=example.sd),100,6)
example.y[1:2,4:6] <- example.y[1:2,4:6] + 2
rownames(example.y) <- paste("Gene",1:100)
example.design <- cbind(Grp1=1,Grp2vs1=c(0,0,0,1,1,1))
example.fit <- limma::lmFit(example.y,example.design)
example.fit <- limma::eBayes(example.fit)
example.tt <- limma::topTable(example.fit, coef=2)
example.dt <- limmaTopTable2dgeTable(example.tt)
head(example.dt)

Description

Transform a matrix to long table

Usage

matrixToLongTable(x, valueLabel = "value", rowLabel = "row", colLabel = "col")

Arguments

Value

A data.frame

Examples

myMatrix <- matrix(rnorm(24), nrow=4, dimnames=list(LETTERS[1:4], letters[1:6]))
matrixToLongTable(myMatrix)

Description

Merge two eSets by column binding

Usage

mergeEset(eset1, eset2, by.x, by.y, normalization = "quantile")

Arguments

Value

A new eSet object

Description

Extract the number of contrasts from an object

Usage

nContrast(object)

## S4 method for signature 'DesignContrast'
nContrast(object)

Arguments

Value

An integer, number of contrasts

Methods (by class)

• nContrast(DesignContrast): Return the number of contrasts in a DesignContrast object

Description

Parse contrast from strings

Usage

parseContrastStr(contrastStr)

Arguments

Value

A contrast matrix

Description

Parse study design and asked questions encoded in design and contrast matrices or in one-way ANOVA designs

Usage

parseDesignContrast(
  designFile = NULL,
  contrastFile = NULL,
  sampleGroups = NULL,
  groupLevels = NULL,
  dispLevels = NULL,
  contrasts = NULL,
  expSampleNames = NULL
)

Arguments

Value

A S4-object 'DesignContrast'

Examples

## one-way ANOVA
parseDesignContrast(sampleGroups="As,Be,As,Be,As,Be",groupLevels="Be,As",
    dispLevels="Beryllium,Arsenic", contrasts="As-Be")
## design/contrast matrix
designFile <- system.file("extdata/example-designMatrix.txt",
    package="ribiosExpression")
contrastFile <- system.file("extdata/example-contrastMatrix.txt",
    package="ribiosExpression")
# minimal information
parseDesignContrast(designFile=designFile, contrastFile=contrastFile)
# with extra information about sample groups
parseDesignContrast(designFile=designFile, contrastFile=contrastFile,
    sampleGroups="As,Be,As,Be,As,Be",
    groupLevels="Be,As", dispLevels="Beryllium,Arsenic")

Description

Parse design and contrast from files

Usage

parseDesignContrastFile(
  designFile,
  contrastFile,
  groupsStr = NULL,
  levelStr = NULL,
  dispLevelStr
)

Arguments

Value

A DesignContrast object

Description

Parse design and contrast from strings

Usage

parseDesignContrastStr(groupsStr, levelStr, dispLevelStr, contrastStr)

Arguments

Value

A DesignContrast object

Description

The function plots a ComplexHeatmap containing two matrices, one of the design matrix and the other of the contrast matrix.

Usage

## S3 method for class 'DesignContrast'
plot(
  x,
  y = NULL,
  title = NULL,
  clusterDesign = FALSE,
  clusterSamples = FALSE,
  clusterContrasts = FALSE,
  designRange = NULL,
  contrastRange = NULL,
  designParams = NULL,
  contrastParams = NULL,
  ...
)

Arguments

Value

Heatmap object

Examples

myFac <- gl(3,3, labels=c("baseline", "treat1", "treat2"))
myDesign <- model.matrix(~myFac)
colnames(myDesign) <- c("baseline", "treat1", "treat2")
myContrast <- limma::makeContrasts(contrasts=c("treat1", "treat2"), levels=myDesign)
res1 <- DesignContrast(myDesign, myContrast, groups=myFac)
res2 <- DesignContrast(myDesign, myContrast, groups=myFac, dispLevels=c("C", "T1", "T2"))
plot(res1, title="DesCon 1")
plot(res2, title="DesCon 1 (identical)")
plot(res2, title="DesCon 1 (identical)", designRange=c(-2,2), 
    contrastRange=c(-2,1),
    designParams=list(row_names_gp=grid::gpar(fontsize=8)),
    contrastParams=list(column_names_gp=grid::gpar(fontsize=12, color="red")))

Description

Read in an annotation file in the tsv-format, with or without row names

Usage

readAnnotationFile(file, outputKeyName = "FeatureName", ...)

Arguments

Value

A data.frame containing the annotation, with the first column named as outputKeyName that contains feature identifiers as character strings. In case the input table contains the column with the same name, the content in that column must match the row names, otherwise an error is reported.

This function is called by readFeatureAnnotationFile and readSampleAnnotationFile. Normal users are unlikely to use it.

Examples

f1 <- system.file("extdata",
  "featureAnnotation/featureAnnotationFile-withRowNames.txt", 
  package="ribiosExpression")
f2 <- system.file("extdata",
  "featureAnnotation/featureAnnotationFile-withoutRowNames.txt", 
  package="ribiosExpression")
# 'FeatureName' does not exist in the column names of f1
f1Read <- readAnnotationFile(f1, outputKeyName="FeatureName") 
# 'GeneID' exists in the colum names of f2, and it is the first column.
f2Read <- readAnnotationFile(f2, outputKeyName="GeneID")
head(f1Read)
head(f2Read)

Description

Read eSet object from plain files

Usage

readEset(
  exprs.file,
  fData.file,
  pData.file,
  exprs.file.format = c("gct", "tsv"),
  sep = "\t",
  header = TRUE,
  ...
)

Arguments

Details

The function can read in eSet object saved by writeEset by parsing three plain text files: exprs.file, fData.file, and pData.file.

Currently both tsv and gct formats are supported for expression file.

See writeEset for limitations of these functions.

Value

An ExpressionSet object.

See Also

writeEset, readFKtable.

Examples

data(sample.ExpressionSet, package="Biobase")
fData(sample.ExpressionSet) <- data.frame(
 ProbeID=featureNames(sample.ExpressionSet),
 row.names=featureNames(sample.ExpressionSet))
exprs.file <- tempfile()
fData.file <- tempfile()
pData.file <- tempfile()
writeEset(sample.ExpressionSet, exprs.file, fData.file, pData.file,
exprs.file.format="gct")
testRead1 <- readEset(exprs.file, fData.file, pData.file, exprs.file.format="gct")
writeEset(sample.ExpressionSet, exprs.file, fData.file, pData.file,
exprs.file.format="tsv")
testRead2 <- readEset(exprs.file, fData.file, pData.file, exprs.file.format="tsv")

Description

The function reads in an expression matrix into an ExpressionSet object. The expression matrix should be saved in the file format supported by the read_exprs_matrix function: currently supported formats include tab-delimited file and gct files.

Usage

readExprsMatrix(x)

Arguments

Details

The function is a wrapper of the read_exprs_matrix function in the ribiosIO package. The difference is it returns a valid ExpressionSet object instead of a primitive matrix.

Value

An ExpressionSet object holding the expression matrix. Both pData and fData are empty except for the feature/sample names recorded in the expression matrix.

Author(s)

Jitao David Zhang <[email protected]>

See Also

read_exprs_matrix in the ribiosIO package.

Examples

idir <- system.file("extdata", package="ribiosExpression")
myeset <- readExprsMatrix(file.path(idir, "sample_eset_exprs.txt"))
myeset2 <- readExprsMatrix(file.path(idir, "test.gct"))

Description

Read in feature annotation file in the tsv-format, with or without row names

Usage

readFeatureAnnotationFile(file, ...)

Arguments

Value

A data.frame containing feature annotation, with the first column named as 'FeatureName' that contains feature identifiers as character strings. In case the input table contains the column 'FeatureName', the content in that column must match the row names, otherwise an error is reported.

Examples

f1 <- system.file("extdata",
  "featureAnnotation/featureAnnotationFile-withRowNames.txt", 
  package="ribiosExpression")
f2 <- system.file("extdata",
  "featureAnnotation/featureAnnotationFile-withoutRowNames.txt", 
  package="ribiosExpression")
f1Read <- readFeatureAnnotationFile(f1)
f2Read <- readFeatureAnnotationFile(f2)
head(f1Read)
head(f2Read)

Description

The concept Foreign Keys comes from relational databse systems. These keys can be used to cross-reference tables. Say we have two data.frames, one contains gene annotations and the other contains protein annotations. A column named mRNArefseqID may be the foreign key that can be used to specify relationships between gene and proteins.

Usage

readFKtable(file, fk, strict.order = FALSE, ...)

Arguments

Details

The readFKtable reads a table from file, and checks if it contains provided foreign keys: either as row.names or in the first column.

Value

A data.frame if the FK-matching was successful, otherwise the function will print an error message and stop.

Author(s)

Jitao David Zhang <[email protected]>

Examples

test.file <- tempfile()
fk.teams <- c("HSV", "FCB", "BVB")
## FK in row names
test.mat <- matrix(rnorm(9), nrow=3, dimnames=list(fk.teams, NULL))
write.table(test.mat, test.file)
readFKtable(test.file, fk=fk.teams)

## or: FK can be in the first column
test.df <- data.frame(team=fk.teams, pts=c(15,14,15),plc=c("H", "G", "H"))
write.table(test.df, test.file)
readFKtable(test.file, fk=fk.teams)

## try strict.order=TRUE
test.df <- data.frame(pts=c(15,14,13), plc=c("H", "G", "H"), row.names=rev(fk.teams))
write.table(test.df, test.file)
readFKtable(test.file, fk=fk.teams, strict.order=FALSE)
## Not run: readFKtable(test.file, fk=fk.teams, strict.order=TRUE)

Description

As complementary functions to writeGctCls, readGctCls reads a pair of gct and cls files (with same base names) into an ExpressionSet object.

Usage

readGct(gct.file)

readGctCls(file.base, gct.file, cls.file, add.fData.file, add.pData.file)

Arguments

Details

The readGctCls function calls internally the readGct and read_cls functions to read in two formats respeectively. readGct returns a barely annotated ExpressionSet object, and read_cls returns a vector of levels encoding sample groups.

Since gct/cls contains only one property of features and samples each (Description in the gct file as well as sample groups/levels in the cls file), readGctCls allows users to provide additional fData/pData files. They should be tab-delimited files, with first column machting exactly the names of features or samples. They must be within the path specified by the path option, namely in the same directory of gls/cls files.sample

See example below.

Value

A ExpressionSet object

An ExpressionSet object. The Description column in the gct file is encoded in the desc column in the featureData of the resulting object. The sample groups in the cls file is encoded in the cls column in the phenoData.

Functions

• readGct(): readGct uses the C implementation of reading in a gct file

Note

The readGct function is a wrapper of the read_gct_matrix function in the ribiosIO package, which makes up the GCT matrix into an ExpressionSet object.

Author(s)

Jitao David Zhang <[email protected]>

See Also

writeGctCls. See read_gct_matrix for underlying C code to import GCT files.

Examples

idir <- system.file("extdata", package="ribiosExpression")

sample.eset <- readGctCls(file.base=file.path(idir, "test"))

ext.eset <- readGctCls(file.base=file.path(idir, "test"),
add.fData.file=file.path(idir, "test.add.fData.txt"),
add.pData.file=file.path(idir, "test.add.pData.txt"))

stopifnot(identical(exprs(sample.eset), exprs(ext.eset)))

## try to compare pData(sample.eset) with pData(ext.eset), and similarly
## fData(sample.eset) with fData(ext.eset)

Description

Read in sample annotation file in the tsv-format, with or without row names

Usage

readSampleAnnotationFile(file, ...)

Arguments

Value

A data.frame containing sample annotation, with the first column named as 'ExperimentName' that contains sample identifiers as character strings. In case the input table contains the column 'ExperimentName', the content in that column must match the row names, otherwise an error is reported.

Examples

f1 <- system.file("extdata",
  "sampleAnnotation/sampleAnnotationFile-withRowNames.txt", 
  package="ribiosExpression")
f2 <- system.file("extdata",
  "sampleAnnotation/sampleAnnotationFile-withoutRowNames.txt", 
  package="ribiosExpression")
f1Read <- readSampleAnnotationFile(f1)
f2Read <- readSampleAnnotationFile(f2)
head(f1Read)
head(f2Read)

Description

The function is used to transform an eSet object, which is annotated by Bioconductor annotation packages, into an object with annotation information from GTI.

Usage

reannotate(object, check.target, ...)

Arguments

Details

The translation between Bioconductor annotation package names and GTI chip types is performed by the bioc2gti function in the ribiosAnnotation package.

Once the re-annotation succeeds, the annotation slot of the eSet object will be overwritten by the corresponding chip type name in GTI.

Value

An eSet object with feature annotations updated by GTI, and the annotation slot is changed to the chip type in GTI.

Author(s)

Jitao David Zhang <[email protected]>

See Also

annotate to annotate an eSet object without prior information of bioc-annotation, or if that information is not saved in the annotation slot.

Examples

data(ribios.ExpressionSet)
print(ribios.ExpressionSet)

## Not run: 
gti.eSet <- reannotate(ribios.ExpressionSet)
gti.eSet <- reannotate(ribios.ExpressionSet, check.target=FALSE)
print(gti.eSet)

## End(Not run)

Description

Remove all-zero variables from design matrix and the corresponding contrast matrix

Usage

removeAllZeroVar(obj, contrasts)

## S3 method for class 'matrix'
removeAllZeroVar(obj, contrasts)

## S3 method for class 'DesignContrast'
removeAllZeroVar(obj, contrasts = NULL)

Arguments

Value

Either a list of two matrices (design and contrasts), or a DesignContrast object, depending on the input parameter type. The design matrix and contrast matrix have an attribute each, notEstCoefs and notEstContrasts, that keep track of filtered variables and contrasts.

Methods (by class)

• removeAllZeroVar(matrix): S3 function for matrix as input

• removeAllZeroVar(DesignContrast): S3 function for matrix as input

Examples

myTestDesign <- matrix(c(1,1,1,1, 1,1,0,0,0,0,1,1,0,0,0,0), 
  byrow=FALSE, nrow=4L, 
  dimnames=list(sprintf("S%d", 1:4), c("Baseline", "Trt1", "Trt2", "Trt3")))
myTestContrast <- matrix(c(0,1,0,0, 0,0,1,0, 0,0,0,1), nrow=4L, byrow=FALSE,
  dimnames=list(colnames(myTestDesign), c("Trt1", "Trt2", "Trt3")))
removeAllZeroVar(myTestDesign, myTestContrast)
removeAllZeroVar(DesignContrast(myTestDesign, myTestContrast))

Description

Return rank of the matrix and the ranks of resulting matrices when each column is removed

Usage

removeColRank(matrix)

Arguments

Value

A data.frame with n+1 rows, where n is the column count of the input matrix

Examples

myMat <- matrix(c(1,1,1, 0,1,1, 0,0,1, 1,0,0), ncol=4, byrow=FALSE)
removeColRank(myMat)

Description

This object is adapted from the sample.ExpressionSet object, with feature annotations from GTI (Data stand: December 2011). It is used in case studies where functionalities of the ribiosExpression package are demonstrated.

Format

An ExpressionSet object.

References

Jitao David Zhang <[email protected]>

Examples

data(ribios.ExpressionSet)
tbl <- eSetToLongTable(ribios.ExpressionSet)

Description

ribiosExpressionSet: An example of ExpressionSet with artificial expression data

Format

An ExpressionSet object.

Author(s)

Jitao David Zhang [email protected]

Examples

data(ribiosExpressionSet)

Description

Perform row-wise scaling to an ExpressionSet object

Usage

## S3 method for class 'ExpressionSet'
rowscale(x, center = TRUE, scale = TRUE)

Arguments

Value

An ExpressionSet object with row-scaled expression values.

Description

Sniff the feature type of an object that implements the featureNames method

Usage

sniffFeatureType(object, majority = 0.5)

Arguments

Value

A character string indicating likely feature type.

See Also

guessFeatureType

Description

Split an eSet object and run PCA on each split, return PCA scores as one data.frame

Usage

splitPCA(eset, factor, func = function(e) exprs(e), ...)

Arguments

Value

A data.frame of PCA scores combined from all splits.

Examples

data(ribios.ExpressionSet, package="ribiosExpression")
fac1 <- gl(2,13)
pcaScore1 <- splitPCA(ribios.ExpressionSet, fac1)

Description

The summarizeRows function summarizes (collapses) rows of a numeric matrix by calculating summarizing statistics of rows that belong to the same factor level.

Usage

summarizeProbesets(
  eset,
  index.name,
  fun = mean,
  keep.nonindex = FALSE,
  keep.featureNames = FALSE,
  ...
)

Arguments

Details

summarizeRows is called internally by summarizeProbesets to collapse probesets that belong to one index (e.g. GeneID).

The action of this function is univariate: namely the fun is applied to all probesets on each sample independently. For example, if fun is mean, the average value of mutliple probesets is taken for each sample. With this function, there is no way to distinguish probesets on their expression profiles (for instance: find the probeset with the maximum average signal).

Value

An ExpressionSet, with probesets summarized by indices specified.

Author(s)

Jitao David Zhang <[email protected]>

See Also

summarizeRows in the ribiosUtils package.

Examples

data(ribios.ExpressionSet, package="ribiosExpression")
ribios.mean <- summarizeProbesets(ribios.ExpressionSet,
index.name="GeneID", fun=mean)
ribios.mean

data(ribios.ExpressionSet, package="ribiosExpression")
ribios.mean.keepFeatureNames <- summarizeProbesets(ribios.ExpressionSet,
index.name="GeneID", fun=mean, keep.featureNames=TRUE)
ribios.mean

ribios.inval.mean <- summarizeProbesets(ribios.ExpressionSet,
index.name="GeneID", fun=mean, keep.nonindex=TRUE)

## the underlying method
ribios.meanMat <- ribiosUtils::summarizeRows(exprs(ribios.ExpressionSet),
fData(ribios.ExpressionSet)$GeneID, mean)
stopifnot(identical(exprs(ribios.mean), ribios.meanMat))

## keep old featureNames
ribios.inval.mean.old <- summarizeProbesets(ribios.ExpressionSet,
index.name="GeneID", fun=mean, keep.nonindex=TRUE, keep.featureNames=TRUE)

Description

The function takes an eSet object and a factor of the same length as the object, and summarizes samples of the same factor level by applying the function.

Usage

summarizeSamples(
  eset,
  indSamples = eset$SAMPLEID,
  removeInvarCols = TRUE,
  fun = sum,
  ...
)

poolReplicates(eset, indSamples = eset$SAMPLEID, removeInvarCols = TRUE)

avgReplicates(eset, indSamples = eset$SAMPLEID, removeInvarCols = TRUE)

medianReplicates(eset, indSamples = eset$SAMPLEID, removeInvarCols = TRUE)

Arguments

Details

poolReplicates and avgReplicates are two specific form of the more generic summarizeSamples function: they take sum and average of replicates given by the factor, respectively.

From version 1.1-7, the function summarizes not only exprs, but also all other objects in assayData

Value

A eSet object.

Author(s)

Jitao David Zhang <[email protected]>

See Also

The function calls summarizeColumns internally.

Also see summarizeProbesets.

Examples

data(ribios.ExpressionSet, package="ribiosExpression")
index <- factor(c(gl(12,2), 13, 14))

(ss.eset1 <- summarizeSamples(ribios.ExpressionSet, index))

(ss.eset2 <- summarizeSamples(ribios.ExpressionSet, index, fun=mean,
na.rm=TRUE))
## equivalently
(ss.eset2 <- poolReplicates(ribios.ExpressionSet, index))

(ss.eset3 <- avgReplicates(ribios.ExpressionSet, index))

Description

Truncate dgeTable into tables of positively and negatively differentially expressed genes according to the pre-defined criteria

Usage

truncateDgeTable(dgeTable)

Arguments

Value

A list of two elements: 'pos' and 'neg'. Each contains a dgeTable of positively/negatively regulated genes

Description

Gct/Cls file formats are required by the Gene Set Enrichment Analysis (GSEA) tool. Functions writeGct and writeCls exports file of two formats respectively, and writeGctCls calls the two function internally to write two files.

Usage

writeCls(eset, file = stdout(), sample.group.col = "group")

writeGctCls(
  eset,
  file.base,
  feat.name,
  feat.desc,
  sample.group.col,
  write.add.fData.file = TRUE,
  write.add.pData.file = TRUE
)

Arguments

Details

The feat.name option specifies what identifiers should be used for features (probesets). When the value is missing, featureNames is called to provide feature identifiers.

In contrast, the sample.group.col cannot be missing: since cls files encode groups (classes) of samples, and if sample.group.col was missing, it is usually impossible to get class information from sampleNames.

Internally writeCls calls dfFactor function to determine factor of samples. Therefore sample.group.col is to a certain degree generic: it can be a character string or integer index of the pData(eset) data matrix, or a factor vector of the same length as ncol(eset).

Value

Functions are used for their side effects.

Functions

• writeCls(): writeCls

Author(s)

Jitao David Zhang <[email protected]>

References

https://www.gsea-msigdb.org/gsea/doc/GSEAUserGuideTEXT.htm

See Also

See dfFactor for possible values of the sample.group.col option.

See readGctCls for importing functions.

Examples

data(sample.ExpressionSet, package="Biobase")
writeGct(sample.ExpressionSet[1:5, 1:4], file=stdout())
writeCls(sample.ExpressionSet, file=stdout(), sample.group.col="type")

tmpfile <- tempfile()
writeGctCls(sample.ExpressionSet, file.base=tmpfile, sample.group.col="type")
readLines(paste(tmpfile, ".cls",sep=""))
unlink(c(paste(tmpfile, ".cls", sep=""), paste(tmpfile, ".gct", sep="")))

Description

Export an ExpressionSet object as tab-delimited (or gct) files

Usage

writeEset(
  eset,
  exprs.file,
  fData.file,
  pData.file,
  exprs.file.format = c("gct", "tsv"),
  feat.name = NULL,
  feat.desc = NULL
)

Arguments

Value

NULL, only side effect is used

Note

One limitation of readEset and writeEset functions is that they only support the export/import of exactly one expression matrix from one ExpressionSet object. Although an ExpressionSet can hold more than one matrices other than the one known as exprs, they are currently not handled by writeEset or readEset. If such an ExprssionSet object is first written in plain files, and then read back as an ExpressionSet, matrices other than the one accessible by exprs will be discarded.

Similarly, other pieces of information saved in an ExpressionSet, e.g. experimental data, are lost as well after a cycle of exporting and subsequent importing. If keeping these information is important for you, other functions should be considered instead of readEset and writeEset, for instance to save an image in a binary file with the save function.

Yet another limitation is that factor information is lost. This hits especially the phenoData where factor information, such as sample groupping and orders of levels, may be important.

See Also

readEset

Examples

data(sample.ExpressionSet, package="Biobase")
exprs.file <- tempfile()
fData.file <- tempfile()
pData.file <- tempfile()
writeEset(sample.ExpressionSet, exprs.file, fData.file, pData.file,
exprs.file.format="gct")
writeEset(sample.ExpressionSet, exprs.file, fData.file, pData.file,
exprs.file.format="tsv")

Description

Export matrix or eSet that can be coerced as one into gct/cls files

Usage

writeGct(obj, file, feat.name, feat.desc)

## S4 method for signature 'matrix'
writeGct(obj, file, feat.name, feat.desc)

## S4 method for signature 'eSet'
writeGct(obj, file, feat.name, feat.desc)

Arguments

Value

Used for its side effect of writing files; returns invisibly.

Methods (by class)

• writeGct(matrix): Method for matrix as input, feta.name and feat.desc are passed to write_gct.

• writeGct(eSet): Use eSet as input. feat.name and feat.desc are variable (column) names in fData.

Description

Write sample groups and group levels into plain text files

Usage

writeSampleGroups(sampleGroups, sampleGroups.file, sampleGroupLevels.file)

Arguments

Details

The function is used to export sample group and group level information for differential gene expression analysis.

Value

Used for its side effect of writing files. Returns invisibly.

Examples

writeSampleGroups(gl(3,4), stdout(), stdout())

Description

writexlxs: write AnnotatedDataFrame to a xlsx file

Usage

writeVarMetadata(x, path = tempfile(fileext = ".xlsx"), overwrite = TRUE)

## Default S3 method:
writeVarMetadata(x, path = tempfile(fileext = ".xlsx"), overwrite = TRUE)

Arguments

Value

An invisible TRUE in case the file is successfully created, else FALSE.

Note

We also tried the writexl package but the comments are not well supported by writexl, therefore we stay with openxlsx

Examples

data("ribiosExpressionSet", package="ribiosExpression")
outfile <- tempfile()
writeVarMetadata(ribiosExpressionSet, path=outfile)
writeVarMetadata(phenoData(ribiosExpressionSet), path=outfile)