gate.IPC              package:rflowcyt              R Documentation

_I_n_t_e_r_a_c_t_i_v_e _g_a_t_i_n_g _o_f _a_n _I_m_a_g_e _P_a_r_a_l_l_e_l _C_o_o_r_d_i_n_a_t_e_s _P_l_o_t

_D_e_s_c_r_i_p_t_i_o_n:

     This function will plot an image parallel coordinates plot and
     allows to user to click on the plot to indicate the cutoff value
     of the variable that is to be gated.  On this single variable, the
     plot will be divided and two subsequent subplots (ie, two image
     parallel coordinates plots) will be shown.

_U_s_a_g_e:

     gate.IPC(myFCSobj, var.gate,
           var.pos=1:(dim(myFCSobj@data)[2]),
           num.bins=10,
           joint=FALSE,
           range.var=range(myFCSobj@data[,var.pos]),
           break10 =seq(range.var[1]-1, range.var[2],
                            by=range.var[2]/num.bins),
           title="",
           use.shortnames=FALSE,
           color.image=gray((25:5/25)[-c(1,2,3, 4, 5, 6)]), 
           xwidth.scale=5,
           ntrans=1,
           hist.plotted=FALSE,
           image.plotted=TRUE,
           para.plotted=FALSE,
           lines.plotted=TRUE,
           legend.plotted=TRUE,
           lwd.vec=1:7,
           lty.vec=rep(1,7),
           col.vec=7:1,
           range.image=c(0, dim(myFCSobj@data)[1]),
           shrink.legend=TRUE,
           horizontal.legend = TRUE,
           offset.legend=0.03,
           nlevel.legend=length(color.image),
           xlab.image="",
           ylab.image="Bins",
           MY.DEBUG=FALSE,...)

_A_r_g_u_m_e_n_t_s:

myFCSobj: FCS object to be gated/subsetted on an image parallel
          coordinates plot

var.gate: numerical column position of the variable to be gated in the
          data component of myFSobj

 var.pos: a vector of the column positions of the variables of interest
          in the data of the FCS object to be shown in the image
          parallel coordinates plot;default is all the columns will be
          shown in the plots 

num.bins: a vector consisting of the row positions of the cells to be
          analyze; default is 10

   joint: Boolean; If TRUE, then the joint image parallel coordinate
          plots will be shown for the pre-gated and post-gated data; if
          FALSE, then the mariginal lines for the image parallel
          coordinate plots will be displayed; default is FALSE

range.var: a 2-dimensional vector denoting the minimum value and the
          maximum value of the variables to be plotted; default is
          c(0,1024), where 0 is the minimum value and 1024 is the max
          value

 break10: vector denoting the breaks for the binning on the vertical
          axis; default is equal interval binning denoted by num.bins
          unless otherwise specified; the breaks must include the range
          of the variable; each bin is denoted by an open lower value
          and a closed upper value, ie, (a,b] where a and b are
          breakpoints and a<b. 

   title: character string denoting the title of the image plot;
          default value is an empty string 

use.shortnames: Boolean; if TRUE, then the shortnames of the variables
          will be used in labeling in the plots; otherwise if FALSE,
          the longnames of the variables will be used; default is FALSE

color.image: the color scheme for the image plot; default is
          gray((25:5/25)[-c(1,2,3, 4, 5, 6)]) 

xwidth.scale: numeric value denoting the horizontal width of the
          variable and the transitions blocks; default value is 5 units
          of width

  ntrans: numeric value denoting the number of transition columns
          between each pair of variables; default is 1 transition
          column between each pair of variables

hist.plotted: Boolean; if TRUE then the histogram plots of the
          variables and the transitions are made; otherwise if FALSE,
          there is no histogram plots; default value is FALSE

image.plotted: Boolean; if TRUE, then the image parallel coordinates
          plot is displayed; otherwise if FALSE, the plot is
          surpressed; default is TRUE

para.plotted: Boolean; if TRUE, then the parallel coordinates plot is
          displayed; otherwise if FALSE, the plot is surpressed;
          default is TRUE

lines.plotted: Boolean; if TRUE, then the image plot with the
          superimposed lines displayed; otherwise if FALSE, the plot is
          surpressed

legend.plotted: Boolean; if TRUE, then the legend for the superimposed
          lines denoting particular counts will be diplayed; otherwise
          if FALSE, the legend display is surpressed

 lwd.vec: vector denoting the line width sizes to be used in the lines
          overlaying the image parallel coordinates plot; default value
          is an integer vector from 1 to 7

 lty.vec: vector denoting the line type (solid or dotted, etc) for the
          corresponding line width in lwd.vec; the default is to have a
          solid line for each line width

 col.vec: vector denoting the color for each line with the
          corresponding line width in lwd.vec and line type in lty.vec;
          the default is to have colors ranging from yellow to black
          (in that order).

range.image: 2-dimensional numerical vector denoting the range of the
          number of counts in the image block to be plotted.  The
          default value is to have a vector with a mininum value of
          zero and to have a maximum dependent on the number of
          cells/rows and bins

shrink.legend: boolean; if TRUE then the legend will be ; default value
          is TRUE

horizontal.legend: default value is TRUE

offset.legend: default value is 0.03

nlevel.legend: default value is the length of the color.image vector

xlab.image: a character string denoting the label of the horizontal
          x-axis on the image plot; default value is an empty string

ylab.image: a character string denoting the label of the vertical
          y-axis on the image plot; default value is "Bins"

MY.DEBUG: boolean value; if TRUE, debugging statements are printed,
          otherwise if FALSE, the statements are surpressed; default is
          FALSE

     ...: graphical parameters for 'plot' may also be passed as
          arguments to this function

_D_e_t_a_i_l_s:

     The gating will be made on the image parallel coordinates plot
     without the lines drawn; this plot is the last plot to be
     displayed.  The user should make a right click on the variable
     value displayed on the vertical axis.  This variable value will
     denote the cutoff.  The subsequent plots of the subsets will be
     made on the data such that the first subset will include row
     observations whose gated variable values are less than or equal to
     the cutoff of the gated variable across all other variables of
     interest and that the second subset/subplot will include row
     observations of whose gated variable's values are strictly greater
     than the cutoff.

_V_a_l_u_e:

     The first series of histograms, and parallel coordinates plots,
     and image parallel coordinates plots with superimposed lines and
     legends are displayed optionally by the user.

     The second single image parallel coordinates plot is the one, in
     which the gating or threshold in which to subset is obtained by
     right clicking on the plot.

     _i_m_a_g_e._b_l_o_c_k a matrix denoting the number of observations in each
          cell of the total image plot

     _l_i_n_e._i_n_f_o total plot's list of matrices in which each matrix
          corresponds to the the line information between a pair of
          variables.  Each matrix has three columns.  The first two
          columns are the values of unique bin patterns between the
          pair of column variables, and the third column is the number
          of observations with that particular pattern.

     _b_r_e_a_k_s total plot's vector of breaks for binning on the vertical
          axis for the values of the variablesDescription of `comp1'

     _i_m_a_g_e._b_l_o_c_k a matrix denoting the number of observations in each
          cell of the first subsetted image plot

     _l_i_n_e._i_n_f_o first subset's list of matrices in which each matrix
          corresponds to the the line information between a pair of
          variables.  Each matrix has three columns.  The first two
          columns are the values of unique bin patterns between the
          pair of column variables, and the third column is the number
          of observations with that particular pattern.

     _b_r_e_a_k_s first subset's vector of breaks for binning on the vertical
          axis for the values of the variablesDescription of `comp2'

     _i_m_a_g_e._b_l_o_c_k a matrix denoting the number of observations in each
          cell of the second subsetted image plot

     _l_i_n_e._i_n_f_o second subset's list of matrices in which each matrix
          corresponds to the the line information between a pair of
          variables.  Each matrix has three columns.  The first two
          columns are the values of unique bin patterns between the
          pair of column variables, and the third column is the number
          of observations with that particular pattern.

     _b_r_e_a_k_s second subset's vector of breaks for binning on the
          vertical axis for the values of the variablesDescription of
          `comp1'

obspos.sub1: first subset's vector of numerical row observation
          positions of the data component of myFCSobj

obspos.sub2: second subset's vector of numerical row observation
          positions of the data component of myFCSobj

FCSgateobj: An FCS gate object that resulted from the gating

_A_u_t_h_o_r(_s):

     A.J. Rossini & J.Y. Wan

_S_e_e _A_l_s_o:

     'ImageParCoord', 'JointImageParCoord', 'hist', 'plot'

_E_x_a_m_p_l_e_s:

     if (require(rfcdmin)){
     data.there<-is.element(c("st.1829", "unst.1829", "st.DRT", "unst.DRT"),objects())
     if ( ( sum(data.there) != length(data.there) )){
     ## obtaining the FCS objects from VRC data
     data(VRCmin)
     }

     ## make a smaller data for example
     ## first 1000 row observations
     example.fcs<-unst.DRT[1:1000,]
     if (!checkvars(example.fcs)){
     example.fcs<-fixvars(example.fcs)
     }

     if (interactive()==TRUE){

     ## Joint parallel coordinates image
     par(mfrow=c(4,3))
     ## gating the first column variable
     ## showing the image parallel coordinates
     ##    for column variables 1 through 5
     gate.IPC(example.fcs, 1, var.pos=1:5, num.bins=10,joint=TRUE,
                   title="Joint 10 bins 5 trans", ntrans=5)

     ## marginal parallel coordinate image
     ## gating the second column variable
     par(mfrow=c(4,3))
     gate.IPC(example.fcs, 2, var.pos=1:5, num.bins=10,joint=FALSE,
                   title="Marginal 10 bins 5 trans", ntrans=5)
     }
     }

