MarkerList. CellMix 1.6

Description

MarkerList is an S4 generic function that provides a convenient interface to create MarkerList-class objects from a variety of input formats, such as plain named lists, factors, matrices or ExpressionSet-class objects, text files, etc..

Usage

MarkerList(object, ...)

S4 (missing)
`MarkerList`(object, ..., file = NULL)

S4 (vector)
`MarkerList`(object, ..., names = NULL)

S4 (character)
`MarkerList`(object, ..., names = NULL)

S4 (list)
`MarkerList`(object, ..., unlist = FALSE, quiet = FALSE)

S4 (matrix)
`MarkerList`(object, ..., values = TRUE, add.names = TRUE)

Arguments

object: input object from which marker data are extracted.
...: extra arguments to allow extension. See each method's description for more details.
file: filename of a file that contains marker data. Conneciton objects are also supported.
names: factor or character vector that defines the types associated to each marker in object.
unlist: logical that indicates if the result should be a vector representation of the marker list. In this case auxiliary numeric values are dropped from the list.
quiet: logical that indicates if warnings should be silenced if any.
values: a logical that indicates if the row maximums should be embedded into the marker list.
add.names: logical that indicates if names should be added if necessary (TRUE). This is used in the case the input matrix has no rownames and the row maximum values are requested to be attached to the marker list (values=TRUE), which throws an error if add.names=FALSE.

Details

Except for its method MarkerList,matrix, this function does not try to infer markers from the input data, but only reorganise groups of markers that are already clearly defined in the input data.

Methods

MarkerListsignature(object = "MarkerList"): This method acts as a Constructor-Copy that returns the input MarkerList object unchanged if no other argument are passed, or creates a new MarkerList object based on object, using the arguments in ... to initialise the slots.
MarkerListsignature(object = "missing"): Creates a MarkerList object as per new('MarkerList', ...) or from a file (see section Loading from files).
MarkerListsignature(object = "ANY"): Default method that tries to retrieve marker data from the input object using the function getMarkers.
MarkerListsignature(object = "vector"): Creates a MarkerList object treating the input vector as a factor, except if the input is a numeric vector of scores. See MarkerList,factor-method.

If object is numeric, one also needs to supply a factor that defines the cell types. Markers ids are taken from the names object, or, if missing, from the names of types.
MarkerListsignature(object = "integer"): Creates a MarkerList object using the -- normally -- duplicated names of the input vector as types, and the values as marker indexes. See MarkerList,factor-method.
MarkerListsignature(object = "character"): Either loads a marker list from the internal registry (see cellMarkers), or use the names of object for defining the sets and the values (strings) as marker identifiers.

If no names are present, then it uses the character vector as a factor, whose levels are the sets, and creates an index marker list with MarkerList,factor-method.
MarkerListsignature(object = "factor"): Create a MarkerList object by splitting the input factor into a list of its different levels.

If object has names they are used as marker identifiers, otherwise an index marker list is created.
MarkerListsignature(object = "list"): Convert a standard list into a MarkerList object.

The list should contain no duplicated marker identifiers (either as strings or integer indexes).
MarkerListsignature(object = "matrix"): Creates a MarkerList object from a numeric matrix, that is assumed to have one column per marker set, e.g., a matrix cell type-specific signature.

This method uses a very simple heuristic, which associate each row in a matrix to the column with the maximum entry (see max.col).

For more complex and finer ways of extracting markers from expression data see extractMarkers.

The rownames are used as marker identifiers if present. If not otherwise specified, each marker is associated with its correspondong row maximum, which is also stored in the result object.
MarkerListsignature(object = "ExpressionSet"): Create a MarkerList from the expression matrix of an ExpressionSet-class object.

This is a shortcut for MarkerList(exprs(object), ...).

Loading from files

Loading marker lists directly from files can be performed by providing filename to argument file. Currently this functionality is only implemented for plain text files that contain one marker feature description per line: marker names (e.g., ENTREZID), marker set (e.g., cell type name) and optionally some numeric value (e.g. specificity score).

In this case all arguments in ... are passed to read.table, and should be set so that the loaded data.frame conforms with one of the following formats:

at least one column and row names: the row names are used as marker names, column 1 as marker set. Note that tables with automatic rownames generated by read.table (i.e. 1,2,3, etc..) are not considered as proper rownames.
two columns and no row names:column 1 is used for marker names, column 2 for the marker set names.
single column and no (or automatic) rownames:column is used for marker set names, the markers are taken to be integers.

Optionally, in all cases, the next numeric column after the one used for marker set names is used for associated numeric values.

Examples


## create a MarkerList from another MarkerList
m <- rMarkerList(3, 4, names=TRUE)
m

## <object of class: MarkerList>
## Types: Type1, Type2, Type3 (total: 3)
## Mode: character
## setName: NA 
## geneIds: Marker.3, Marker.4, ..., Marker.10 (total: 12)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

MarkerList(m, setName=mkScalar("Another list of markers"))

## <object of class: MarkerList>
## Types: Type1, Type2, Type3 (total: 3)
## Mode: character
## setName: Another list of markers 
## geneIds: Marker.3, Marker.4, ..., Marker.10 (total: 12)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

txtdesc <- function(x) textConnection(paste(x, collapse="\n"))

# two columns
ml <- MarkerList(file=txtdesc(c("m1 a", "m2 b", "m3 a")))
summary(ml)

##   Length Class  Mode     
## a 2      -none- character
## b 1      -none- character


# single column with row.names
ml2 <- MarkerList(file=txtdesc(c("m1 a", "m2 b", "m3 a")), row.names=1L)
identical(ml, ml2)

## [1] TRUE


# three columns with values
mlv <- MarkerList(file=txtdesc(c("m1 a 1.4", "m2 b 1.5", "m3 a 2.6")))
summary(mlv)

##   Length Class  Mode   
## a 2      -none- numeric
## b 1      -none- numeric

print(mlv)

## a :
##  m1  m3 
## 1.4 2.6 
## 
## b :
##  m2 
## 1.5


# skip an extra column
mlv <- MarkerList(file=txtdesc(c("m1 a 1.4", "m2 b 1.5", "m3 a 2.6")))
summary(mlv)

##   Length Class  Mode   
## a 2      -none- numeric
## b 1      -none- numeric

print(mlv)

## a :
##  m1  m3 
## 1.4 2.6 
## 
## b :
##  m2 
## 1.5


# single column: index MarkerList
ml <- MarkerList(file=txtdesc(c("a", "b", "a")))
summary(ml)

##   Length Class  Mode   
## a 2      -none- numeric
## b 1      -none- numeric

## create a MarkerList from an integer vector
# names are required
try( MarkerList( 1:15 ) )
# repeated names define marker sets
MarkerList( setNames(1:12, rep(letters[1:3], 4)) )

## <object of class: MarkerList>
## Types: a, b, c (total: 3)
## Mode: integer
## setName: NA 
## geneIds: 1, 4, ..., 12 (total: 12)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

## create a MarkerList from a character vector
# no names: repeated values define the sets
v <- sample(letters[1:3], 15, replace=TRUE)
MarkerList(v)

## <object of class: MarkerList>
## Types: a, b, c (total: 3)
## Mode: integer
## setName: NA 
## geneIds: 5, 6, ..., 15 (total: 15)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

# with names: repeated names define the sets
m <- str_c('M', 1:15)
MarkerList( setNames(m, v) )

## <object of class: MarkerList>
## Types: a, b, c (total: 3)
## Mode: character
## setName: NA 
## geneIds: M5, M6, ..., M15 (total: 15)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

## create a MarkerList from a factor
f <- factor(sample(letters[1:3], 15, replace=TRUE))
MarkerList(f)

## <object of class: MarkerList>
## Types: a, b, c (total: 3)
## Mode: integer
## setName: NA 
## geneIds: 1, 5, ..., 14 (total: 15)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

MarkerList( addNames(f, 'M') )

## <object of class: MarkerList>
## Types: a, b, c (total: 3)
## Mode: character
## setName: NA 
## geneIds: M1, M5, ..., M14 (total: 15)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

## create an index MarkerList from a standard list
m <- list(1:3, 5:10, c(4L,12L))
MarkerList(m)

## <object of class: MarkerList>
## Types: Type_1, Type_2, Type_3 (total: 3)
## Mode: integer
## setName: NA 
## geneIds: 1, 2, ..., 12 (total: 11)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'


# with mixed integer/numeric, a warning is thrown
m <- list(1:3, 5:10, c(4,12))
MarkerList(m)

## Warning: MarkerList - Converting mixed integer/numeric elements into
## integers.

## <object of class: MarkerList>
## Types: Type_1, Type_2, Type_3 (total: 3)
## Mode: integer
## setName: NA 
## geneIds: 1, 2, ..., 12 (total: 11)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

## create a MarkerList from a matrix of signatures
s <- rmatrix(10,4)
m <- MarkerList( s )

## Warning: MarkerList - Rownames were generated (as integers) to be able to
## attach row maximum values.

# the object has values, that can be dropped is necessary
m

## <object of class: MarkerList>
## Types: 1, 2, 3, 4 (total: 4)
## Mode: numeric
## setName: NA 
## geneIds: 2, 3, ..., 6 (total: 10)
## geneIdType: Null
## collectionType: Null 
## geneValues: 0.85329433879815, 0.829545540269464, ..., 0.908054968109354 
## details: use 'details(object)'

dropvalues(m)

## <object of class: MarkerList>
## Types: 1, 2, 3, 4 (total: 4)
## Mode: character
## setName: NA 
## geneIds: 2, 3, ..., 6 (total: 10)
## geneIdType: Null
## collectionType: Null 
## geneValues: NA 
## details: use 'details(object)'

# or directly
identical(dropvalues(m), MarkerList(s, values=FALSE))

## [1] FALSE