New parameters can be added to a file of interest using the R Add Parameters input method.

 

To be compatible with the R Add Parameters method, the Execute function defined in the R script should result in an S4 object containing the following slots:

 

1. numberOfNewParams : integer of the number of new parameters;

2. newParamData : numeric matrix with the data for the new parameters. It has to be oriented with events in columns and parameters in rows, irrespective of the orientation set for the mat matrix;

3. newParamNames : character vector containing the names of new parameters.

 

A general example of an R script compatible with the R Add Parameters input method follows:

 

Execute <- function(mat)

{

 setClass("TransformationResult",

           representation(

               newParamData="matrix",

               numberOfNewParams="integer",

               newParamNames="character"

               ),

           prototype(

               newParamData=c(),

               numberOfNewParams=as.integer(0),

               newParamNames=""

               )

 )

 

 result <- new("TransformationResult")

 

 result@numberOfNewParams <- as.integer(A)

 result@newParamData <- B

 result@newParamNames <- C

 

 return(result)

}

 

Where A, B and C values are defined by the user. As stated above:

•A can be any integer number. Note that the as.integer() function is required since numbers are otherwise stored as object of class numeric.

•B can be the result of any user-defined transformation. B must be an object of class matrix with events in columns and parameters in rows. The number of events (i.e. the number of columns) must match the number of events in the mat matrix and the number of parameters (i.e. the number of rows) must match the value defined in A.

•C is a vector of class character containing the names of the new parameters. Multiple names can be specified using the c() function (e.g. c("name1","name2","name3") ). Please also note that the name of the parameters included in the mat matrix are accessible in R by using the rownames() or the colnames() functions (when parameter are in rows and in columns respectively). Thus parameter names can be derived and used as part of generating new parameter names.

 

 

An R script structured as above can be integrated into FCS Express using the R Add Parameters tools via the following steps:

 

1. Open the Transformation window by selecting the Tools tab→Transformations →Transformations command.

2. Click on the drop down arrow adjacent to the blue plus button.

3. Select R Add Parameters. The Transformation window will appear as in the picture below (Figure 29.45).

4. Click on the ellipsis at the right of the Template File field to browse for a template *.FCS file (Figure below - Step 1).

 

 

The Transformation window will be populated with the parameters contained in the selected *.FCS file (Figure 29.46).

 

5. Select the parameters that will be included in the mat matrix (Figure below - Step 2).

6. Select or change to the appropriate Parameter Scaling Options for each of the selected parameters if required (Figure below - Step 3).

7. (Optional) Select a gate from the Gate drop down menu to only include the events within that gate in the mat matrix (Figure below - Step 4).

8. (Optional) Select a Sampling Option (Figure below - Step 5). Although multiple Sampling Methods are available (please refer to the Sampling Options chapter for more details), the default Downsampling Method for an R Add Parameters transformation is None, thus all available events (i.e. the ones defined with the Gate drop-down menu) will be used.

9. Click on the ellipsis at the right of the R Script File field to browse for an R script file (Figure below - Step 6).

10.Select the Event Order. This option defines the orientation of the mat matrix. If Events as Row is selected, the mat object will have events in rows and parameters in columns. If Events as Columns is selected, the mat object will have events as column and parameters as rows.(Figure below - Step 7).

 

The result of the previous steps can be seen in the Figure below:

 

 

 

The custom R Add Parameters transformation is now ready to be applied to plots and Data Grids.

 

The R Script will be automatically run as soon as it will be applied on a plot or a data grid, or as soon as one of the option in the Transformation dialog are modified. To defer running the R Script, uncheck the box for Automatically Run R Script. Doing so will present you with the button to Execute R Script (Figure 29.47) which can be pressed to calculate on demand.

 

 

Once an R Add Parameters transformation has been created, results can be accessed as 1D plots, 2D plots and Data Grid as new parameters. In order to do so, the R transformation must be applied to the object of interest.

 

R Transformations may be applied to 1D plots, 2D plots and data grids by either of the following methods:

 

Drag and Drop (Figure 29.48)

 

1. Left click and hold on New R Add Parameters from the Transformation window.  

2. Drag the transformation to the intended object (1D plots, 2D plots or a data grid).

3. Release the mouse button.

 

The R transformation will be applied to the object. For 1D and 2D plots the title of the plot will now include text "R add parameters added" indicating the transformation has been applied.

 

 

 

Using the Formatting Dialog (Figure 29.49)

 

1. Access the Formatting→Overlays dialog (for 1D and 2D plots) or the Formatting→General dialog (for Data Grids).

2. Choose the R Add Parameters to apply from the Transformation drop down.

3. Click OK.

 

 

 

 

The result of the previous methods for 1D and 2 Plots is represented in Figure 29.50 below. When an R Add Parameters has been applied to a plot, the suffix "R Add Parameters Added" has appear in the object title.

 

 

 

 

 

Once the transformation is applied, transformation results can be accessed as new parameters (Figure 29.51).

 

Next Topic: R Cluster Transformations