xyplot                package:flowViz                R Documentation

_M_e_t_h_o_d_s _i_m_p_l_e_m_e_n_t_i_n_g _L_a_t_t_i_c_e _x_y_p_l_o_t_s _f_o_r _f_l_o_w _d_a_t_a.

_D_e_s_c_r_i_p_t_i_o_n:

     These functions create Trellis scatter plots (a.k.a. dot plots in
     the Flow Cytometry community) from flow cytometry data.

_U_s_a_g_e:

     ## Method for 'flowFrame' objects without a formula.
     ## This creates plots of all flow parameters agains
     ## time. 
     ## S4 method for signature 'flowFrame, missing':
     xyplot(
         x,
         data,
         time,
         xlab,
         ylab="",
         layout,
         prepanel=prepanel.xyplot.flowframe.time,
         panel=panel.xyplot.flowframe.time,
         type="discrete",
         ...)

     ## prepanel function for time line plots of flowFrames
     prepanel.xyplot.flowframe.time(
         x,
         y,
         frame,
         time,
         ...)

     ## panel function for time line plots of flowFrames
     panel.xyplot.flowframe.time(
         x, 
         y,
         frame,
         time,
         type="discrete",
         nrpoints=0,
         binSize=100,
         ...)


     ## method for formulae with 'flowFrame' objects
     ## S4 method for signature 'formula, flowFrame':
     xyplot(
         x,
         data,
         smooth=TRUE,
         prepanel=prepanel.xyplot.flowframe,
         panel=panel.xyplot.flowframe,
         ...)

     ## prepanel function for generic xyplots of flowFrames
     prepanel.xyplot.flowframe(
         frame,
         channel.x.name,
         channel.y.name,
         ...)
        

     ## panel function for generic xyplots of flowFrames
     panel.xyplot.flowframe(
         x,
         y,
         frame,
         filter=NULL,
         smooth=TRUE,
         margin=TRUE,
         outline=FALSE,
         channel.x.name,
         channel.y.name,
         pch=gpar$flow.symbol$pch,
         alpha=gpar$flow.symbol$alpha,
         cex=gpar$flow.symbol$cex,
         col=gpar$flow.symbol$col,
         gp,
         ...)


     ## method for 'flowSet' objects
     ## S4 method for signature 'formula, flowSet':
     xyplot(
         x,
         data,
         xlab,
         ylab,
         as.table=TRUE,
         prepanel=prepanel.xyplot.flowset,
         panel=panel.xyplot.flowset,
         pch = ".",
         smooth = TRUE,
         filter = NULL,
         par.settings=NULL,
         ...)

     ## prepanel function for generic xyplots of flowSets
     prepanel.xyplot.flowset(
         x,
         frames,
         channel.x.name,
         channel.y.name,
         ...)

     ## panel function for generic xyplots of flowSets
     panel.xyplot.flowset(
         x,
         frames,
         filter=NULL,
         channel.x,
         channel.y,
         ...)

     ## method for various workflow objects
     ## S4 method for signature 'formula, view':
     xyplot(
         x,
         data,
         ...)

     ## S4 method for signature 'view, missing':
     xyplot(
         x,
         data,
         ...) 

     ## S4 method for signature 'formula, gateView':
     xyplot(
         x,
         data,
         filter=NULL,
         par.settings,
         ...)
           

_A_r_g_u_m_e_n_t_s:

       x: A formula describing the structure of the plot and the
          variables to be used in the display.  In the 'prepanel' and
          'panel' functions, also the names of 'flowFrames' or any of
          the annotation data columns in the 'phenoData' slot. 

data, y, frame: a 'flowSet' or 'flowFrame' object that serves as the
          source of data. For the workflow methods, this can also be
          various 'view' or 'actionItem' objects.

    time: A character string giving the name of the data column
          recording time. If not provided, we try to guess from the
          available parameters. 

xlab, ylab: Labels for data axes, with suitable defaults taken from the
          formula. 

as.table, layout: These arguments are passed unchanged to the
          corresponding methods in lattice, and are listed here only
          because they provide different defaults.  See documentation
          for the original methods for details. 

    type: type of rendering; see 'panel.xyplot' for details. For the
          basic 'flowFrame' method without a detailed formula, the
          addtional type 'discrete' is available, which plots a
          smoothed average of the flow cytometry values against time. 

nrpoints: The number of points plotted on the smoothed plot in sparse
          regions. This is only listed here because we use a different
          default. See 'panel.smoothScatter' for details. 

 binSize: The size of a bin (i.e., the number of events within a bin)
          used for the smoothed average timeline plots. 

channel.x.name, channel.y.name: Character strings giving corresponding
          names used to match filter parameters if applicable. 

  smooth: Logical. If 'TRUE', 'panel.smoothScatter' is used to display
          a partially smoothed version of the data. Otherwise, events
          are plotted individually, as in a standard scatter plot. 

  filter: A 'filter', 'filterResult' or 'filterResultList' object or a
          list of such objects of the same length as the 'flowSet'. The
          appropriate spherical 2D representation of this filter will
          be superimposed on the plot if 'smooth=TRUE', or the resukt
          of the filtering operation will be indicated by grouping if
          'smooth=FALSE' . The software will figure out whether the
          'filter' needs to be evaluated in order to be plotted (in
          which case providing a 'filterResult' can speed things up
          considerably). 

  margin: Logical indicating whether to truncate the density estimation
          on the margins of the measurement range and plot margin
          events as lines if 'smooth=TRUE'. To avoid visual artifacts
          it is highly recommended to set this option to 'TRUE'. 

 outline: Logical, specifying whether to add the boundaries of a gate
          to the plot when 'smooth=FALSE' in addition to the grouping.
          Defaults to 'FALSE'. 

pch, cex, col, alpha: Graphical parameters used when 'smooth=FALSE'.
          These mostly exist for conveniance and much more control is
          available throught the 'lattice'-like 'par.setting' and
          'flowViz.par.set' customization. See 'flowViz.par.set' for
          details. 

par.settings: A list of lists of graphical parameters.  See
          'flowViz.par.set' for details.

      gp: A list of graphical parameters that are passed down to the
          low level panel functions. This is for internal use only. The
          public user interface to set graphical parameters is either
          'par.settings' for customization of a single call or
          'flowViz.par.set' for customization of session-wide defaults. 

prepanel: The prepanel function. See 'xyplot'. 

   panel: The panel function. See 'xyplot'. 

channel.x, channel.y: Expressions defining the x and y variables in
          terms of columns in the data.  Can involve functions or
          multiple columns from the data, however this usage is
          discouraged. 

  frames: An environment containing frame-specific data. 

     ...: More arguments, usually passed on to the underlying lattice
          methods. 

_D_e_t_a_i_l_s:

     The implementation of 'xyplot' in 'flowViz' is very close to the
     original 'lattice' version. Concepts like conditioning and the use
     of panels apply directly to the flow cytometry data. The single
     fundamental difference is that conditioning variables are not
     evaluated in the context of the raw data, but rather in the
     'phenoData' slot environment (only for the 'flowSet' methods.
     Thus, we can directly condition on pheotypic variables like sample
     groups, patients or treatments.

     In the formula interface, the primary and secondary variables
     (separated by the tilde) have to be valid parameter names. Please
     note that frequently used variants like 'FSC-H' and 'SSC-H' are
     not syntactically correct R symbols, and need to be wrapped in '`
     `'. E.g., '`FSC-H`'. For 'flowSets', the use of a conditioning
     variable is optional. We implicitely condition on 'flowFrames' and
     the default is to arrange panels by sample names.

_M_e_t_h_o_d_s:



     _x_y_p_l_o_t 'signature(x = "flowFrame", data = "missing")': Creates
          diagnostic time series plots of flow parameter values against
          time. These plots are useful to detect quality issues in the
          raw data. If not provided explicitely via the 'tine'
          argument, the time parameter will be automatically detected.
          The additional arguments 'xlab', 'ylab', 'nrpoints', and
          'layout' are only listed because 'flowViz' provides different
          defaults. Internally, they are directly passed on to the
          underlying 'lattice' functions. Argument 'type' can be a
          combination of any of the types allowed in 'lattice xyplots',
          or 'discrete', in which case a smoothed average of the
          parameter against time is plotted. 'binSize' controls the
          binning that is used for the smoothing procedure.

     _x_y_p_l_o_t 'signature(x = "formula", data = "flowFrame")': Creates
          scatter plots (a.k.a. dot plots) of a pair of FCM channels.
          Depending on the setting of the 'smooth' argument, the data
          will be rendered as a partially smoothed density estimate
          ('smooth=TRUE', the default) or as a regular scatter plot
          with separate points for individual events. The formula
          interface allows for fairly general plotting, however there
          are certain limitations on the use of expressions as part of
          the formulae. Unless you are sure about what you are doing,
          you should transform the raw data in a separate step using
          one of the tools in the 'flowCore' package rather than inline
          using the formula interface. The method allows to superimpose
          gating results though the 'filter' argument. If
          'smooth=TRUE', we try to add spherical 2D representations of
          the gates if applicable. For 'smooth=FALSE', gates are
          indicated by a grouping mechanism using different point
          shapes or colors (unless 'outline' is also 'TRUE', in which
          case the gate outlines are superimposed in addition to the
          grouping). Argument 'margins' controls how events on the
          margins of the measurement range are treated. The default
          ('TRUE') is to discard them from any density estimation and
          later add them as separate glyphs. See 'flowViz.par.set' for
          details on controlling graphical parameters in these plots. 

     _x_y_p_l_o_t 'signature(x = "formula", data = "flowSet")': Scatter plots
          from a 'flowSet' object. We allow for conditioning on
          variables in the 'phenoData' slot of the 'flowSet'. All
          additional arguments that apply to the 'flowFrame' method are
          also valid for 'flowSets'. 

     _x_y_p_l_o_t 'signature(x = "formula", data = "view")': Scatter plots
          from a 'view' object. Depending on the particulars of the
          view, the method tries to come up with reasonable defaults.
          Full customization is also available though all the before
          mentioned arguments. 

     _x_y_p_l_o_t 'signature(x = "view", data = "missing")': Scatter plots
          from a 'view' object. This is the fallback method in the case
          of absolutely no customization. It serves as the default plot
          method for all 'views'.  

     _x_y_p_l_o_t 'signature(x = "formula", data = "gateView")': Scatter
          plots from a 'gateView' object. This allows for customization
          of the 'gateView' plots but still provides reasonable
          defaults, e.g., for added gates. 


_A_u_t_h_o_r(_s):

     F. Hahne, D. Sarkar

_S_e_e _A_l_s_o:

     Not all standard lattice arguments will have the intended effect,
     but many should.  For a fuller description of possible arguments
     and their effects, consult documentation on lattice.

_E_x_a_m_p_l_e_s:

     data(GvHD)
     GvHD <- GvHD[pData(GvHD)$Patient %in% 5:6]

     ## a bivariate scatterplot
     ## by default ('smooth=TRUE') panel.smoothScatter is used
     xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
     main="A single flowFrame")

     ## A non-smooth version of the same data
     xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
     main="A single flowFrame", smooth=FALSE)

     ## Visual artifacts created by the pileup of margin events
     xyplot(`FSC-H` ~ `SSC-H`, GvHD[["s5a05"]], nbin = 100,
     main="A single flowFrame", margin=FALSE)

     ## simple bivariate scatter plot (a.k.a. dot plot)
     ## for the whole flowSet, conditioning on Patient and
     ## Visit
     xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit, data = GvHD)

     ## several examples with time on the X axis
     ## first for a flowFrame
     xyplot(GvHD[[1]])

     ## and for flowSets
     xyplot(`FSC-H` ~ Time | Visit, GvHD, 
            smooth = FALSE, type = "l", 
            subset = (Patient == 5))

     xyplot(`FSC-H` ~ Time | Patient+Visit, GvHD, 
            smooth = FALSE, type = "a",
            strip = FALSE, strip.left = TRUE,
            aspect = "xy")

     ## combine plots for two channels
     ssc.time <- 

         xyplot(`SSC-H` ~ Time | factor(Patient):factor(Visit), GvHD, 
                smooth = FALSE, type = "a",
                strip = FALSE,
                strip.left = strip.custom(horizontal = TRUE),
                par.strip.text = list(lines = 3),
                between = list(y = rep(c(0, 0.5), c(6, 1))),
                scales = list(x = list(axs = "i"), y = list(draw = FALSE)),
                layout = c(1, 14))

     fsc.time <- 
         xyplot(`FSC-H` ~ Time | factor(Patient):factor(Visit), GvHD, 
                smooth = FALSE, type = "a",
                strip = FALSE,
                strip.left = strip.custom(horizontal = TRUE),
                par.strip.text = list(lines = 3),
                between = list(y = rep(c(0, 0.5), c(6, 1))),
                scales = list(x = list(axs = "i"), y = list(draw = FALSE)),
                layout = c(1, 14))

     plot(fsc.time, split = c(1, 1, 2, 1))
     plot(ssc.time, split = c(2, 1, 2, 1), newpage = FALSE)

     ## saving plots as variables allows more manipulation
     plot(update(fsc.time[8:14], layout = c(1, 7)),
          split = c(1, 1, 1, 2))

     plot(update(ssc.time[8:14], layout = c(1, 7)),
          split = c(1, 2, 1, 2), newpage = FALSE)

     ## displaying filters
     n2gate <- norm2Filter("SSC-H", "FSC-H")

     xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit, data = GvHD,
            filter=n2gate, subset=Patient==5)

     xyplot(`SSC-H` ~ `FSC-H` | Patient:Visit,
            data=transform("SSC-H"=asinh,"FSC-H"=asinh) %on% GvHD,
            smooth=FALSE, filter=n2gate, subset=Patient==5)

     n2gate.results <- filter(GvHD, n2gate)

     xyplot(`SSC-H` ~ `FSC-H` | Visit, data=GvHD,
            subset=Patient == "6",
            filter=n2gate.results, smooth=FALSE)

