gate.IPC {rflowcyt} | R Documentation

## Interactive gating of an Image Parallel Coordinates Plot

### Description

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.

### Usage

    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,...)

### Arguments

`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

### Details

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.

### Value

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.

`info.total` | image.block a matrix denoting the number of observations in each cell of the total image plot line.info 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. breaks total plot's vector of breaks for binning on the vertical axis for the values of the variables Description of `comp1'
`info.sub1` | image.block a matrix denoting the number of observations in each cell of the first subsetted image plot line.info 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. breaks first subset's vector of breaks for binning on the vertical axis for the values of the variables Description of `comp2'
`info.sub2` | image.block a matrix denoting the number of observations in each cell of the second subsetted image plot line.info 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. breaks second subset's vector of breaks for binning on the vertical axis for the values of the variables Description 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

### Author(s)

A.J. Rossini & J.Y. Wan

### See Also

`ImageParCoord`, `JointImageParCoord`, `hist`, `plot`

### Examples

    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)
    }
    }

[Package rflowcyt version 1.2.0 Index]