AnnotatedDataFrame          package:Biobase          R Documentation

Class Containing Measured Variables and Their Meta-Data Description.

Description:

     An 'AnnotatedDataFrame' consists of two parts. There is a
     collection of samples and the values of variables measured on
     those samples. There is also a description of each variable
     measured. The components of an 'AnnotatedDataFrame' can be
     accessed with 'pData' and 'varMetadata'.

Extends:

     Versioned

Creating Objects:

     'new("AnnotatedDataFrame")'

     'new("AnnotatedDataFrame", data=data.frame(),
     varMetadata=data.frame(), dimLabels=c("rowNames", "columnNames"))'

     'AnnotatedDataFrame' instances are created using 'new'.  The
     initialize method takes up to three arguments, 'data',
     'varMetadata', and 'dimLabels'.  'data' is a 'data.frame' of the
     samples (rows) and measured variables (columns).  'varMetadata' is
     a 'data.frame' with the number of rows equal to the number of
     columns of the 'data' argument. 'varMetadata' describes aspects of
     each measured variable. 'dimLabels' provides aesthetic control for
     labeling rows and columns in the 'show' method. 'varMetadata' and
     'dimLabels' can be missing.

     'as(data.frame, "AnnotatedDataFrame")' coerces a 'data.frame' to
     an 'AnnotatedDataFrame'.

     'annotatedDataFrameFrom' may be a convenient way to create an
     'AnnotatedDataFrame' from 'AssayData-class'.

Slots:

     Class-specific slots:

     'data': A 'data.frame' containing samples (rows) and measured
          variables (columns).

     'dimLabels': A 'character' vector of length 2 that provides labels
          for the rows and columns in the 'show' method.

     'varMetadata': A 'data.frame' with number of rows equal number of
          columns in 'data', and at least one column, named
          'labelDescription', containing a textual description of each
          variable.

     '.__classVersion__': A 'Versions' object describing the R and
          Biobase version numbers used to created the instance.
          Intended for developer use.

Methods:

     Class-specific methods.


     'as(annotatedDataFrame, "data.frame")' Coerce objects of
          'AnnotatedDataFrame' to 'data.frame'.

     'combine(<AnnotatedDataFrame>,         <AnnotatedDataFrame>': Bind
          data from one 'AnnotatedDataFrame' to a second
          'AnnotatedDataFrame', returning the result as an
          'AnnotatedDataFrame'. Row (sample) names in each argument
          must be unique. Variable names present in both arguments
          occupy a single column in the resulting 'AnnotatedDataFrame'.
          Variable names unique to either argument create columns with
          values assigned for those samples where the variable is
          present. 'varMetadata' in the returned 'AnnotatedDataFrame'
          is updated to reflect the combination.

     'pData(<AnnotatedDataFrame>)', 'pData(<AnnotatedDataFrame>)<-<data.frame>': 
          Set and retrieve the data (samples and variables) in the
          'AnnotatedDataFrame'

     'varMetadata(<AnnotatedDataFrame>)', 'varMetadata(<AnnotatedDataFrame>)<-<data.frame>': 
          Set and retrieve the meta-data (variables and their
          descriptions) in the 'AnnotatedDataFrame'

     'featureNames(<AnnotatedDataFrame>)', 'featureNames(<AnnotatedDataFrame>)<-<ANY>': 
          Set and retrieve the feature names in 'AnnotatedDataFrame'; a
          synonym for 'sampleNames'.

     'sampleNames(<AnnotatedDataFrame>)', 'sampleNames(<AnnotatedDataFrame>)<-<ANY>': 
          Set and retrieve the sample names in 'AnnotatedDataFrame'

     'varLabels(<AnnotatedDataFrame>)', 'varLabels(<AnnotatedDataFrame>)<-<data.frame>': 
          Set and retrieve the variable labels in the
          'AnnotatedDataFrame'

      'dimLabels(<AnnotatedDataFrame>)', 'dimLabels(<AnnotatedDataFrame>) <- <character>' 
          Retrieve labels used for display of 'AnnotatedDataFrame',
          e.g., 'rowNames', 'columnNames'.

     Standard generic methods:

     'initialize(<AnnotatedDataFrame>)': Object instantiation, used by
          'new'; not to be called directly by the user.

     'as(<data.frame>, "AnnotatedDataFrame")': Convert a 'data.frame'
          to an AnnotatedDataFrame.

     'as(<phenoData>,<AnnotatedDataFrame>)': Convert old-style
          'phenoData-class' objects to 'AnnotatedDataFrame', issuing
          warnings as appropriate.

     'validObject(<AnnotatedDataFrame>)': Validity-checking method,
          ensuring coordination between 'data' and 'varMetadata'
          elements

     'updateObject(object, ..., verbose=FALSE)' Update instance to
          current version, if necessary. See 'updateObject'

     'isCurrent(object)' Determine whether version of object is
          current. See 'isCurrent'

     'isVersioned(object)' Determine whether object contains a
          'version' string describing its structure . See 'isVersioned'

     'show(<AnnotatedDataFrame>)' Abbreviated display of object

     '[<sample>,<variable>': Subset operation, taking two arguments and
          indexing the sample and variable. Returns an
          'AnnotatedDataFrame', i.e., including relevant metadata.
          Unlike a 'data.frame', setting 'drop=TRUE' generates an
          error. 

     '[[<variable>', '$<variable>': Selector returning a variable
          (column of 'pData').

     '[[<variable>, ...]]<-<new_value>', '$<variable> <- <new_value>': 
          Replace or add a variable to 'pData'. ... can include named
          arguments (especially 'labelDescription') to be added to
          'varMetadata'.

     'dim(<AnnotatedDataFrame>)', 'ncol(<AnnotatedDataFrame>)': Number
          of samples and variables ('dim') and variables ('ncol') in
          the argument.

Author(s):

     V.J. Carey, after initial design by R. Gentleman

See Also:

     'eSet', 'ExpressionSet', 'read.AnnotatedDataFrame'

Examples:

     df <- data.frame(x=1:6,
                      y=rep(c("Low", "High"),3),
                      z=I(LETTERS[1:6]),
                      row.names=paste("Sample", 1:6, sep="_"))
     metaData <-
       data.frame(labelDescription=c(
                    "Numbers",
                    "Factor levels",
                    "Characters"))
                            
     new("AnnotatedDataFrame")
     new("AnnotatedDataFrame", data=df)
     new("AnnotatedDataFrame",
         data=df, varMetadata=metaData)

     as(df, "AnnotatedDataFrame")

     obj <- new("AnnotatedDataFrame")
     pData(obj) <- df
     varMetadata(obj) <- metaData
     validObject(obj)

