**BRB-ArrayTools**

**Version 3.0**

**User's Manual**

by

Dr. Richard Simon

Biometrics Research Branch

National Cancer Institute

and

Amy Lam

The EMMES Corporation

February 21, 2002

**Table of Contents**

Introduction [4](#introduction)

Purpose of this software [4](#purpose-of-this-software)

Overview of the software's capabilities
[4](#overview-of-the-softwares-capabilities)

A note about single-channel arrays
[6](#a-note-about-single-channel-arrays)

Installation [8](#installation)

System Requirements [8](#system-requirements)

Installing the software components
[8](#installing-the-software-components)

Loading the add-in into Excel [9](#loading-the-add-in-into-excel)

Collating the data [10](#collating-the-data)

Overview of the collating step [10](#overview-of-the-collating-step)

Input to the collating step [12](#input-to-the-collating-step)

Input data types [12](#input-data-types)

Expression data [12](#expression-data)

Gene identifiers [13](#gene-identifiers)

Experiment descriptors [13](#experiment-descriptors)

User-defined genelists [14](#user-defined-genelists)

Minimal required data elements [15](#minimal-required-data-elements)

Collating data from raw files [17](#collating-data-from-raw-files)

Example 1 - Arrays are horizontally stacked in one file
[17](#example-1---arrays-are-horizontally-stacked-in-one-file)

Example 2 - Arrays are in separate files
[21](#example-2---arrays-are-in-separate-files)

Example 3 -- Multi-chip sets [25](#example-3-multi-chip-sets)

Collating Affymetrix data from MAS output files
[28](#collating-affymetrix-data-from-mas-output-files)

Collating data from an NCI mAdb archive
[31](#collating-data-from-an-nci-madb-archive)

Output of the collating step [32](#output-of-the-collating-step)

Organization of the project folder
[32](#organization-of-the-project-folder)

The collated project workbook [32](#the-collated-project-workbook)

Filtering the data [35](#filtering-the-data)

Spot filters [35](#spot-filters)

Intensity filter [35](#intensity-filter)

Spot flag filter [36](#spot-flag-filter)

Spot size filter [36](#spot-size-filter)

Detection call filter [36](#detection-call-filter)

Transformations [36](#transformations)

Normalization [36](#normalization)

Median normalization [37](#median-normalization)

Housekeeping gene normalization [37](#housekeeping-gene-normalization)

Lowess normalization [37](#lowess-normalization)

Truncation [37](#truncation)

Gene screening [38](#gene-screening)

Minimum fold-change filter [38](#minimum-fold-change-filter)

Log expression variation filter [38](#log-expression-variation-filter)

Percent missing filter [39](#percent-missing-filter)

Percent absent filter [39](#percent-absent-filter)

Analyzing the data [40](#analyzing-the-data)

Scatterplot tools [40](#scatterplot-tools)

Scatterplot of single array versus array
[40](#scatterplot-of-single-array-versus-array)

Hierarchical cluster analysis tools
[43](#hierarchical-cluster-analysis-tools)

Cluster analysis of genes [46](#cluster-analysis-of-genes)

Cluster analysis of samples [47](#cluster-analysis-of-samples)

Multidimensional scaling of samples
[49](#multidimensional-scaling-of-samples)

Classification tools [51](#classification-tools)

Class comparison [52](#class-comparison)

Class Prediction [57](#class-prediction)

Prediction for new samples [59](#prediction-for-new-samples)

Survival analysis [60](#survival-analysis)

Specifying replicate arrays and paired samples
[60](#specifying-replicate-arrays-and-paired-samples)

Programmable Plug-In Faciltiy [63](#programmable-plug-in-faciltiy)

Hands-on practice using a sample dataset
[65](#hands-on-practice-using-a-sample-dataset)

Further help [72](#further-help)

Some useful tips [72](#some-useful-tips)

Excluding arrays from an analysis
[72](#excluding-arrays-from-an-analysis)

Extracting genelists from HTML output
[72](#extracting-genelists-from-html-output)

Creating user-defined genelists [72](#creating-user-defined-genelists)

Re-playing the three-dimensional rotating scatterplot
[73](#re-playing-the-three-dimensional-rotating-scatterplot)

Stopping a computation after it has started running
[75](#stopping-a-computation-after-it-has-started-running)

Determining the order of the arrays in the collated data
[75](#determining-the-order-of-the-arrays-in-the-collated-data)

Always save the collated project workbook when prompted!
[76](#always-save-the-collated-project-workbook-when-prompted)

Troubleshooting the installation [77](#troubleshooting-the-installation)

Testing the R COM [77](#testing-the-r-com)

Updating the R Server and BRB-ArrayTools library references
[78](#updating-the-r-server-and-brb-arraytools-library-references)

Reporting bugs [80](#reporting-bugs)

References [81](#references)

#  

# Introduction

## Purpose of this software

BRB-ArrayTools is an integrated software package for the analysis of DNA
microarray data. It was developed by the Biometric Research Branch of
the Division of Cancer Treatment & Diagnosis of the National Cancer
Institute under the direction of Dr. Richard Simon. BRB-ArrayTools
contains utilities for processing expression data from multiple arrays,
visualization of data, multidimensional scaling, clustering of genes and
samples, and classification and prediction of samples. BRB-ArrayTools
features drill-down linkage to NCBI databases using clone, GenBank, or
UniGene identifiers, and drill-down linkage to the NetAffx database
using Probeset ids. BRB-ArrayTools can be used to analyze both
single-channel and dual-channel arrays. The package is very portable and
is not restricted to use with any particular array platform, scanners,
image analysis software or database. The package is implemented as an
Excel add-in so that it has an interface that is familiar to biologists.
The computations are performed by sophisticated and powerful analytics
external to Excel but invisible to the user. The software was developed
by statisticians experienced in the analysis of microarray data and
involved in research on improved analysis tools. BRB-ArrayTools serves
as a tool for instructing users on effective and valid methods for the
analysis of their data. The existing suite of tools will be updated as
new methods of analyses are being developed.

## Overview of the software's capabilities

BRB-ArrayTools can be used for performing the following analysis tasks:

-   **Collating data:** Importing your data to the program and aligning
    genes from different arrays. The software can load a maximum of 250
    arrays consisting of up to 65,000 genes. However, other limitations
    may apply, which depend on the user\'s system resources. Both
    dual-channel and single-channel (such as Affymetrix) microarrays can
    be analyzed. Data should be in tab-delimited text format. Data which
    is in Excel workbook format can also be used, but will automatically
    be converted by BRB-ArrayTools into tab-delimited text format.

```{=html}
<!-- -->
```
-   **Filtering and normalization:** Filter individual spots (or
    probesets) based on channel intensities (either by excluding the
    spot or thresholding the intensity), and by spot flag and spot size
    values. Affymetrix data can also be filtered based on the Detection
    Call. For dual-channel chips, normalize arrays by median-centering
    the log-ratios in each array, by subtracting out a lowess-smoother
    based on the average of the red and green log-intensities, or by
    defining a list of housekeeping genes. For single-channel chips,
    normalize arrays by centering the log intensity of each array to the
    median log intensity of the first array, or by defining a list of
    housekeeping genes. Truncate outlying expression levels. Filter
    genes based on the percentage of expression values which are at
    least a specified fold-difference from the median expression over
    all the arrays, by the variance of log-expression values across
    arrays, by the percentage of missing values, and by the percentage
    of "Absent" detection calls over all the arrays (for Affymetrix data
    only).

-   **Scatterplot of array v. array:** For dual-channel data, create
    clickable scatterplots using the log-red, log-green, average
    log-intensity of the red and green channels, or log-ratio, for any
    pair of arrays (or for the same array). For "M-A plots" (i.e., the
    plot of log-ratios versus the average red and green
    log-intensities), a trendline is also plotted. For single-channel
    data, create clickable scatterplots using the log-intensity for any
    pair of arrays. All genes or a defined subset of genes may be
    plotted. Hyperlinks to NCI feature reports, GenBank, NetAffx, and
    other genomic databases.

-   **Scatterplot of phenotype classes:** Create clickable scatterplots
    of average log-expression within phenotype classes, for all genes or
    a defined subset of genes. Hyperlinks to NCI feature reports,
    GenBank, NetAffx, and other genomic databases.

-   **Hierarchical cluster analysis of genes:** Create cluster
    dendrogram and color image plot of all genes. For each cluster,
    provides a hyperlinked list of genes, and a lineplot of median
    expression levels within the cluster versus arrays. The arrays may
    be clustered separately with regard to each gene cluster. Each gene
    cluster can be saved and used in later analyses. A color image plot
    of median expression levels for each gene cluster versus arrays is
    also provided. The cluster analysis may be based on all data or on a
    user-specified subset of genes and arrays.

-   **Hierarchical cluster analysis of samples:** Produces cluster
    dendrogram, and statistically-based cluster-specific reproducibility
    measures for a given cut of the cluster dendrogram. The cluster
    analysis may be based on all data or on a user-specified subset of
    genes and arrays.

-   **Global test of clustering:** Statistical significance tests for
    presence of any clustering among a set of arrays, using either the
    correlation or Euclidean distance metric. This analysis is given as
    an option under the multidimensional scaling tool.

-   **Multidimensional scaling of samples:** Produces clickable 3-D
    rotating scatterplot where each point represents an array, and the
    distance between points is proportional to the dissimilarity of
    expression profiles represented by those points. If the user has
    PowerPoint installed, then a PowerPoint slide is also created which
    contains the clickable 3-D scatterplot. The PowerPoint slide can be
    ported to another computer, but must be run on a computer which also
    has BRB-ArrayTools v3.0 installed in order for the clickable 3-D
    scatterplot to work.

```{=html}
<!-- -->
```
-   **Class comparison:** Uses univariate parametric and non-parametric
    tests to find genes which are differentially expressed between two
    or more phenotype classes. Also computes a global permutation test
    of whether the number of apparently significant genes is greater
    than one would expect by chance. The output contains a listing of
    genes which were significant and hyperlinks to NCI feature reports,
    GenBank, NetAffx, and other genomic databases. The parametric tests
    are either t/F tests, or randomized variance t/F tests. The latter
    provide improved estimates of gene-specific variances without
    assuming that all genes have the same variance. The criteria for
    inclusion of a gene in the gene list is either a p-value less than a
    specified threshold value, or specified limits on the number of
    false discoveries or proportion of false discoveries. The latter are
    controlled by use of multivariate permutation tests.

-   

```{=html}
<!-- -->
```
-   **Class prediction:** Constructs predictors for classifying arrays
    into phenotype classes based on expression levels. Five methods of
    prediction are used: compound covariate predictor, diagonal linear
    discriminant analysis, k-nearest neighbor (using k=1 and 3), nearest
    centroid, and support vector machines. The compound covariate
    predictor, diagonal linear discriminant analysis and support vector
    machines are only implemented for the case then the phenotype
    variable contains only two class labels, whereas the k-nearest
    neighbor and nearest centroid may be used even when the phenotype
    variable contains more than two class labels. Determines
    cross-validated misclassification rate and performs a permutation
    test to determine if the cross-validated misclassification rate is
    lower than would be expected by chance. The analysis may also be
    performed on paired samples. The output contains the result of the
    permutation test on the cross-validated misclassification rate, and
    a listing of genes which comprise the predictor, with parametric and
    permutation p-values for each gene, and hyperlinks to NCI feature
    reports, GenBank, NetAffx, or other genomic databases. Permits
    application of predictive models developed for one set of samples to
    expression profiles of a separate test set of samples.

## A note about single-channel arrays

All of the tools within BRB-ArrayTools can be equally run on
single-channel and dual-channel arrays. For Affymetrix data, it is
suggested that the \"signal\" field produced in MAS 5.0 should be used
as the intensity signal. If the \"average difference\" field is used as
the intensity signal, then genes with negative \"average difference\"
will be automatically thresholded to a value of 1 (log-transformed value
of 0). For sake of convenience of exposition, we will assume
dual-channel data throughout this document. We will refer to log-ratios,
though a comparable analysis can be run on the log-intensities for
single-channel data. We will also refer to \"spots\" but for Affymetrix
arrays the analog of \"spot\" is the probe set used to detect the
expression of a specified gene.

All analyses on log-intensities work exactly the same way as the
analyses on log-ratios, but for two exceptions:

1)  [Data normalization]{.underline}: The median-normalization of
    single-channel (e.g., Affymetrix) data is normalized such that the
    median log-intensity of each array is equal to the median
    log-intensity of the first array. Lowess (intensity-dependent)
    normalization is not available for single-channel data.

2)  [Class prediction]{.underline}: To reduce the dominating effect that
    genes with overall high intensity might have, the single-channel
    log-intensities are median-centered on a gene-by-gene basis for all
    class prediction methods.

# Installation

## System Requirements

BRB-ArrayTools is Windows-compatible software, Windows 98/2000/NT/XP or
later. It is designed to be used as an add-in to Excel 2000.
BRB-ArrayTools is no longer supported for Excel 97.

It is recommended that the user have at least 256MB of RAM. It is
possible to run BRB-ArrayTools with less than 256MB of RAM; however,
some procedures may be very slow or may not be able to run at all,
depending on the size of the dataset.

For producing high-resolution graphics, it is recommended that the user
set the display color palette to **True Color**. To change the display
color palette settings, click on the following sequence of items:
**Windows Start Button  Settings  Control Panel  Display 
Settings**.

## Installing the software components

The BRB-ArrayTools software and associated files may be downloaded from
the BRB website:

<http://linus.nci.nih.gov/BRB-ArrayTools.html>

If you have Excel open, please close Excel before installing
BRB-ArrayTools.

There are three installation steps:

1.  If you do not already have the **Java Runtime Environment v1.2.2**
    on your computer, then you should download and execute the
    jre-1_2_2_011-win.exe installation file. (If you already have a
    previous version of BRB-ArrayTools on your computer, then you do not
    need to complete this step because you should already have the JRE
    v1.2.2 on your computer.)

2.  If you do not already have the **R 1.6.1** software on your
    computer, then you should download and execute the rw1061.exe
    installation file. (Previous versions of BRB-ArrayTools used R
    1.2.0, so you will need to complete this step even if you already
    have a previous version of BRB-ArrayTools on your computer, unless
    you have already specifically upgraded your R to version 1.6.1.)

3.  Now you are ready to install **BRB-ArrayTools**. Download and
    execute the ArrayTools_v3_0beta.exe installation file. The
    BRB-ArrayTools installer will automatically install the R-COM into
    your R 1.6.1 installation directory. If you do not already have R
    1.6.1 installed, then you need to go back to step 2 and install R
    1.6.1 first. If you have a previous version of BRB-ArrayTools
    installed, then you should install the newer version into the same
    installation directory as the previous version, and the newer
    version will overwrite the previous version. (You should avoid
    installing BRB-ArrayTools in a different directory than the previous
    version, since this would require that you go through additional
    procedures when loading the add-in within Excel.)

## Loading the add-in into Excel

To begin using BRB-ArrayTools, you must have BRB-ArrayTools loaded into
Excel as an add-in. The BRB-ArrayTools installer now pre-loads
BRB-ArrayTools into Excel, so users no longer have to load
BRB-ArrayTools into Excel as a separate step as they did with previous
versions of BRB-ArrayTools. Users may still load and unload
BRB-ArrayTools in Excel manually by going to the **Tools** menu within
Excel and clicking on **Add-Ins**.

If you close an Excel session with BRB-ArrayTools still loaded, then
your next Excel session will automatically begin by re-loading
BRB-ArrayTools. BRB-ArrayTools will not be unloaded from Excel unless
you specifically unload it through the **Add-Ins** dialog.

# Collating the data

## Overview of the collating step

**Collating** is a process in which your data are read, sorted, and
written to a standard Excel workbook format which is \"understood\" by
BRB-ArrayTools. The user inputs three types of data (expression data,
gene identifiers, and experiment descriptors) by entering parameters to
describe the file format of each data type. BRB-ArrayTools then
processes these data files and produces a **collated project workbook**
which is a standard data format used by all the analysis tools included
in the software package. Curated gene lists may also be used to define
gene functions or pathways, and will be read in at the time of
collating. The following page contains a diagram of the entire process.

  -----------------------------------------------------------------------
  A note about Excel workbooks

  A single Excel file (with an .xls extension) is called a **workbook**,
  and a workbook may contain one or more spreadsheets called
  **worksheets**. A tab-delimited ASCII text file with an .xls extension,
  though not a true Excel object, is interpreted by Excel to be a
  workbook containing a single worksheet.
  -----------------------------------------------------------------------

## 

## 

## 

## 

## 

## 

##  

## Input to the collating step

The input data files should be tab-delimited ASCII text files. Excel
workbooks (where the input data is on the *first* worksheet if there are
multiple worksheets within the workbook) may be used instead of
tab-delimited text files. However, BRB-ArrayTools will automatically
convert those Excel files into tab-delimited text format. If the user
wishes to save a copy of the original Excel files, then the user should
first save a copy of those original data files into another folder. The
user must enter enough information describing the format of these input
data files (such as the column designation of each data element) so that
BRB-ArrayTools can find and process these data elements from the input
files.

### Input data types

#### Expression data

BRB-ArrayTools accepts three input file formats for the expression data:
(1) arrays **horizontally stacked** in one file, (2) arrays in
**separate files**, and (3) arrays from **multi-chip sets**. Multi-chip
sets are sets of arrays in which the total number of clones or probesets
are divided over several arrays. BRB-ArrayTools accepts multi-chip sets
with up to 5 array types in the set, with each array in the set labeled
as 'A', 'B', 'C', 'D', and 'E' for convenience. These three input
formats will be described as examples in the "Collating data from raw
files" section of this manual. The data format for multi-chip sets is
similar to the data format for the horizontally stacked or separate
files, except that for multi-chip sets, there is either one horizontally
stacked file for each array type in the set, or one data folder for each
array type in the set which contains a separate data file for each array
which was performed of that array type. For multi-chip sets, the
individual arrays are normalized separately, but the data for all arrays
will be concatenated to form one large dataset. A "shortcut" interface
is available for collating Affymetrix data outputted as text files from
MAS 4.0 or 5.0, and for data archives downloaded from NCI's mAdb system.

If the genes are listed in the same order and there is a one-to-one
correspondence between the rows of each of the expression data files,
then the data is said to be **aligned**. The horizontally stacked data
format can only be used when the genes are already aligned, while the
other two data formats may be used whether or not the genes are already
aligned. When the input data is in separate files, BRB-ArrayTools will
automatically align the data as it collates, and any gene which is
multiply-spotted within any array will have its expression data
geometrically averaged over the replicate spots within the array. Genes
which are multiply-spotted over several arrays in a multi-chip set will
only have replicates within the same array averaged, but replicates
across different arrays will not be averaged.

The required expression data elements are either the red and green
signal intensity columns or the log-ratio column (for dual-channel
data), or a single signal intensity column (for single-channel data). If
a background subtraction is desired for the dual-channel data, then the
red and green background columns are also necessary. In addition, a spot
flag or spot size column may optionally be entered, to allow spot
filtering using these data elements. For Affymetrix data, the Detection
Call (Absent, Marginal, or Present) may be used as the "spot flag"
variable for the purpose of flag filtering.

#### Gene identifiers

Various identifiers can be associated with each spot, such as spot
numbers, well numbers, clone names, clone identifiers, probe set
identifiers, UniGene identifiers, GenBank accession numbers, etc. The
gene identifiers may be located alongside the expression data in the
same files, or may be contained in a separate file which is used as a
look-up table for the genes on all the arrays. If the gene identifiers
are contained in a separate file, then there must be corresponding
columns within the expression data file(s) and the gene identifier file,
containing gene ids which can be used for matching the gene identifiers
with the expression data.

The column which is designated within BRB-ArrayTools as **clone id**
should contain an organization-prefixed clone id (e.g., a prefix such as
\"IMAGE:\", \"ATCC:\", \"TIGR:\" etc.). These clone ids can be used to
link to clone reports in the NCBI database. Note that clone reports in
the NCI mAdb database are only available for clones in the NCI Advanced
Technology Center inventory or for other expression array sets which are
tracked by BIMAS/CIT/NIH. All clone identifiers found within a **clone
id** column which are numeric and have no prefix will be assumed to have
a prefix of IMAGE by default.

**Probe set ids** are used to link to feature reports in the NCI mAdb
database. Currently feature reports are available only for the Human
Genome U133 A and B chips, and for the Mouse Genome U74 A-C chips. For
Class Comparison, Class Prediction, and Survival Analysis output, probe
set ids are also used for batch query links to NetAffx.

**UniGene cluster ids** and **gene symbols** are used to search for the
UniGene annotation mirrored in the NCBI database. **GenBank accession
numbers** are used to search for the GenBank annotation which is also
mirrored in the NCBI database.

A minimum of one gene identifier is required for use in collating the
dataset. However, the user may wish to enter any or all of the above
gene identifiers, if they are available, to enhance the usability of the
output from the analyses.

#### Experiment descriptors

A file containing experiment descriptors must be prepared by the user
and input during collation. Each row in the experiment descriptor file
represents an array in the dataset (except for the first row which is a
header row), and each column represents a descriptor variable whose
entries are used to describe each of the arrays. The experiment
descriptor file should contain *exactly* the same arrays as those to be
collated (i.e., it should not contain any extra rows representing arrays
which are not represented in the dataset to be collated).

The first column of the experiment descriptor file should contain the
names of the arrays. If the expression data is in a separate file for
each array, these names should be the filenames (without extensions).
For horizontally stacked data, the order of the arrays in the experiment
descriptor file is assumed to correspond to the order of the arrays in
the gene expression data file.

For multi-chip sets with separate data files for each array, the array
names in the first column of the experiment descriptor file should
contain the filenames (without extensions) of the arrays which are in
the data folder for array type 'A'.

Each succeeding column in the experiment descriptor file contains a
descriptor variable which may be used for labeling purposes, for
identifying reverse fluor arrays, for classification analyses, for
identifying replicate arrays, for matching between paired arrays, or for
specifying the plotting order of the arrays when clustering genes. The
user can create as many columns of the experiment descriptor file as
he/she finds useful for classifying the arrayed samples. There should be
no empty columns between the experiment descriptor columns.

#### User-defined genelists

BRB-ArrayTools allows the user to associate genes with defined functions
or pathways through the use of user-defined genelists. Unlike the other
input data files mentioned above which collectively describe the
expression, genes, and samples of a specific project, the user-defined
genelists are stored in the ArrayTools installation directory, and are
used as a general database for all projects which are analyzed within
BRB-ArrayTools.

In the ArrayTools installation directory, there is a Genelists
subdirectory, which contains the subdirectories Cgap and User. The Cgap
directory contains curated gene lists which have been downloaded from
the Cancer Genome Anatomy Project website
(<http://cgap.nci.nih.gov/Genes/CuratedGeneLists>). These HTML files
will be updated with each new release of BRB-ArrayTools, and may be
manually updated in the interim by the user by replacing or adding to
the existing files with new files downloaded from the CGAP website.

The User directory contains genelists which may be created by the user.
Unlike the HTML formatted files contained in the Cgap directory, the
files contained in the User directory are simply ASCII text files
containing lists of genes. The name of the file denotes the function or
pathway which is defined by the genes listed in the file. The first row
of the file specifies the type of gene identifier used within the file,
and must *exactly* match one of the following pre-defined labels

Unique id

> Description
>
> Clone
>
> Probe set
>
> GB acc
>
> UG cluster
>
> Gene symbol

or must exactly match one of the write-in gene identifier names
specified in the **column format** section of the **gene identifiers**
page of the **collating data** dialog box. Each succeeding row of the
file should contain the gene identifier of a specific gene or clone to
be included in the list.

The User directory currently contains some examples of genelists which
will be used with the BreastSamples dataset which is provided with this
package. These example genelists are used with the example dataset, and
may be deleted at any time by the user.

Some procedures will automatically create new user genelists. The
following procedures can be used to create new genelists: the
hierarchical clustering of genes, the class comparison tool, and the
class prediction tool. The name of the genelist which is produced by the
class comparison or class prediction tool is specified by the user
before running the analysis. If there is already an existing genelist
with the same name, then that genelist will be overwritten.

During the collating step, genes in the user\'s dataset will
automatically be matched against CGAP and user-defined genelists which
are currently stored within the Genelists folder. If any of the genes in
the user\'s dataset match any of the genelists, then the name of the
genelist will appear in a column of the **gene identifiers** page in the
collated project workbook. If the user adds a new genelist after the
data has already been collated, then the gene annotations in the **gene
identifiers** page can be updated by clicking on the **ArrayTools 
Utilities  Annotate data using genelists** menu item**.**

### 

#### Minimal required data elements

Although there are many optional data elements which may be input into
the collating step, the minimal required data elements for all input
formats are as follows:

(1) the expression data (either the red and green signals or the
    log-ratio for dual-channel data, or the single signal intensity for
    single-channel data),

(2) at least one gene identifier (may be located alongside the
    expression data or in a separate gene identifier file), and

(3) at least one experiment descriptor column (the array id) in the
    experiment descriptor file.

### Collating data from raw files

#### 

#### Example 1 - Arrays are horizontally stacked in one file

**Format of the raw data files**

In this file format, the expression data from each array is represented
by a block of columns in the data file, and the array data blocks are
horizontally stacked in one file. There may be other columns, such as
gene identifiers, which precede the array data blocks. However, there
should be no other miscellaneous data columns following the last array
data block. If there are any other data columns following the last array
data block, then the user should either delete those last columns or
move them to the beginning of the file so that they precede the first
array data block.

The file may be a tab-delimited ASCII text file, or an Excel spreadsheet
(a single worksheet within an Excel workbook). If the file is an Excel
spreadsheet, then BRB-ArrayTools will automatically convert it to text
format. The following figure shows an example of a horizontally stacked
expression data file with four columns in each data block:

![](media/image1.png){width="5.998611111111111in"
height="1.5819444444444444in"}

![](media/image2.png){width="3.1in" height="1.1625in"}The figure to the
right shows the experiment descriptor file. The experiment descriptor
file describes the samples used in the dataset. This particular dataset
is a replication study. Each row of the experiment descriptor file
describes the sample on one array. The order of the arrays listed in the
experiment descriptor file are assumed to correspond to the order of the
array data blocks in the expression data file. Thus, array data block #1
will be matched with HSOC2px-10 in row 2 of the experiment descriptor
file, array data block #2 will be matched with HSOC2px-11 in row 3 of
the experiment descriptor file, etc. The Reverse descriptor in column D
indicates the arrays on which the fluors were reversed.

**Collating parameters**

There are two ways in which the data may be specified in the collating
dialog form. One way is to enter the red and green signal columns, and
let BRB-ArrayTools compute the log-ratio. Another way is to enter the
log-ratio column directly. The user is not permitted to enter both the
log-ratio and the dual-channel signals, since the log-ratios can be
computed once the dual-channel signals are entered. It is preferred that
the dual-channel signals be entered (if they are available) rather than
the log-ratio, since BRB-ArrayTools can use the signal intensities for
filtering, lowess (intensity-based) normalization, and creating
diagnostic scatterplots. If the log-ratios are entered directly, then
these functionalities are not available to the user.

![](media/image3.png){width="3.9in" height="3.6798611111111112in"}The
first figure on the right shows the collating parameters which would be
entered on the **Expression data** page of the collating dialog box to
describe the horizontally stacked data file shown above, if the signal
intensities were to be entered rather than the log-ratio. The user
should browse for or type in the name and path of the file which
contains the expression data. Note that the column designations of the
red, green, and spot flag variables are *relative to the first column of
the array data block*. In other words, a designation of "4" for the spot
flag column means that the spot flag is in the *fourth* column of each
array data block. Any extra columns within the array data blocks which
are not specifically designated in the **Data variables** section of the
collating dialog box, such as the third column (the log-ratios), will be
ignored during the collating step. Since BRB-ArrayTools automatically
calculates the log-ratio from the red and green signals, it is not
necessary to enter the log-ratios as input. The second figure on the
right shows the collating parameters which would be entered on the
**Expression data** page of the collating dialog box to describe the
horizontally stacked data file shown above, if the log-ratios were to be
entered directly instead of the signal intensities.

![](media/image5.png){width="3.9in" height="3.6798611111111112in"}The
figure on the right shows the collating parameters which would be
entered on the **Gene identifiers** page of the collating dialog box. In
this case, the gene identifiers are found in the same rows alongside the
expression data, not in a separate file. The gene identifiers are
specified by their column designation under the **Column format**
section, which are given relative to the file specified in the **File**
section.

![](media/image6.png){width="3.9in" height="3.6798611111111112in"}The
figure on the right shows the collating parameters which would be
entered on the **Experiment descriptors** page of the collating dialog
box. The user should browse for or type in the file and path name of the
experiment descriptor file. In this case, any array with a label of 1 in
column **D** of the experiment descriptor file would have its intensity
ratios "flipped" so that the log-ratios in that array are "reversed" to
have the opposite sign.

The **Filter** dialog box, which allows the user to change the default
filtering parameters, will be reviewed in a separate section of this
manual. After all the collating and filtering parameters have been
entered, the user will be prompted for the name of the **project
folder** and the name of the **collated project workbook** to be
created.

#### Example 2 - Arrays are in separate files

**Format of the raw data files**

In this file format, the expression data from each array is stored in a
separate file. [All files must have the same column format, though the
genes contained in the rows of the separate files may
differ.]{.underline} Each file may be a tab-delimited ASCII text file,
or an Excel spreadsheet (a single worksheet within an Excel workbook).
If the files are a Excel spreadsheets, then BRB-ArrayTools will
automatically convert them to text format. The BreastSamples dataset
enclosed with this software package is an example of this data format.
This dataset was obtained from published data by Ross, et al.

To view the BreastSamples dataset, unpack the BreastSamples.zip file
using WinZip or other utility. When you unpack the dataset, you should
get a folder called BreastSamples, containing a gene identifier file
called GeneIds.xls, an experiment descriptor file called ExpDesc.xls,
and a subfolder called ExpressionData. Inside the ExpressionData
subfolder, there are thirteen expression data files. The expression data
files in this dataset are already aligned.

The following figure shows the format of each of the expression data
files:

![](media/image7.png){width="2.55in" height="1.492361111111111in"}

The following figure shows the format of the gene identifiers file:

![](media/image8.png){width="5.993055555555555in"
height="1.5138888888888888in"}

![](media/image9.png){width="2.85in" height="2.1305555555555555in"}The
following figure shows the format of the experiment descriptors file:

**Collating parameters**

![](media/image10.png){width="3.9in" height="3.6770833333333335in"}The
following three figures show the collating parameters which would be
entered on the **Expression data** page, **Gene identifiers** page, and
**Experiment descriptors** page of the collating dialog box, for
collating the BreastSamples data using SPOT as the unique gene
identifier which links the expression data with the gene identifiers.

![](media/image11.png){width="3.9in" height="3.6770833333333335in"}

![](media/image12.png){width="3.9in" height="3.6770833333333335in"}

The **Filter** dialog box, which allows the user to change the default
filtering parameters, will be reviewed in a separate section of this
manual. After all the collating and filtering parameters have been
entered, the user will be prompted for the name of the **project
folder** and the name of the **collated project workbook** to be
created.

#### Example 3 -- Multi-chip sets

**Format of the raw data files**

In this file format, it is assumed that the user has up to five array
types in the multi-chip set, which for convenience are designated within
BRB-ArrayTools as type 'A', 'B', 'C', 'D', and 'E'. For example, the
Affymetrix U133 is a multi-chip set, with the total set of probesets
divided between the U133A and U133B chips. The user does not need to
have performed experiments using all of the array types in a multi-chip
set, but it is expected that for the array types which were actually
used from the set, the same samples should have been used for each array
type. For example, if the user chose to use only two chip types from a
five-chip set, then for each sample used on array type 'A', the same
sample should also have been used on array type 'B'.

The data for each of the array types, can in turn be in the horizontally
stacked or separate files format, as described in Examples 1 and 2. If
the data for each array type is in a horizontally stacked format, then
all the horizontally stacked files should have the same format, with the
same number of data columns in each file. The following is an example of
the data columns which might be found for a multi-chip set consisting of
two array types, with three samples performed on each array type:

[DataFileA.txt]{.underline}

  ------------ ----------------- --------------- ----------------- --------------- ----------------- ---------------
  **GeneId**   **Exp1_Signal**   **Exp1_Flag**   **Exp2_Signal**   **Exp2_Flag**   **Exp3_Signal**   **Exp3_Flag**

  Gene1                                                                                              

  Gene2                                                                                              

  Gene3                                                                                              
  ------------ ----------------- --------------- ----------------- --------------- ----------------- ---------------

[DataFileB.txt]{.underline}

  ------------ ----------------- --------------- ----------------- --------------- ----------------- ---------------
  **GeneId**   **Exp1_Signal**   **Exp1_Flag**   **Exp2_Signal**   **Exp2_Flag**   **Exp3_Signal**   **Exp3_Flag**

  Gene1                                                                                              

  Gene2                                                                                              

  Gene3                                                                                              
  ------------ ----------------- --------------- ----------------- --------------- ----------------- ---------------

In the above example, the array data blocks consist of 2 columns each,
with Signal being in column 1 of each array data block, and Flag being
in column 2 of each array data block. The *first* data block begins in
column 2.

If the same dataset were formatted in the separate files format, then
the user would have two folders, with each folder containing a data file
for each of the three experiments Exp1, Exp2, and Exp3, as follows:

[In data folder 'A':]{.underline}

[Exp1a.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

[Exp2a.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

[Exp3a.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

[In data folder 'B':]{.underline}

[Exp1b.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

[Exp2b.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

[Exp3b.txt]{.underline}

  --------------------------- ---------------------- --------------------
  **GeneId**                  **Signal**             **Flag**

  Gene1                                              

  Gene2                                              

  Gene3                                              
  --------------------------- ---------------------- --------------------

The filenames in data folder 'A' and data folder 'B' are allowed to
differ by a one-character suffix, but need not differ at all. However,
the array labels in the first column of the Experiment Descriptor file
should always match the filenames in data folder 'A' (without the file
extensions), not the filenames in the other data folders.

For example, the following sets of filenames are all acceptable:

[Data Folder 'A':]{.underline} Exp1.txt, Exp2.txt, Exp3.txt

[Data Folder 'B':]{.underline} Exp1.txt, Exp2.txt, Exp3.txt

> (The first column of the Experiment Descriptor file should contain the
> array labels Exp1, Exp2, and Exp3 in this case.)

or

[Data Folder 'A':]{.underline} Sample1.txt, Sample2.txt, Sample3.txt

[Data Folder 'B':]{.underline} Sample1b.txt, Sample2b.txt, Sample3b.txt

> (The first column of the Experiment Descriptor file should contain the
> array labels Sample1, Sample2, and Sample3 in this case.)

However, the following set of filenames are not acceptable, because
BRB-ArrayTools would not know how to match up the files in data folder
'A' with the files in data folder 'B'

[Data Folder 'A':]{.underline} Sample1.txt, Sample2.txt, Sample3.txt

[Data Folder 'B':]{.underline} Exp1.txt, Exp2.txt, Exp3.txt

###  

### Collating Affymetrix data from MAS output files

BRB-ArrayTools has a dialog especially designed for easy importing of
Affymetrix data. To access this tool, go to the **ArrayTools  Collate
data  Affymetrix GeneChips** menu item.

If the user has Affymetrix data, then the CHP files should be exported
from MAS 4.0 or 5.0 as tab-delimited text files in either the
"horizontally stacked" or "separate files" input data formats as
previously described.

If data is exported in the horizontally stacked input data format, then
a Pivot Table should be created for each chip type, containing the
absolute analysis data from all experiments which were performed of that
chip type, and each pivot table should be exported as a tab-delimited
text file.

If the data is exported in the "separate files" format, then the Metrics
Table data from each CHP file should be exported as a separate
tab-delimited text file, and the files should be named and organized
into folders as described in "Example 3 -- Multi-chip sets" above.

### 

The files may contain miscellaneous rows before the column header row,
but all files must have the exact same format (and same number of
miscellaneous rows before the column header row). BRB-ArrayTools will be
able to automatically read and parse the tab-delimited text files if the
text files have a header row in any of the following formats.

**In all of the following formats, the "Probe Set Name", "Signal" and
"Detection" are the only required columns from MAS 5.0 data, and the
"Probe Set Name", "Avg Diff" and "Abs_Call" are the only required
columns from MAS 4.0 data. All other columns are optional.**

BRB-Arraytools can automatically recognize the data format of files that
have been exported directly from MAS 4.0 and MAS 5.0. However, users who
choose to edit the data columns and column headers of their files should
follow the format described below, in order for BRB-ArrayTools to
automatically recognize the data format. If the column header row is not
in any of the following formats, then BRB-ArrayTools will not be able to
parse the files automatically. In that case, the user will need to use
either the 'horizontally stacked' or 'separate files' collating dialogs
(for a single array type) or the "multi-chip sets" collating dialog (for
multi-array sets), in order to collate the data.

**[For expression data in a "horizontally stacked" file (using one
horizontally stacked file for each chip type):]{.underline}**

1\. [For expression data outputted from a Pivot Table in MAS
5.0:]{.underline}

Probe Set Name Description Exp1\_ Signal Exp1_Detection Exp2_Signal
Exp2_Detection

1053_at Human replication 234 P 456 P

1773_at Human farnesyl- 123 P 39 P

2\. [For expression data outputted from a Pivot Table in MAS
4.0:]{.underline}

Probe Set Name Description Exp1_Avg Diff Exp1_Abs_Call Exp2_Avg Diff
Exp2_Abs_Call

1053_at Human replication 234 P 456 P

1773_at Human farnesyl- 123 P 39 P

For the above two formats, the prefixes Exp1 and Exp2 will be used as
experiment names in the collated project workbook. You may use any other
experiment names, but do not use the following special characters "\\ /
: \* ? " \< \> \| ." which have special meanings in Windows. The "Probe
Set Name" column label may also be given as simply "Probe Set". The
detection (Abs_call) column should be right next to the signal (Avg
Diff) column for each experiment.

**[For expression data in a "Separate Files" format:]{.underline}**

1\. [For expression data outputted from a Metric Table in MAS
5.0:]{.underline}

Probe Set Name Description Signal Detection

1053_at Human replication 234 P

1773_at Human farnesyl- 123 P

2\. [For expression data outputted from a Metric Table in MAS
4.0:]{.underline}

Probe Set Name Description Avg Diff Abs_Call

1053_at Human replication 234 P

1773_at Human farnesyl- 123 P

3\. [In addition to the above mentioned file formats, the following file
format from the NCBI portal will also be recognized:]{.underline}

ID_REF VALUE ABS_CALL

AFFX-MurIL2_at -896 A

AFFX-MurIL10_at 682 A

4\. [In addition to the above mentioned file formats, the following file
format from mAdb will also be recognized:]{.underline}

AffyId Signal Detection Call

A28102_at 7.002252579 A

AB000114_at 4.121015549 A

Each file should contain data from one chip or array. The files from a
different chip type or array type should be placed in a separate folder.
The names of the separate files will be used as experiment names in the
collated project workbook.

**[Gene annotations file format:]{.underline}**

If you have probe set annotation columns other than the Description
column, please place them in a separate tab-delimited gene annotation
file and use the following column header labels. For multi-chip sets,
please place all your probe set annotation information in just one file.

Probe Set ID or Probe Set Name - the name of the probe set.

Title or Description - the description or title of the probe set.

Unigene - the Unigene Id.

Gene Symbol - the gene symbol.

GenBank or SeqDerivedFrom - the GeneBank Id or source of the sequence.

Map Location or Chromosomal Location - the location of the gene in the
chromosomal map.

###  Collating data from an NCI mAdb archive

BRB-ArrayTools has an interface which allows the National Cancer
Institute Advanced Technology Center users to easily collate their data
which has been downloaded from the \"mAdb\" website as a zipped archive.
With this interface, the user only needs to browse for the folder which
contains their unpacked archive, and specify whether or not the genes
are aligned and whether or not the data contains reverse fluor
experiments. If the data contains reverse fluor experiments, then the
user should first edit the array_descriptions file by entering a reverse
fluor indicator in column \"G\", in which reversed arrays are denoted by
the label "Yes".

Currently, this collating interface is only for dual-channel cDNA data,
not for Affymetrix data. If the user has a mAdb archive which contains
Affymetrix data, then the user will need to use the "horizontally
stacked", "separate files", "multi-chip", or "Affymetrix" collating
dialogs.

The zipped archive should be unpacked before collating. When unpacking
the archive, please check to make sure the directory structure of the
archive has been preserved.

When the data for each array is in a separate file, there should be two
files

array_descriptions_xxx_xxxxxx.xls

gene_identifiers_xxx_xxxxxx.xls

and a folder

array_data_xxx_xxxxxx

which are unpacked into the same directory. The array_data_xxx_xxxxxx
folder contains all the expression data files, where each file contains
the expression data for a single array.

## Output of the collating step

### Organization of the project folder

During the collating step, BRB-ArrayTools will create a **project
folder** either within or alongside the folder which contained the
user\'s original raw data files. This project folder will contain the
**collated project workbook**, as well as supporting files needed by the
collated project workbook. Some BRB-ArrayTools analyses may also produce
various output files, which will be written to an Output folder within
this project folder. For example, all the plots which appear onscreen in
the **Cluster viewer** page during cluster analysis are also
automatically saved into the Output folder, and may be subsequently
edited by the user for publication.

### The collated project workbook

The collating procedure produces a collated project workbook. This is an
Excel workbook containing three worksheets labeled **Experiment
descriptors**, **Gene identifiers**, and either **filtered log-ratio**
(for dual-channel data) or **filtered log intensity** (for
single-channel data). All other data variables, such as the red and
green background-adjusted signals and raw log-ratios (for dual-channel
data), the raw log-intensities (for single-channel data), the spot flag
(or Detection Call, for Affymetrix data), and the spot size, will be
written to separate workbooks within the project folder.

The rows in the gene identifiers worksheet correspond to the rows in the
filtered log-ratio (or filtered log intensity) worksheet. The last
column of the gene identifiers and filtered log-ratio (or filtered log
intensity) worksheets contains a filtering variable will be adjusted
each time the user adjusts the filtering levels. To change the filtering
criteria for any given analysis, the user should not manually edit the
filtering column in these worksheets, but should set the filtering
criteria by clicking on the **Filter** button at the bottom of the
dialog box for each analysis.

The **experiment descriptors** worksheet of the collated project
workbook contains an *editable copy* of the experiment descriptors file
which was collated with the data. This copy can be edited by the user to
add descriptors to be used in later analyses, as in the example below:

![](media/image13.png){width="6.0in" height="2.3402777777777777in"}

The **Array-order** descriptor variable, for example, might be used to
specify the order of arrays to use when plotting lineplots of gene
cluster expression.

The **gene identifiers** worksheet of the collated project workbook
contains the gene identifiers whose columns had been specified in the
**column format** section under the **gene identifiers** page of the
collating dialog box.

![](media/image14.png){width="6.0in" height="2.4in"}

A column labeled **Defined genelists** will be added to the gene
identifiers, indicating if the genes matched any of those listed in the
**user defined gene lists**.

The click-arrows in each cell of the header row may be used to search
for specific values of each variable. Column-widths may be adjusted by
hovering the cursor between the columns in the lettered column header
bar and dragging.

The **filtered log ratio** (or **filtered log intensity**) worksheet
contains the log-ratios (or log intensities) *after* the specified
filtering levels have been applied. These are the data values which will
be used for all analyses except the scatterplot of array v. array, where
the log of the channel intensities can also be plotted for dual-channel
data. The first column of the worksheet contains the primary gene id,
which matches the gene id listed in the first column of the gene
identifiers worksheet. Each succeeding column contains the log-ratios
obtained from a single array. The highlighted yellow columns at the end
of the dataset are used internally by BRB-ArrayTools for gene-filtering
purposes. The user should not edit this worksheet in any way.
BRB-ArrayTools will automatically re-filter this worksheet, if
necessary, before running each analysis.

![](media/image15.png){width="2.551388888888889in"
height="2.3402777777777777in"}

# ![](media/image15.png){width="3.3in" height="2.3402777777777777in"}

# 

# 

# 

# 

# 

# 

# 

#  

# Filtering the data

The filtering criteria are specified during the data collating step, and
may be changed prior to each analysis. The dialog box for each analysis
has a **Filter** button on the bottom, which can be used to specify or
change the filtering criteria for all subsequent analyses.

Although the filtering criteria may be changed for each analysis, it may
be important to check the filtering criteria before collating the data
*if* the data contains replicate spots for some genes in the array. This
is because the **spot filtering** is applied *before* averaging the
replicate spots, and replicate spots are *not* re-averaged after the
collating step has been completed, even if the user changes the
filtering criteria.

The **Filtered log ratio** (or **Filtered log intensity**) worksheet of
the collated project workbook will reflect the filtering actions which
have been selected. With the exception of replicated spots which are
filtered before averaging, the supporting files which are located in the
project folder will *not* reflect the filtering actions which have been
selected.

The order of operations for filtering the data is that spot filters are
applied first, then data normalization, then truncation of extreme
values, then gene screening.

## Spot filters

Spot filtering refers to filters on spots in individual arrays. Spot
filtering is used for quality-control purposes, to filter out \"bad\"
spots. Unlike gene screening, spot filtering does not filter out the
entire gene (row), but replaces the existing value of a spot within any
given array with a missing value.

### Intensity filter

For dual-channel data, a spot may either be filtered out (excluded) from
the analysis, or thresholded (with one signal set equal to the specified
minimum) in the analysis. Using the filtering option, a spot on any
array which has a red signal less than the specified minimum and/or a
green signal less than the specified minimum will have its log-ratio
value filtered out on the **filtered log ratio** worksheet. Using the
thresholding option, a spot on any array which has BOTH signals less
than the specified minimum will be filtered out, but a spot which has
only ONE signal less than the specified minimum will have the
below-minimum value set equal to the specified minimum, in computing the
log-ratio value which is shown in the **filtered log ratio** worksheet.
The intensity filter is applied to the *background-adjusted* red and
green signals.

For single-channel data, a spot on any array which has a signal
intensity less than the specified minimum may either be filtered out or
thresholded on the **filtered log intensity** worksheet.

### Spot flag filter

The spot flag filter can contain both numeric and character values. The
user may specify a numeric range outside of which a numeric flag is
considered to be "excluded", and/or specify a list of flag values
denoting the "excluded" values. When the flag filter is on, a spot on
any array which has an "excluded" flag value will be filtered out on the
**filtered log ratio** (or **filtered log intensity**) worksheet. The
flag field is optional.

For Affymetrix users, a Detection Call column can be designated as the
spot flag column at the time of collating, allowing users to filter out
expression values which have an Absent call. Additionally, the spot flag
column (or Detection Call column, for Affymetrix users) is also used by
the Percent Absent Filter, to filter out spots (or probesets) with a
large percentage of expression values which have a spot flag (or
Detection Call) value of "A".

### Spot size filter

The spot size field is optional, but when the spot size filter is on and
the spot field is present, then a spot on any array which has a spot
size less than the minimum value will be filtered out on the **filtered
log ratio** (or **filtered log intensity**) worksheet. For Affymetrix
data, the number of pairs used to compute the signal can be used as a
surrogate for the spot size measurement.

### Detection call filter

For data collated using the **Affymetrix GeneChips** collating
interface, the Detection call filter is a special case of the spot flag
filter mentioned above, allowing users to filter out expression values
based on the Detection call. The Detection data column is also used by
the Percent Absent Filter to filter out probesets with a large
percentage of Detection Calls which have a value of "A".

## Transformations

A logarithmic (base 2) transformation is applied to the signal
intensities (for single-channel data) or intensity-ratios (for
dual-channel data) before they are normalized and truncated. The effect
of the data normalization and truncation will be reflected in the
**Filtered log ratio** (or **Filtered log intensity**) worksheet of the
collated project workbook.

### Normalization

There are currently three normalization options: median normalization,
housekeeping gene normalization, and lowess normalization. The median
normalization and housekeeping gene normalization options are available
for both single-channel and dual-channel data, but the lowess
normalization option is available only for dual-channel data.

#### Median normalization

For single-channel data, the log-intensities are normalized by
subtracting a constant from each array so that the median over each
array is the same as the median over the *first* array. For dual-channel
data, each array is normalized separately by subtracting the median
log-ratio from all the log-ratios on the array. This is equivalent to
multiplying all of the intensities in one channel of an array by a
normalization factor.

#### Housekeeping gene normalization

The user may specify a housekeeping genelist which will be used for
normalization. For single-channel data, the normalization factor for
each array is computed as the median log-intensity over the housekeeping
genes on the *first* array minus the median log-intensity over the
housekeeping genes on the array being normalized. This normalization
factor is added to all the log-intensities over the array. For
dual-channel data, the median log-ratio over the housekeeping genes is
subtracted from all the log-ratios on each array.

#### Lowess normalization

For dual-channel data, a lowess (or intensity-dependent) normalization
option is also available. For dual-channel data, median normalization is
equivalent to multiplying all of the intensities in one channel of an
array by a normalization factor. In some cases it can be advantageous to
have a different normalization factor for different intensity levels;
i.e. the dye bias may be different for low intensity spots relative to
high intensity spots. In the lowess normalization, a non-linear lowess
smoother function is fit to the graph of un-normalized log-ratio on the
y-axis versus average log intensity (i.e. \[log(Red)+log(Green)\]/2 ) on
the x-axis. This is the so-called M-A plot. The lowess smoother is based
on a concatenation of linear regressions for points in overlapping
intervals on the x-axis of the M-A plot. This lowess smoother is
subtracted from the un-normalized log-ratios for the array in order to
obtain the normalized log-ratios. The lowess normalization is much more
computationally intensive than the median centering normalization and
may require up to 10 seconds per array on some computers using data with
35,000 genes. You may wish to first normalize your data using the
default method and then examine M-A scatterplots to determine whether
intensity dependent normalization is needed. If most of the points of
the M-A plot are distributed equally above and below the 0 value of the
y-axis, without a trend over x-values, then intensity based
normalization is not needed.

### Truncation

This option allows the user to specify a maximum intensity (for
single-channel data) or intensity ratio (for dual-channel data) to be
used for analysis. Any values greater than the specified threshold will
be truncated to the threshold. For truncation of intensity ratios, both
the intensity ratios and inverse intensity ratios will be truncated
(e.g., an intensity ratio threshold of 64 means that all intensity
ratios will be truncated to lie between 1/64 and 64).

## Gene screening

Gene screening, unlike spot filtering, is not applied on an
array-by-array basis for each gene. Instead, it uses a criterion based
on *all* arrays for a given gene, to determine if that gene should be
screened out or not. Its purpose is not to filter out \"bad\" spots, but
rather to screen out genes which are not likely to be informative. The
last column (labeled **Filter**) on the **Gene identifiers** and
**Filtered log ratio** (or **Filtered log intensity**) worksheets are
internally used by BRB-ArrayTools to select the genes which pass the
screening.

### Minimum fold-change filter

Genes which have low variation may be filtered out using the minimum
fold-change filter. Here the criterion for filtering out a gene is based
upon the percentage of expression values for that gene which have at
least a minimum fold-change from the median expression value for that
gene. The user may specify the minimum fold-change which is required. If
less than a specified percentage of expression values meet the minimum
fold-change requirement, then the gene is filtered out.

### Log expression variation filter

Here the criterion for filtering out a gene is based upon the variation
of its log expression values across all arrays after normalization.
Filtering low variance genes is not really necessary except for
clustering genes, where the computer memory requirements increase
rapidly with the number of genes clustered. Several filtering options
are available.

One option is to filter the gene if the proportion of the arrays in
which the expression of the gene differs less than two-fold from the
median expression of that gene does not exceed a specified threshold. A
fold-difference criteria other than two-fold may also be specified by
the user. The median expression of each gene is computed over all of the
arrays.

Alternatively, the filtering can be based on the variance for the gene
across the arrays. One can exclude the x% of the genes with the smallest
variances, where the percentile x is specified by the user. Or a
statistical significance criterion based on the variance can be used. If
the significance criterion is chosen, then the variance of the
log-ratios for each gene is compared to the *median* of all the
variances. Those genes not significantly more variable than the median
gene are filtered out. The significance level threshold may be specified
by the user. Specifically, the quantity (n-1) Var~i~ / Var~med~ is
computed for each gene i. Var~i~ is the variance of the log intensity
for gene i across the entire set of n arrays and Var~med~ is the median
of these gene-specific variances. This quantity is compared to a
percentile of the chi-square distribution with n-1 degrees of freedom.
This is an approximate test of the hypothesis that gene i has the same
variance as the median variance.

### Percent missing filter

Here the criterion for filtering out a gene is based upon the percentage
of expression values which are not missing and not filtered out by any
of the previous spot filters.

### Percent absent filter

Here the criterion for filtering out a gene is based upon the percentage
of Absent calls in the Spot Flag or Detection variable. This gene filter
may be applied *independently* of the Spot Flag Filter or Detection Call
Filter described in the "Spot Filters" section above, though it uses the
same Spot Flag or Detection Call variable. For instance, a user may
choose to turn *off* the Detection Call Filter in order to preserve all
"Absent" expression values as they are, but turn *on* the Percent Absent
Filter in order to exclude probesets which are considered unreliable or
uninteresting because too many of the expression values were "Absent".
In this case, probesets which did not get excluded by the Percent Absent
Filter still maintain their expression values even for those values
which were "Absent".

# Analyzing the data

## Scatterplot tools

### Scatterplot of single array versus array

It is frequently of interest to plot the log-ratios of one array versus
the log-ratios of another array. Generally, most of the plotted points,
which represent genes with nonmissing values in both arrays, will line
up along a 45-degree diagonal line. All genes which pass the filtering
criteria will be used in the scatterplot, unless a genelist has been
selected. Genes which are differentially expressed between the two
arrays will fall outside of a pair of outlier lines. These outlier lines
can be specified by the user to indicate genes whose expression ratios
in the two arrays are larger than a given fold-difference.

The user may click on individual points in order to identify its
associated gene and to hyperlink to annotated clone reports within NCBI
database. Or, all the genes outside of the outlier lines can be
simultaneously selected by clicking on a button.

![](media/image16.png){width="3.347916666666667in" height="3.5in"}For
dual-channel arrays, it may also be of interest to plot the
log-intensity of one channel versus the log-intensity of the other
channel, or to plot the reference sample in one array versus the
reference sample in another array (to check reproducibility). Such plots
might reveal any of the following descriptive features: whether or not
one channel is uniformly higher than the other, whether the two channels
are linearly related (they should be if most genes are not
differentially expressed between the two samples), and whether or not
there are points which are "clumped" away from the mass of points. A
plot of log(Red) versus log(Green) within the same array will often show
a "fanning" out effect at the lower end, showing that low-intensity
spots are generally less reproducible than the higher-intensity spots.
These plots can sometimes be used to help determine appropriate
thresholds for the intensity filter.

For dual-channel arrays it may be easier to detect non-linearities that
represent inadequate normalization by examining the so-called M-A plot,
rather than the plot of log(Red) versus log(Green). The M-A plot is a
graph of the normalized log-ratio on the y-axis versus average log
intensity (i.e. \[log(Red)+log(Green)\]/2 ) on the x-axis. Most of the
points of the M-A plot should be distributed equally above and below the
0 value on the y-axis, without a trend over x-values. If there is a
trend, then intensity based normalization may be needed.

**[Scatterplot of phenotype averages]{.underline}**

To compare the arrays in one phenotype class versus the arrays in
another phenotype class, BRB-ArrayTools provides a tool which plots the
average log-ratio within one class on the x-axis versus the average
log-ratio within the other class on the y-axis. These averages are taken
on a gene-by-gene basis, and each gene is represented by a single point
in the resulting scatterplot. The experiment descriptor sheet must
contain a descriptor variable containing the class labels to be
compared. A blank label in this column means that the corresponding
array will be omitted from the analysis. For this analysis, the column
should contain only two unique class labels, and all labels belonging to
other classes should be "blanked" out by the user.

Genes which are differentially expressed between the two phenotypes will
fall outside of a pair of outlier lines. These outlier lines can be
specified by the user to indicate genes for which the fold-difference
between the geometric mean of the expression ratios within each of the
two classes is greater than a specified amount.

As with the scatterplot tool for a single array versus array, the user
may click on individual points in order to identify its associated gene
and to hyperlink to annotated clone reports within NCBI database. Or,
all the genes outside of the outlier lines can be simultaneously
selected by clicking on a button.

## Hierarchical cluster analysis tools

For a given dataset, hierarchical clustering can occur in two
directions: either the genes can be clustered by comparing their
expression profiles across the set of samples, or the samples can be
clustered by comparing their expression profiles across the set of
genes. In BRB-ArrayTools, the data can be clustered in either one or
both directions independently. The objects to be clustered may be either
the genes or the samples.

Hierarchical clustering produces a sequentially nested merging of the
genes (or samples) determined by a defined measure of pair-wise
similarity or distance between expression profiles. The nested merging
is represented by a "dendrogram". At the lowest level of the dendrogram,
each gene (or sample) is a member of an individual singleton cluster. At
the first step, the genes (or samples) with the two expression profiles
most similar to each other are merged into a cluster. Then the next two
most similar genes (or samples) are joined as a cluster. At each step,
the most similar two clusters (including singleton clusters) are joined
to form a larger cluster. This might actually involve the joining of two
singleton genes (or samples), merging a gene (or sample) into an
existing cluster, or merging two clusters formed at a previous step. The
"distance" between two clusters which merge into a single cluster can be
read from the scale along side of the dendrogram. Clusters which are
merged low on the dendrogram are similar, whereas clusters which are
formed by mergers high on the dendrogram may be very heterogeneous. At
the top level of the dendrogram, there is a single cluster containing
all of the genes (or samples). At the lowest level of the dendrogram the
"clusters" are very homogeneous because they consist of singleton genes
(or samples).

Several options are available for the clustering procedure. The first is
whether to use the average linkage, complete linkage or single linkage
version of the hierarchical clustering algorithm. The distance metric
used defines the distance between the expression profiles of two
samples. During hierarchical clustering, however, the algorithm must
compute the distance between clusters formed at a previous step, or
between a singleton and a previously created cluster. With average
linkage clustering, the distance between two clusters is taken as the
average of the distances between all pairs of elements, one from the
first cluster and one from the second. With complete linkage clustering,
the distance between two clusters is taken as the maximum distances
between an element in the first cluster and an element in the second.
With single linkage clustering, the distance between two clusters is
taken as the minimum of these distances. Complete linkage clusters tend
to be compact, with all members of a cluster relatively equally distant
from each other. The results of complete linkage clusters, however, may
be heavily dependent upon the elements which were used to start the
clusters. Single linkage clusters tend to be "long and narrow" in
multi-dimensional space, containing members very distant from each other
but closer to some intermediate member. Average linkage clustering is
most commonly used because it provides a compromise between the
advantages and disadvantages of the other types.

The distance metric itself is also an option. A Pearson correlation
between two arrays X and Y is defined as

Σ~*i=*1\ to\ N~ (X*~i~*-X*~avg~*)(Y*~i~*-Y*~avg~*) / \[ (Σ~*i=*1\ to\ N~
(X*~i~*-X*~avg~*)^2^) (Σ~*i=*1\ to\ N~ (Y*~i~*-Y*~avg~*)^2^) \],

where the summation index *i* runs through the N genes in the two
arrays, and X*~avg~* is the mean over all the genes in array X, and
Y*~avg~* is the mean over all the genes in array Y. (The formula is the
same for the Pearson correlation between two genes X and Y, except that
the summation index *i* would run through the M arrays in the dataset.)
Pearson correlation is a commonly used measure of similarity of two
columns of numbers, and hence one minus Pearson correlation serves as a
distance metric. The two columns used in computing correlation contain
the normalized log-ratios or normalized log-intensities of the genes for
the two samples being compared. When the entire set of genes is not used
for clustering samples, it may be appropriate to use the "uncentered
correlation" metric. The uncentered correlation between two arrays X and
Y is defined as

Σ~*i=*1\ to\ N~ X*~i~*Y*~i~* / \[ (Σ~*i=*1\ to\ N~ X*~i~*^2^)
(Σ~*i=*1\ to\ N~ Y*~i~*^2^) \],

where the summation index *i* runs through the N genes in the two
arrays. If the complete set of genes is used and the arrays have been
normalized, then the centered correlation between any two arrays is very
similar to the uncentered correlation between those two arrays, because
the means of the two normalized data columns are very similar. Euclidean
distance is a somewhat different metric. The Euclidean distance between
two columns is equivalent to the root-mean-square error between the two
columns; it is the square root of the sum of squared differences between
the expression levels. The expression profiles of two samples have a
large correlation if genes that are highly expressed relative to the
mean in one are also highly expressed relative to the mean in the other.
The correlation depends on the patterns of which genes are above and
below the mean expression in each profile. Euclidean distance measures
absolute differences between expression levels of individual genes
rather than on patterns of whether similar genes are up or down
regulated relative to each other. The Euclidean distance between two
expression profiles is small only if the absolute expression levels of
the genes in the two profiles are very similar. The correlation metric
is most commonly used, but it may be worthwhile to examine clustering
also with regard to Euclidean distance.

The tool for hierarchical clustering of genes can be used for perform a
cluster analysis of the genes alone, or a cluster analysis of both the
genes and the samples, where the output includes an image plot of the
log-ratio values where the genes and the samples are sorted according to
their dendrogram order.

When performing a cluster analysis of genes or samples, BRB-ArrayTools
will create a **Cluster viewer** worksheet in the collated project
workbook, which will display the dendrogram plot. To continue viewing
the sequence of plots, click on the **Next** button at the top of the
page. Clicking on the **Next** button may also bring up a prompt for the
user to define discrete clusters from the dendrogram by "cutting" the
tree, if the analyses selected by the users require the definition of
distinct clusters. All plots which are shown in the **Cluster viewer**
are also automatically saved as JPEG files in the Output folder of the
project folder, and may be subsequently edited using other commercially
available graphics software.

### Cluster analysis of genes

The cluster analysis of genes will produce a dendrogram plot. After the
user has "cut" the dendrogram tree, the following plots will be
produced: an image plot of all the genes (a matrix of colors
representing the over- or under-expression of each gene in each sample,
where the rows in the image plot represent the genes, and the columns in
the image plot represent the samples), a "median" image plot (similar to
the previous plot, but where a row represents a cluster rather than a
gene), and "profile" lineplots for each cluster (where the median
log-ratio of that cluster in each array is plotted).

In the image plot of all the genes, the genes are sorted in
dendrogram-order, so that genes which are next to each other when
reading across the bottom of the dendrogram are also next to each other
in the image plot. For all three plots, the user has the option to order
the samples in the image plot based on a cluster analysis of the samples
whose dendrogram-order will determine the plotting order of the samples,
or based on a pre-defined experiment descriptor variable whose order
will determine the plotting order of the samples. If a cluster analysis
of the samples is chosen, then the user has the option to center the
genes or not (see discussion under the next section "Options for cluster
analysis of samples"). If the plotting order of the samples is based on
a cluster analysis, then the user has the option of re-ordering the
samples in each "profile" lineplot using a cluster analysis based only
on the genes in that cluster.

Some other options include specifying the labeling of the samples, the
ability to suppress printing of clusters which contain too few genes,
and the color scheme (red/green or orange/blue) and color range of the
image plots.

The genes composing each cluster are listed in the **Cluster listing**
worksheet of the collated project workbook. The genes in each cluster
can also be identified from **the Cluster viewer** worksheet by clicking
on **List Genes**.

###  

### Cluster analysis of samples

Clustering samples is frequently performed using the entire set of genes
which pass the established filter levels. In certain cases, the user may
wish to use a special gene set for clustering and that is an option.
There is an option for whether the genes should be median centered in
computing the distance between pairs of samples. In most cases with cDNA
arrays it is advisable to use the median gene centering option because
it reduces the influence of the expression profile of the internal
reference sample, which is often not itself of interest.

Another option in the cluster analysis of samples is the ability to
compute reproducibility measures. Cluster analysis algorithms always
produce clusters, but the clusters are not always reproducible or
biologically meaningful. With gene clustering this is less of a problem
because we know in advance that gene products are grouped into pathways.
It may be a question whether genes in the same cluster are co-regulated,
but the existence of biologically meaningful gene clusters is usually
not open to question. This is not the case with clusters of samples
based on disease tissue from different patients, however. The claim that
there are "real" clusters in many cases represents the substantial claim
that the disease is molecularly heterogeneous. Such a claim requires
more evidence than the fact that the clustering algorithm produced
clusters.

Probably the best evidence for reproducibility of clusters of samples is
to demonstrate that the clusters that patients tissues are placed in
remain the same when the analysis is repeated using RNA independently
extracted from each of the same samples. In many cases, however, two
arrays based on independently extracted RNA samples for each sample is
not available. BRB-ArrayTools provides some alternative, though less
compelling, measures of the reproducibility of the sample clusters.

The user may select the cluster reproducibility analysis in the dialog
box for clustering samples. The reproducibility analysis is based on
perturbing the normalized log-ratios (or normalized log intensities for
single label oligonucleotide data) and re-clustering the perturbed data.
Indices are computed for each cluster in the original data indicating
how much the membership of the cluster changed based on the
perturbation. The perturbation and re-clustering process is repeated
many times (the number of repetitions is defined by the user) and the
output is a summary over the replications of the indices of
reproducibility for each cluster. The indices are not computed for all
clusters in the dendrogram, but rather for all clusters defined by
cutting the original dendrogram at a level defined by the user. A
similar level is used for re-clustering the perturbed data in each
replication.

Two reproducibility indices are reported. One is called the
Reproducibility or R measure for each cluster. The R measure is based on
pairs of samples in a cluster of the data. For each such pair of
samples, the program computes the proportion of the replications that
those two samples remain in the same cluster. That proportion, averaged
over replications and over all pairs of samples in the same cluster, is
the R measure for that cluster. An R of 1 means perfect reproducibility
of that cluster. An R of 0 means no reproducibility of the cluster.

The other index used is the Discrepancy or D measure. Each cluster of
the original data has a "target" cluster in a repetition of the
perturbed data. The "target" cluster is that cluster of the perturbed
data which contains the largest number of samples included in the
original cluster. The program computes the number of discrepancies as
the number of samples in the target cluster but not in the original
cluster plus the number of samples in the original cluster but not in
the target cluster. This number of discrepancies is computed for each
original cluster and averaged over the repetitions.

The data is perturbed using Gaussian random noise. The user can specify
the variance of the noise if he/she has independent data on the
variation over arrays of measurements of independent labelings and
hybridization of the same RNA sample. If the user does not specify a
value of the variance to be used, the program computes the variance of
normalized log-ratios (or normalized log intensities) across all of the
arrays for each gene and uses the median variance for the generation of
Gaussian perturbations. This estimation is reasonable as long as most
genes are not differentially expressed across the arrays. The variance
measure used may include some component of biological variation, rather
than just experimental variation. The inclusion of biological
variability is desirable, although true biological variability would be
correlated among sets of genes and the perturbations simulated by the
program are generated independently for each gene.

For more information about the cluster reproducibility analysis, see the
paper "Methods of assessing reproducibility of clustering patterns
observed in analyses of microarray data" by LM McShane, MD Radmacher, B
Freidlin, R Yu, MC Li and R Simon in Bioinformatics 18:1462-1469, 2002
also available as a technical report at
<http://linus.nci.nih.gov/~brb/TechReport.htm>

## Multidimensional scaling of samples

Multi-dimensional scaling is a group of methods for representing
high-dimensional data graphically in low (usually 2 or 3) dimensions.
The objective in multi-dimensional scaling is to preserve the pair-wise
similarities or distances between objects in the low-dimensional
graphical representation. BRB-ArrayTools provides multi-dimensional
scaling analysis of the expression profiles of the samples. We provide a
3-dimensional representation displayed as a rotating cloud of spheres in
which each sphere represents a single sample. Samples whose expression
profiles are very similar are shown close together. The options for
selecting gene sets, and similarity or distance metrics for the
multi-dimensional scaling analysis are the same as for the clustering
samples tool. In general, the user will use the same selections in both
analyses. When Euclidean distance is used as the metric, the
multi-dimensional scaling analysis is equivalent to what has been called
a principal component analysis. In that case, BRB-ArrayTools utilizes
the first three principal components as the axes for the
multi-dimensional scaling representation. The principal components are
orthogonal linear combinations of the genes. That is, they represent
independent perpendicular dimensions which are rotations of the gene
axes (if the thousands of gene axes could be represented). The first
principal component is the linear combination of the genes with the
largest variance over the samples of all such linear combinations. The
second principal component is the linear combination of the genes which
is orthogonal (perpendicular) to the first and has the largest variance
over the samples of all such orthogonal linear combinations; etc. The
first three principal components are usually good choices for
multi-dimensional scaling representation, though they are not
necessarily the best choice for observing clustered structure.
Multi-dimensional scaling analysis is similar to cluster analysis in
that one is attempting to examine the relations among samples. But
multi-dimensional scaling provides a graphical representation of the
pair-wise similarities or distances among samples without forcing the
samples into specific clusters.

Options on the multi-dimensional scaling dialog box provide the user
control of the labeling of samples in the graphical display.

The 3-D rotating plot contains controls for controlling the axis and
speed of rotation. The user may also stop the rotation and use his/her
mouse (holding the button down) to brush some of the points to obtain
identification of the samples represented by those points.

The multi-dimensional scaling dialog box also provides an option for
computing a global statistical significance test of whether the
expression profiles are clustered. This global test of clustering is
based upon the first three components obtained from a multi-dimensional
scaling of the samples. The statistical significance test is based on a
null hypothesis that the expression profiles come from the same
multivariate Gaussian (normal) distribution. A multivariate Gaussian
distribution is a unimodal distribution that represents a single
cluster. The global test of clustering can be computed only when the
user has at least 30 arrays in his or her dataset. More information
about the global tests of clustering is available in "Methods of
assessing reproducibility of clustering patterns observed in analyses of
microarray data" by LM McShane, MD Radmacher, B Freidlin, R Yu, MC Li
and R Simon, Journal of Computational Biology 9:505-511, 2002 and also
available as a technical report at
<http://linus.nci.nih.gov/~brb/TechReport.htm>

## Classification tools

It is frequently of interest to determine whether samples of different
phenotypes or samples collected under different conditions differ with
regard to expression profile. For example, one class of samples may
consist of breast tumors that contain BRCA1 mutations and the other
class may consist of breast tumors that do not contain such mutations (I
Hedenfalk, et al., Gene expression profiles of hereditary breast cancer,
New England Journal of Medicine 344:549, 2001). Another example is
comparing tumors that respond to therapy to those that do not. There are
numerous microarray studies that have objectives of this type. This type
of problem has been called "class prediction" in distinction to "class
discovery" because the classes, or phenotypes, of the samples to be
compared are known in advance of the expression profiling.

Cluster analysis is not usually the most effective tool for addressing
class prediction problems. Clustering of samples is usually based on the
entire set of genes represented on the array. Since the classes to be
distinguished may differ only with regard to a relatively small subset
of these genes, these differences may be dominated by variations among
the thousands of other genes used in the clustering distance metric.
Whereas perusal of the image plot associated with clustering the samples
and the genes may reveal some genes that appear to distinguish the
classes, the visual approach is error prone without statistical
confirmation that the clusters observed do not represent patterns
obtained by chance from screening thousands of genes for those that sort
the samples.

BRB-ArrayTools contains two powerful tools for comparing expression
profiles among pre-defined classes. They are found under the
Classification menu item. Both tools presume that the data consists of
arrays of different samples representative of the two classes. The
arrays should represent replication at the highest level, incorporating
biological variability. That is, if we are comparing expression profiles
of BRCA1 mutated breast tumors to non-BRCA1 mutated breast tumors, we
need samples from breast tumors of different patients in both
categories. It is not sufficient to compare replicate arrays of one RNA
sample from a BRCA1 mutated tumor to one RNA sample from a non-BRCA1
mutated breast tumor. Comparing two RNA samples, regardless of how many
arrays have been run with those two samples, cannot support conclusions
about the influence of BRCA1 mutation on expression profiles. If cDNA
arrays are used, the two class prediction analyses in BRB-ArrayTools
assume that a common internal reference sample has been used in all
arrays, or that a patient specific normal tissue reference is used for
the arrays.

### Class comparison

The Class Comparison tool is used for comparing 2 or more pre-defined
classes. The classes to be compared are defined by a column of the
experiment design worksheet. The codes used in a column can be any set
of numerical, character or character string codes. If an entry for a
particular array is left blank in defining the column, that array will
be omitted from the class prediction analysis. The ability of the user
to define columns in the experiment design worksheet to specify class
prediction analyses enables the user to import his/her complete set of
arrays into BRB-ArrayTools once and to conduct a variety of different
comparisons guided by different columns.

The F-test is a generalization of the two-sample t-test for comparing
values among groups. The Class Comparison Tool computes an F-test
separately for each gene using the normalized log-ratios for cDNA arrays
and the normalized log-intensities for one color oligonucleotide arrays.
The tool computes the number of genes which are differentially expressed
among the classes at the statistical significance level selected in the
F-test menu and creates a gene list containing information about the
significant genes. Several other important statistics are also computed.
The tool performs random permutations of the class labels (i.e. which
arrays correspond to which classes). Based on these random permutations,
the tool computes the "permutation p value" associated with each gene in
the list. The permutation p value is a better indicator of the
statistical significance of the gene because it does not depend on the
normal distribution assumption inherent in the F-test.

The Class Comparison Tool also computes the proportion of the random
permutations that gave as many genes significant at the level selected
by the user as were found in comparing the true class labels. That p
value provides a global test of whether the expression profiles in the
classes are different. This test is also robust; although it uses the
number of genes significant by the F-test as a statistic, it generates
the permutation p-value of that statistic. In comparing classes, it is
statistically easier to determine reliably whether expression profiles
for pre-defined classes are different than to reliably determine exactly
which genes are differentially expressed among the classes. The latter
problem more directly confronts the multiple comparison problem.

For example, suppose that we select a significance level of 0.001 for
including genes in the gene list. If there are 8000 genes on the array,
then we expect by chance that 8 genes on the gene list will be false
positives. If we obtain 24 genes on the gene list, then about one third
of them are false positives. If we obtain 80 genes on the gene list,
then about one tenth of them are false positives. Traditionally multiple
comparison corrections used in statistical analyses are much more
stringent, usually requiring that the chance of any false positives be
very small. For most microarray analyses, such conservatism is not
appropriate. However, gene lists will not be a useful basis for further
experimentation if they are heavily populated by false positives. For
example, if we select a significance level of 0.01 instead of 0.001,
then we expect by chance that 80 genes on the gene list will be false
positives. Having 80 false positives makes interpretation or planning
confirmatory experiments very problematic. So using a relatively
stringent 0.001 is usually appropriate. With that stringency, however,
there may be a substantial chance of false negatives; that is some genes
that are differentially expressed among the classes will not be found
significant at the 0.001 level. The false negative rate will depend on
the sample size, the within class variation among samples and the
average fold difference between classes for the gene. Hence although the
statistical power for detecting individual genes is limited by the
stringency needed to control the false positive rate, the global test of
whether the classes differ with regard to expression profiles will have
better power for establishing that the expression profiles are
different. Because a single global test is performed, obtaining a p
value of less than 0.05 is sufficient to establish that the expression
profiles are different. Multiple comparison stringency needed for
inferences about individual genes is not needed for the global test.

*Randomized Variance Model*

The class comparison tool in BRB-ArrayTools 3.0 has been enhanced in two
important ways. The first way is that the *randomized variance* t and F
tests can be selected as alternatives to the standard t/F tests. The
standard t/F tests are based on the assumption that the within class
variance is different for different genes and hence these variances are
estimated separately for each gene. When there are few samples in each
class, the variance estimates are not very accurate and the statistical
power of t/F tests are poor. Some published methods assume that the
variances are the same for all genes, and that is clearly a poor
assumption. The randomized variance model takes an intermediate
approach. It assumes that different genes have different variances, but
that these variances can be regarded statistically as independent
samples from the same distribution. Specifically, the reciprocal of the
variances are regarded as draws from a gamma distribution with two
parameters (a,b). The parameters are estimated from the complete set of
expression data and we first test that the model is accurate. In most
datasets we have examined, the model assumption is very accurate. The
usual t test for comparing expression of gene i in two classes is based
on the statistic

![](media/image17.wmf)

where the numerator is the difference in the means of log expression for
gene i in the two classes, n~1~ and n~2~ are the number of samples in
the two classes, and ![](media/image18.wmf) denotes the square root of
the usual within class variance for gene i. The within class variance is
computed by a weighted average of the variance of log expression in each
of the two classes. With the usual t test, under the null hypothesis,
the t value has a t distribution with n~1~+n~2~-2 degrees of freedom.
For the randomized variance model, the same formula for t is used,
except that ![](media/image19.wmf) is replaced in the denominator by
![](media/image20.wmf) where

![](media/image21.wmf)

The quantity 1/ab is an estimate of the expected variance for the
inverse gamma model. Consequently, ![](media/image22.wmf) is a weighted
average of the usual gene specific variance and the average variance for
all the genes. The weight given to the gene specific variance is the
total number of samples in the two classes minus two. The weight given
to the average variance for all the genes is 2a. It can be shown
rigorously that when the model assumption holds, that the t values
computed using ![](media/image23.wmf) have a t distribution under the
null hypothesis but the degrees of freedom is now n-2+2a. In cases where
the number of samples n is small, this increase in degrees of freedom
and the associated improvement in the estimation of variances results in
improved statistical power for detecting differentially expressed genes.
These results extend directly to the F distribution for comparing more
than two classes.For details, see G Wright and R Simon, The randomized
variance model for finding differentially expressed genes, Technical
Reprort xx, Biometric Research Branch, National Cancer Institute,
<http://linus.nci.nih.gov/~brb> ; P Baldi and AD Long, A Bayesian
framework for the analysis of microarray expression data: regularized
t-test and statistical inferences of gene changes, Bioinformatics
17:509-519, 2001.

*Multivariate Permutation Tests for Controlling Number and Proportion of
False Discoveries*

Using a stringent p\<0.001 threshold for identifying differentially
expressed genes is a valid way for controlling the number of *false
discoveries*. A false discovery is a gene which is declared
differentially expressed among the classes, when in fact it is not.
There are two problems with this approach to controlling the number of
false discoveries. One is that it is based on p values computed from the
parametric t/F tests or randomized variance t/F tests. These parametric
p values may not be accurate in the extreme tails of the normal
distribution for small numbers of samples. The second problem is that
this approach does not take into account the correlation among the
genes. Using stringent p value thresholds on the univariate permutation
p values won't be effective when there are few samples and will not
account for correlations. We have implemented multivariate permutation
tests that accomplish both objectives. They are described in detail in
EL Korn, JF Troendle, LM McShane and R Simon, Controlling the number of
false discoveries: Application to high dimensional genomic data;
Technical Report 3, Biometric Research Branch, National Cancer
Institute, 2002; <http://linus.nci.nih.gov/~brb>

The multivariate permutation tests are based on permutations of the
labels of which arrays are in which classes. A large number of random
permutations are considered. For each random permutation, the parametric
tests are re-computed to determine a p value for each gene that is a
measure of the extent it appears differentially expressed between the
random classes determined by the random permutation. The genes are
ordered by their p values computed for the random permutation (genes
with smallest p values at the top of the list). For each potential p
value threshold, the program records the number of genes in the list.
This process is repeated for a large number of random permutations.
Consequently, for any p value threshold, we can compute the distribution
of the number of genes that would have p values smaller than that
threshold for random permutations. That is the distribution of the
number of false discoveries, since genes that are significant for random
permutations are false discoveries. The algorithm selects a threshold p
value so that the number of false discoveries is no greater than that
specified by the user 95% of the time or 50% of the time. In a similar
manner, we determine threshold p values so that the resulting gene list
contains no more than a specified proportion of false discoveries
(either 95% of the time or 50% of the time).

The class prediction tool produces a gene list ordered with the genes
having the smallest parametric p values at the top. The length of the
gene list is determined by the types of false discovery control
selected. Generally we recommend using all of the options: univariate p
value threshold (0.001); limiting number of false discoveries (10
default), and limiting proportion of false discoveries (0.10 default).
The output tells you where to truncate the gene list in order to get
each type of control.

The procedures for controlling the number or proportion of false
discoveries are based on multivariate permutation tests. Although
parametric p values are used in the procedures, s the permutation
distribution of these p values is determined and hence the false
discovery control is non-parametric and does not depend on normal
distribution assumptions.

The multivariate permutation tests use the expression data much more
efficiently than the univariate permutation tests. Consequently, we no
longer recommend using the univariate permutation tests. We have
retained the option to do the univariate permutation tests, but we have
made the default to skip them. The multivariate permutation tests are
particularly more effective when the number of samples is limited. In
that case it may be impossible to obtain differences significant at the
0.001 level by a univariate permutation test, but quite possible to find
significant genes while ensure that the number or proportion of false
discoveries is controlled using the multivariate permutation tests.

The multivariate permutation tests take advantage of the correlation
among the genes. For a given p value for truncating an ordered gene
list; the *expected number* of false discoveries does not depend on the
correlations among the genes, but the *median* number of false
discoveries does. The distribution of number of false discoveries is
skewed for highly correlated data. That is why we provide the length of
the gene list associated with a specified median number of false
discoveries or given proportion of false discoveries. You may think of
those gene lists as being expected to contain the target number or
proportion of false discoveries, although the median and expected number
are not exactly the same. Requiring 95% confidence that the gene list
does not contain more false discoveries than the target amount is a much
more stringent condition and the associated gene lists will be much
shorter than those based on the median. For many screening purposes, the
lists based on a targeted median number or proportion of false
discoveries will be adequate.

Two options presented for the Class Comparison Tool are important for
some situations. If two classes are compared and the arrays are paired,
then the paired t-test option should be selected. For example, if arrays
have been prepared for the primary tumor and metastatic tumors of each
patient, then the paired t-test option is appropriate and may improve
the statistical power of the analysis.

If multiple arrays have been performed for some RNA samples, then the
analysis must either be based on selection of a single array for each
RNA sample or the averaging option should be used. The F-test is based
on comparing the differences in mean log-ratios (or log-intensities)
between classes relative to the variation expected in the mean
differences. The variation is computed assuming that all the samples are
independent. If there are multiple arrays for the sample RNA sample,
then the within class variation will under-estimate the inter-class
variation in means to be expected. The user should either omit
technically inferior arrays, arbitrarily choose between technically
satisfactory arrays that are tightly correlated (as determined using the
Scatterplot tool), or utilize the averaging option. A combination of
these approaches may also be used. If the averaging option is selected,
the user must specify a column of the experiment design worksheet that
provides RNA sample identifiers so that the tool can identify when there
are multiple arrays for the same RNA sample. When analyzing paired
sample, samples with replicated pairing id and classification labels
will automatically be averaged.

The HTML output file created by the Class Comparison Tool gives the
parametric p-value, the univariate permutation p-value (if requested),
and the geometric mean ratio (geometric mean intensity for single color
oligonucleotide arrays) in each class, and gene identifying information.
The list is sorted by parametric significance level. If there are two
classes, the list is in two parts; those genes down-regulated in class
one relative to class two followed by those genes up-regulated in class
one relative to class two. When there are more than two classes, the
patterns of differential expression among the classes will be more
varied for genes in the list. The Class Comparison Tool saves this gene
list in the ..\\ArrayTools\\Genelists\\User folder using the genelist
name specified by the user. It is often useful to cluster the samples
with regard to this gene list in order to better understand the pattern
of genes across samples.

### Class Prediction

The Class Prediction Tool is similar to the Class Comparison Tool in
that it provides information about the genes that are differentially
expressed among two pre-defined classes. The user specifies the classes
by identifying a column of the experiment description worksheet. For the
Class Prediction Tool, the column must only define two classes. Blanks
labels in the column indicate that the corresponding array should be
omitted from the analysis. Replicate arrays of the same RNA sample may
be averaged, by entering a sample id column in the experiment design
worksheet. When analyzing paired sample, samples with replicated pairing
id and classification labels will automatically be averaged.

The user specifies a significance level to be used for determining the
genes that will be included in the predictors; genes which are
differentially expressed between the classes at a univariate parametric
significance level less than the specified threshold are included in the
predictor. It doesn't matter whether the specified significance level is
small enough to exclude enough false discoveries, because class
prediction is not really about discovering differentially expressed
genes. In some problems better prediction can be achieved by being more
liberal about the gene set used as features. The predictors may be more
biologically interpretable and clinically applicable, however, if fewer
genes are included.

The Class Prediction Tool creates a multivariate predictor for
determining which of the two classes a given sample belongs. Several
multivariate classification methods are available. One of these is
called the Compound Covariate Predictor. It is a weighted linear
combination of log-ratios (or log intensities for single-channel arrays)
for genes that are univariately significant at the specified level. By
specifying a more stringent significance level, fewer genes are included
in the multivariate predictor. Genes in which larger values of the
log-ratio pre-dispose to class 2 rather than class 1 have weights of one
sign, whereas genes in which larger values of the log-ratios pre-dispose
to class 1 rather than class 2 have weights of the opposite sign. The
univariate t-statistics for comparing the classes are used as the
weights. Detailed information about the Compound Covariate Predictor is
available in the Hedenfalk reference given above or in "A paradigm for
class prediction using gene expression profiles" by MD Radmacher, LM
McShane and R Simon, A paradigm for class prediction using gene
expression profiles. Journal of Computational Biology 9:505-511, 2002.,
also available in Technical Report 01, 2001, Biometric Research Branch,
National Cancer Institute,
[http://linus.nci.nih.gov/\~brb/TechReport.htm](http://linus.nci.nih.gov/)).

In addition to the compound covariate predictor, several other
prediction methods are available. Diagonal linear discriminant analysis
is similar to the Compound Covariate Predictor, but not identical. It is
a version of linear discriminant analysis that ignores correlations
among the genes in order to avoid over-fitting the data. Many complex
methods have too many parameters for the amount of data available.
Consequently the appear to fit the training data used to estimate the
parameters of the model, but they have poor prediction performance for
independent data. The study by Dudoit et al. (S Dudoit, J Fridlyand, TP
Speed; Comparison of discrimination methods for the classification of
tumors using gene expression data, Journal of the American Statistical
Association 97:77-87, 2002) found that diagonal linear discriminant
analysis performed as well as much more complicated methods on a range
of microarray data seta.

The *Nearest Neighbor* predictor is based on determining which
expression profile in the training set is most similar to the expression
profile of the specimen whose class is to be predicted. The expression
profile is a vector of log-ratios or log-intensities for the genes
selected for inclusion in the multivariate predictor. Euclidean distance
is used as the distance metric for the *Nearest Neighbor* predictor.
Once the nearest neighbor in the training set of the test specimen is
determined, the class of that nearest neighbor is taken as the
prediction of the class of the test specimen. *k-Nearest Neighbor
Prediction* is similar. For example with the 3-Nearest Neighbor
algorithm, the expression profile of the test specimen is compared to
the expression profiles of all of the specimens in the training set and
the 3 specimens in the training set most similar to the expression
profile of the test specimen are determined. The distance metric is
again Euclidean distance with regard to the genes that are univariately
significantly differentially expressed between the two classes at the
threshold significance level specified. Once the 3 nearest specimens are
identified, their classes vote and the majority class among the 3 is the
class predicted for the test specimen.

The Class Prediction Tool also offers *Nearest Centroid Prediction*. In
the training set there are samples belonging to class 1 and to class 2.
The centroid of each class is determined. The centroid of class 1, for
example, is a vector containing the means of the log-ratios (or log
intensities for single label data) of the training samples in class 1.
There is a component of the centroid vector for each gene represented in
the multivariate predictor; that is, for each gene that is univariately
significantly differentially expressed between the two classes at the
threshold significance level specified. The distance of the expression
profile for the test sample to each of the two centroids is measured and
the test sample is predicted to belong to the class corresponding to the
nearest centroid.

The Class Prediction Tool also offers *Support Vector Machine
Prediction*. A support vector machine (SVM) is a class prediction
algorithm which has appeared effective in other contexts and is
currently of great interest to the machine learning community. SVMs were
developed by V. Vapnik (The Nature of Statistical Learning.
Springer-Verlag, New York, 1995). We have implemented SVMs with linear
kernel functions as our experience has been that more complex SVMs
perform less well for this application. The SVM predictor is a linear
function of the log-ratios or the log-intensities that best separates
the data subject to penalty costs on the number of specimens
misclassified. In the options dialog, the user can alter the default
penalty cost or the cost of misclassifying a specimen of class 1
relative to misclassifying a specimen of class 2. We use the LIBSVM
implementation of Chang and Lin.

For all of the class prediction methods requested, the Class Predictor
Tool provides an estimate of how accurately the classes can be predicted
by this multivariate class predictor. The cross-validated
misclassification rate is computed and the results are reported. The
cross-validation process omits one sample at a time. For each sample
omitted, the entire analysis is repeated from scratch, including the
determination of which genes are univariately significant on the reduced
training sample. From that gene list, a multivariate predictor is
constructed and applied to the sample that was omitted. The program
records whether that prediction was correct or not. This is repeated,
omitting all of the samples one at a time. The output table shows which
samples were correctly and incorrectly predicted, and the overall
cross-validated misclassification rate. The output table is arranged so
that you can see the extent to which the different predictors agree or
disagree for each specimen left out of the training set. Because of the
large number of candidate predictor variables, it is essential to use
cross-validation or some similar method to determine whether the model
predicts accurately. Even with classes that do not differ in expression
profiles, it is very easy to develop models that predict perfectly when
measured in a non cross-validated manner. Such models would be useless
for application with independent data.

In addition to providing the cross-validated misclassification
information, the Class Prediction Tool also provides the permutation p
value for the cross-validated misclassification error rate. That is, for
each random permutation of class labels, the entire cross-validation
procedure is repeated to determine the cross-validated misclassification
rate obtained from developing a multivariate predictor with two random
classes. The final p value is the proportion of the random permutations
that gave as small a cross-validated misclassification rate as was
obtained with the real class labels. There is a cross-validated
misclassification rate and a corresponding p value for each class
prediction method requested. The user inputs the number of permutations
desired. At least 1000 permutations should be specified for a valid
permutation p value on the cross-validated misclassification rate. The
user may specify only 1 permutation and will quickly obtain the
appropriate gene list and valid cross-validated misclassification rates.
Only the p values associated with the cross-validated misclassification
rates will be missing.

Note that the list of genes which are used to form the class predictors
will coincide with the list of genes produced by the Class Comparison
Tool for the same analysis between the two classes. The only exception
is when there is only one nonmissing value in one of the two classes, or
when the variance in one of the two classes is zero. In that case, the
compound covariate predictor imputes the p-value for that gene to be 1,
rendering that gene nonsignificant for that permutation or analysis,
whereas the Class Comparison Tool does not.

The Class Prediction Tool saves this gene list in the
..\\ArrayTools\\Genelists\\User folder using the genelist name specified
by the user.

#### Prediction for new samples

The class prediction tool can be used to classify samples not used in
the model building process. In the class prediction dialog, check the
box labeled "Use separate test set" . You should create a column in your
experiment descriptor worksheet that indicates which arrays contain
samples that are to be included in the model building process (labeled
"training"), which are to be used only for classification prediction
once the model building is completely finished (labeled "predict"), and
which samples are to be excluded entirely from both the training and
test sets (labeled "exclude"). Predictions will be made for the samples
labeled "predict" using all of the class prediction methods requested in
the dialog.

Ususally, you do not have a separate set of samples that you wish to
withhold from the model building process when the analysis is first
done. The model building process itself uses leave-one-out cross
validation, and so it is not necessary to have a separate test set.
Sometimes, however, after the model is built, you have additional
samples whose classes you wish to predict using the previously developed
model(s). We have enabled you to do this by re-building the model using
the initial set of samples, and to then predict for the new samples in a
combined analysis. This has been more direct for us to implement, rather
than trying to save the originally developed model, since in cases like
k-nearest neighbor classifiers, the entire dataset is needed for
classification of new samples.

### Survival analysis

The survival analysis tool finds genes that are predictive of survival
time for patients. Since some patients/animals may still be alive at the
time of analysis, their survival times from entry on study is
*censored*; that is, it is at least as long as survival measured to
date, but longer by an unknown amount. There are many statistical
methods for analysis of censored survival data. The most popular method
is Cox's proportional hazards model ( ). This is a regression model in
which the hazard function for an individual is a function of predictor
variables. In our case the predictor variables are log expression
levels. The hazard function is the instantateous force of mortality at
any time conditional on having survived till that time. The proportional
hazards model postulates that the logarithm of the hazard of death is a
linear function of the predictor variables, linked by unknown regression
coefficients. For more details see biostatistics texts or the original
paper (DR Cox, Regression models and life tables, J.Royal Stat Soc B
34:187-202).

The survival analysis tool fits proportional hazards models relating
survival to each gene, one gene at a time and computes the p value for
each gene for testing the hypothesis that survival time is independent
of the expression level for that gene. Gene lists are created based on
these p values in the same way as in the Class Comparison tool. The p
values can be used to identify gene lists using multivariate permutation
tests for controlling the number or proportion of false discoveries. Or
the gene list can simply consist of the genes with p values less than a
specified threshold (0.001 is default).

### Specifying replicate arrays and paired samples

To enter paired samples into an analysis, the user must create a
descriptor variable on the Experiment descriptors sheet in which a
unique value is given for each pair. The following example shows the
experiment design sheet for a paired analysis:

![](media/image24.png){width="4.3in" height="3.0909722222222222in"}

Here, the pre-treatment samples are to be compared against the
post-treatment samples for each patient. The pairing variable is
Patient_Id and the class variable to be compared is Treatment. Note that
both Array012 and Array013 contain post-treatment samples for
Patient006. In that case, the average of the two arrays will be used for
the analysis.

When an unpaired analysis is used, the user should make sure to specify
whenever there are replicate arrays which have been performed using the
same sample. The following example shows an experiment descriptor sheet
in which replicate arrays were performed for some of the samples:

![](media/image25.png){width="4.1in" height="3.0in"}

In this case, Sample_Id is the replicate variable to average over. Since
Array001 and Array002 have the same Sample_Id, their average will be
used for the analysis. Similarly, Array002 and Array003 will be averaged
for the analysis. All the other arrays will be used as-is, since they
have no replicates.

# 

# 

# Programmable Plug-In Faciltiy

BRB-ArrayTools has a plug-in facility that enables users or methodology
developers to extend the tool set built in to BRB-ArrayTools by
providing their own tools. Users can then easily add-in the new tools to
their version of BRB-ArrayTools and use them in the analysis of their
data. The extensions must be written as functions in the R statistical
programming language. R is an open source and very powerful statistical
language that is popular with academic statistical scientists. It is in
many ways a public domain version of S+, although each language has some
features missing in the other. There is a growing body of R functions
developed for the analysis of microarray data and the plug-in facility
can give BRB-ArrayTools users and R software developers access to each
other via BRB-ArrayTools.

Detailed information about the creation and use of add-in R functions is
described in the BRB-ArrayTools Plug In Guide. Here we will give an
overview of the plug-in facility. In considering R plug-ins there are
two perspectives, one for the R tool developer and one for the
BRB-ArrayTools user analyzing his/her data and wanting to utilize
plug-ins.

For the plug-in user, the process of installing and accessing a plug-in
is quite simple. The BRB-ArrayTools main menu contains a "Plug In" entry
and a "Load Plug In" sub-menu entry. The Load Plug In dialog box askes
for the path name of the plug in and it asks whether the user wants the
plug-in added to the plug-in menu for future use. When the user clicks
the "Load" button on the Load Plug In dialog box, the plug-in is
launched and it will prompt the user for any further information it
needs. BRB-ArrayTools will pass the R plug-in any data that it needs in
the user's Project Workbook that has already been collated by the user.
The output of the analysis performed by the plug-in will be directed to
a file and that file will be opened either by the plug-in itself or by
the user. The user only needs to know the name of the plug-in. In using
plug ins obtained from others, the user has to install the plug in in
the PlugIns folder of the BRB-ArrayTools directory. There is a .r
sub-folder for r functions, a .plug sub-folder for plug-in interfaces
created by developers, and a .txt sub-folder for readme files created by
developers.

The creation of R plug-ins for BRB-ArrayTools is also relatively easy.
The first step is to write the R function that performs the desired
analysis. This function will be launched by the BRB-ArrayTools user as
described above, and BRB-ArrayTools will pass to the R function the
information in the active collated workbook that the function needs. The
data will be passed via the COM (Common Object Module) architecture and
the developer need not read any files to obtain the desired data. In
writting the R function, the developer can name the available data
objects provided by BRB-ArrayTools any way he/she chooses. Because the R
function runs in the background as a COM object, output from the
function should be written to a file. The R function may open the file
before terminating or the user can open the file.

The second step in creating a plug-in is to create the interface between
the R function and BRB-ArrayTools. We provide a wizard to make this step
easy. The wizard enables the developer to tell BRB-ArrayTools what data
objects the R function needs and what names the R function wants
associated with those data objects. The wizard also enables the
developer to prompt the user for additional data input. The input dialog
will be in the format of the Micrososft Windows type of dialog boxes
used by BRB-ArrayTools but the VBA coding of these dialogs will be
automatically generated by BRB-ArrayTools using information provided by
the developer in his/her dialog with the wizard. For more information,
see the BRB-ArrayTools Plug In Guide.

# Hands-on practice using a sample dataset

In the BRB-ArrayTools installation folder, there is a sample dataset
called BreastSamples which is actually a subset of a dataset published
by Ross, et al.^1^, and contains data from thirteen microarrays. Nine
microarrays were performed on cell-line samples, and four microarrays
were performed on tissue samples. The nine microarrays included three
which were performed on the same cell-line sample (MCF7). Two cell-line
samples which were derived from the same patient (MDA-MB-435 and MDA-N).
The four tissue samples included a normal breast sample, as well as a
lymph node sample collected from one of the breast cancer patients
(BC2).

To begin using the sample dataset, unzip the BreastSamples.zip file, and
open a few of the files in Excel to examine their contents. Then begin
the hands-on tutorial by following the instructions for Example 3 under
the \"Collating the data\" chapter of this manual. For the examples in
this tutorial, we used the default filtering criteria, and also set the
maximum number of missing values to 3.

  -----------------------------------------------------------------------
  Note

  The analyses in this tutorial are chosen to illustrate the
  functionality of BRB-ArrayTools, and should not be considered a
  prescription for how the user\'s own data should be analyzed.
  -----------------------------------------------------------------------

In this particular dataset, we might be interested in comparing
cell-lines versus tissue samples, for example. One qualitative way to
see if there is much difference between these two classes of samples is
to use the scatterplot of phenotype averages. To run this analysis,
click on **Scatterplot  Averaged over phenotype classes**, and select
Cell-type as the phenotype class to average over.

The following plot will be produced on a **Scatterplot** worksheet in
the collated project workbook. Clicking on **Select All Outliers** will
highlight all the genes which have greater than a four-fold difference
between the average log-ratio over the cell-line samples and the average
log-ratio over the tissue samples, and list these genes in the panel
beside the plot, with hyperlinks to clone reports.

Example of scatterplot of phenotype averages:

![](media/image26.png){width="4.65in" height="3.3333333333333335in"}

Since there seem to be lots of genes which are differentially expressed
between cell-line and tissue samples, we might be interested in using
the Class Comparison tool to find a geneset which discriminates between
the two cell-types. To use the Class Comparison tool, we first have to
add a column in the experiment descriptor sheet indicating that some of
the arrays were \"replicates\". In the SampleId column, three arrays
were given the same label, since they were all performed using the same
cell-line MCF7. Another pair of arrays, MDA-MB-435 and MDA-N, were also
given the same label, since they were performed using cell-lines which
were derived from the same patient. One array, BC2_Lymph_Node, was not
given a label since it is not a breast sample, and will be excluded from
the analysis.

![](media/image27.png){width="3.9in" height="2.579861111111111in"}

To run the analysis, click on **Classification  Class Comparison**, and
select Type as the phenotype class variable. Select the checkbox for
averaging replicate arrays over the SampleId descriptor variable. For
this analysis, you should use all available genes, so you should click
on the **Filter** button in the **Class Comparison** dialog box, and
deselect the **Log-ratio Variation Filter** on the **Gene Filters**
page. Now click **OK** for this analysis. You will see a DOS window
minimized at the bottom of your screen, where a script is running to
compute the class comparison output. The script will take a few minutes
to run. When the script is finished running, an HTML page will open up
similar to the following output:

![](media/image28.png){width="5.4in" height="4.283333333333333in"}

There were 164 genes identified as significantly different between the
two classes with an F-test p-value of 0.001. In 2000 random permutations
of the class labels, the chance of finding 164 or more significant genes
was only 0.0105. This is the p-value for the global test of whether or
not the two classes differ with regard to the expression profile. In the
table, the F-test p-value and the permutation p-value are given for each
gene for which the F-test p-value was less than 0.001.

The genelist in the HTML table is automatically saved using the genelist
name specified by the user.

Now if we run a cluster analysis of samples using only this set of 164
genes, we will see that the samples form two very tight tissue and
cell-line clusters which are highly reproducible. Here we did not center
the genes, and we used an uncentered correlation with average linkage.
We selected the arrays using the SampleId descriptor variable, so that
the BC2_Lymph_Node sample was not included in the analysis. The average
correlation with each cluster is fairly tight (around 0.8).

![](media/image29.png){width="4.15in" height="2.975in"}

![](media/image30.png){width="4.15in" height="2.859027777777778in"}

If we had run a cluster analysis of samples using the entire geneset, we
would not have seen two clear clusters, due to the heterogeneity in the
cell-lines. The genes which are not differentially expressed between the
two cell types would have dominated the distance computation so that the
effect of the differences between the two cell types would have been
masked.

We can run the multidimensional scaling tool to visualize the
relationships between these samples, based on the 164 genes which were
significant from the Class Comparison tool.

![](media/image31.png){width="4.766666666666667in"
height="3.563888888888889in"}

The three-dimensional scatterplot may be rotated by clicking on the
**x**, **y** and **z** buttons, and individual points may be identified
by brushing over the points.

Because the global test of clustering can only be run on datasets with
at least 30 samples, the global test of clustering was not run on this
particular dataset.

If we run a hierarchical clustering of the genes, we see from the
dendrogram that there are two clear gene clusters with fairly tight
average correlations (around 0.7).

![](media/image32.png){width="4.25in" height="3.046527777777778in"}

The color image plot gives a graphical depiction of two gene clusters:

![](media/image33.png){width="4.2in" height="3.011111111111111in"}

If we scroll down the image plot, we would see that Cluster #1 is mostly
underexpressed in the tissue samples, while Cluster #2 is mostly
overexpressed in the tissue samples. The differences between the two
clusters is not as dramatic in the cell-line samples.

The image plot of cluster medians illustrates this even more clearly:

![](media/image34.png){width="4.25in" height="3.046527777777778in"}

A "profile" lineplot is also produced for each cluster:

![](media/image35.png){width="4.25in" height="3.046527777777778in"}

# Further help

## Some useful tips

### Excluding arrays from an analysis

Some of the analyses within BRB-ArrayTools can be run on a subset of the
arrays in the collated project workbook. For the hierarchical clustering
and multidimensional scaling tools, an array will be excluded from the
analysis if it has a blank label within the designated experiment
descriptor variable. For the scatterplot of phenotype averages and the
classification tools, an array will be excluded from the analysis if it
has a blank label within the selected phenotype class variable.

### Extracting genelists from HTML output

Sometimes the user may need to extract columns of data from the HTML
tables which are produced by BRB-ArrayTools. For example, the user might
wish to include the HTML genelist table produced by the classification
tools in a Word document for publication. Or the user might need to
extract the t-values and midpoint values from the compound covariate
predictor output for use in classifying new samples. Or the user might
wish to sort the genelist table by a particular column.

HTML tables can be easily converted to tables in Word or columns in
Excel. You can do this in one of two ways. One way is to select the HTML
table by left-clicking and dragging the mouse over the entire table, and
then copying to the buffer through **Edit  Copy** (or **Ctrl-V**). Then
open up a blank Word or Excel document, and paste the contents of the
buffer into the document through **Edit  Paste** (or **Ctrl-C**).

Another way is to open the HTML file within Word or Excel using the
**File  Open** menu. In the **Open** dialog box, go to the **Files of
type** field and select **HTML Document** (in Word or Excel 97) or
select either **All Microsoft Excel Files** or **Web Pages** (in Excel
2000). Now browse for the HTML document which you would like to convert.
Once the table has been converted to a Word table or to cells within
Excel, it is very easy to add to, delete, or edit any of the rows or
columns in the table. Note that all hyperlinks are preserved when
converting HTML tables to Word or Excel.

### Creating user-defined genelists

The best utility to use for creating user-defined genelists is Notepad.
This is because Notepad always saves files as ASCII text files, without
adding the hidden formats into the file which some word processors do.
To open Notepad, click on **Windows Start Button  Programs 
Accessories  Notepad**.

To save any list of genes from a column of cells within Excel, simply
select the cells by left-clicking and dragging your cursor over the
cells, and copying to the buffer through **Edit  Copy** (or
**Ctrl-V**). Then open up a blank text file in Notepad, and paste the
contents of the buffer into the text file through **Edit  Paste** (or
**Ctrl-C**). It is possible to save the list of selected genes from a
BRB-ArrayTools scatterplot in this way.

To save any list of genes from an HTML table, first convert to Word or
Excel, then copy the desired column of gene identifiers into a Notepad
document. Of course, the genelists from the Class Comparison or the
Compound Covariate Predictor tool are already automatically saved into
the ..\\ArrayTools\\Genelists\\User folder. However, the user may be
interested in saving the genes from an HTML table for purposes other
than to enable subset analyses within BRB-ArrayTools, since the HTML
tables report the genes in sorted order by p-value or another criterion.

### Re-playing the three-dimensional rotating scatterplot

Currently there is no tool for saving the rotating three-dimensional
scatterplot of the multidimensional scaling coordinates as a movie.
Future releases of BRB-ArrayTools may include a tool to create the
rotating scatterplot as an object within a PowerPoint presentation.
However, the current release only allows the user to save a screenshot
of the scatterplot or re-play the scatterplot from a DOS command.

To save a still-shot of the screen, simply press the **PrintScreen**
button on the keyboard, then go into any application which has image
editing capabilities, and paste the screenshot (usually by pressing the
**Ctrl-V** key combination).

To re-play the rotating three-dimensional scatterplot from a DOS
command, follow these instructions. (Note that the following steps can
also be used to show the three-dimensional rotating scatterplot with
larger point sizes.)

1)  Open an **MS-DOS** window (this can usually be found by going to the
    **Windows Start Button**).

2)  Find the folder which contains the java.exe file (usually this will
    be in the C:\\Program Files\\JavaSoft\\Jre\\1.2\\bin folder). Use
    the cd command in the **MS-DOS** window to change to that directory.
    If the folder is in a different drive, then you may first need to
    change to that drive by typing either c:\\ or d:\\ at the command
    prompt.

3)  Set the CLASSPATH parameter (in capital letters) to the java
    sub-folder of the ArrayTools installation folder.

4)  Invoke the ThreeDimensionalGraph java application by typing a java
    command at the prompt, with the following required parameters. (The
    keyword ThreeDimensionalGraph is case-sensitive.)

java ThreeDimensionalGraph \<mds file\> \<class file\> \<background\>
\<title\> \<width\> \<height\> \<shape\>

The command line parameters are as follows:

mds file = the file which contains the multidimensional scaling
coordinates along with other data. The full path of the mds file should
be given in quotes. This file is usually found as mds.dat in the
ArrayTools installation folder.

class file = the file which contains the class names and associated
plotting colors. The full path of the class file should be given in
quotes. This file is usually found as cls.dat in the ArrayTools
installation folder.

background = the color to use for the background of the rotating
scatterplot. The allowable values for this parameter are: default
(gray), and the 13 standard Java color names.

title = a string enclosed in quotes, which will be used as the title for
the rotating scatterplot.

width = an integer representing the width of the plotted points.

height = an integer representing the height of the plotted points.

shape = the shape of the plotted points. The allowable values for this
parameter are: oval (becomes a circle when height=width), rectangle
(becomes a square when height=width), diamond, triangle, and star.

If you find that the DOS command window does not allow you to type in
such a long command, then you can move the mds.dat and cls.dat files to
the root folder in order to shorten their pathnames within the DOS
command.

The following figure shows an example of a DOS session which was used to
re-play the multidimensional scaling plot:

![](media/image36.png){width="7.0in" height="2.607638888888889in"}

### Stopping a computation after it has started running

Sometimes a user may want to cancel a computation after it has started
running. If the computation is running in Excel, then the user may stop
the computation from within Excel by pressing the **ESC** key, or by
pressing the **Ctrl-Break** key combination.

However, if the computation is running within the R Server, it is not
possible to cancel the computation from within Excel, but the
computation may be stopped through the Windows manager. To stop a
computation which is running within the R Server, you must go to the
**Windows Task Manager** or **Close Program** window (by pressing the
**Ctrl-Alt-Del** key combination), and kill the **StatConnectorSrv**
process. In Windows NT, this is usually listed as STATCO\~1.EXE under
the **Processes** window of the **Task Manager**, whereas in Windows 98
this is listed as **Statconnectorsrv** in the **Close Program** window.
Once the **StatConnectorSrv** has been terminated, Excel will issue a
series of messages notifying the user that an error has occurred. You
may ignore these error messages, since the error was induced by the
termination of the **StatConnectorSrv** process. If the error message
asks if you want to debug, click **No**. After the R COM has been
closed, you should click on **ArrayTools  Utilities  Refresh R
Session** to start a fresh R session.

If the computation is running as a batch job within an MS-DOS window,
then the computation may be cancelled by simply closing the MS-DOS
window.

### Determining the order of the arrays in the collated data

The **Filtered log ratio** (or **Filtered log intensity**) worksheet of
the collated project workbook (as well as the other data variables in
the project folder) contains a column of data corresponding to each
array in the collated dataset. The order in which the arrays appear in
the collated data is determined by the input format of the raw
expression data files, *not* by the order in which the arrays appear in
the experiment descriptor file.

For the **horizontally stacked** and **vertically stacked** input data
formats, the order of the arrays in the collated data will be determined
by the order in which the array data blocks appear within the original
expression data file.

For the **arrays in separate files** input data format, the order of the
arrays in the collated data is determined by the alphanumeric sorting
order of the expression data filenames. Thus, if the expression data
filenames are numbered, then leading zeroes may be needed in order to
preserve their correct order. For instance, if the user has

Exp1.xls, Exp2.xls, Exp3.xls, ... , Exp10.xls

as the expression data filenames, then the arrays should be renamed as

Exp01.xls, Exp02.xls, Exp03.xls, ... , Exp10.xls

if the user wishes to preserve their order within the collated data. For
single-channel data, the order of the arrays in the collated data may be
important if the user wishes to specify which array to normalize all the
other arrays against (since all the arrays are normalized to the *first*
array in the dataset). To specify an array as the first array, simply
rename its expression data file before collating so that it begins with
an underscore. (An underscore precedes any numeral, and numerals precede
alphabetic letters in an alphanumeric sorting order.)

### Always save the collated project workbook when prompted!

Usually, BRB-ArrayTools will automatically save the collated project
workbook as you close the workbook. If, however, you are prompted to
save the collated project workbook when closing the workbook, then you
should always choose **Yes**, even if you have just saved it. Choosing
**No** may sometimes cause instabilities when you try to open the
collated project workbook later during another session.

## Troubleshooting the installation

### Testing the R COM

If you experience difficulty with the RServer while using
BRB-ArrayTools, you may wish to test the R COM to see if it was
registered properly. The R1_2_0.exe installer should automatically
register the R COM after unpacking all the files. However, there are
glitches which may occur on some user\'s machines while registering the
DLL. To test the R COM, double-click on the ..\\Dcom\\bin\\vbtest.exe
file in your R installation directory. When the **StatConnector Test**
screen comes up, click on **Start**. If the R COM was registered
properly, then a script will start to execute and a graphics window will
appear with a plot of a line.

If the R COM was not properly registered, then you must manually
register the R COM. To manually register the R COM:

1)  Click on the **Windows Start Button** and use the **Find** function
    to search for the location of the regsvr32.exe file. (Usually it
    will either be in the system or system32 folder of your Windows or
    Winnt folder.)

2)  Now open a MS-DOS window (usually by clicking on **Windows Start
    Button  Program  Command Prompt** ). Within the MS-DOS window, use
    the cd command to switch to the folder containing the regsvr32.exe
    file. Use the dir command to double-check that you have the folder
    containing that file.

i.e., type something like the following sequence of commands:

d:

cd d:\\winnt\\system32

dir regsvr32.dll

3)  Now type something like the following command:

> regsvr32 \"d:\\program files\\r\\rw1020\\bin\\StatConnectorClnt.dll\"
>
> You should substitute the location of your own R installation folder
> for \"d:\\program files\". You may or may not need the quotation
> marks, but you can try it both ways. You will know that the command
> has succeeded when you get a window popping up with a message like:
>
> \"DllRegisterServer in d:\\program
> files\\r\\rw1020\\bin\\StatConnectorClnt.dll succeeded.\"

4\) Once the regsvr32 command has succeeded, go back and test the R COM
again by double-clicking on the ..\\Dcom\\bin\\vbtest.exe file in your R
installation folder.

### Updating the R Server and BRB-ArrayTools library references

Usually the locations of library references needed by an add-in are
automatically updated when the add-in is loaded. Sometimes when loading
the ArrayTools.xla add-in, however, a Visual Basic message may appear
with a message such as \"Project not found\", indicating that the
appropriate library references have not been properly updated. In that
case, the user will need to manually update the library references
within the add-ins. However, before updating the library references,
first follow the instructions above to test and make sure that the R COM
is running properly.

To manually update the library references in the RServer:

1)  Open the Visual Basic Editor (VBE) by clicking on **Tools  Macro 
    Visual Basic Editor** from the Excel menubar. (If you had clicked on
    **Debug** when you got the error message, then the VBE is probably
    already open, with the offending command highlighted. In that case,
    click on **Run  Reset** from the VBE menubar.)

2)  Within the VBE, open the **Project Explorer** if it is not already
    open, by clicking on **View  Project Explorer** from the VBE
    menubar.

3)  Scroll through the tree pictured in the **Project Explorer** and
    click on **RServerVBAlib (RServer.xla)**.

4)  Then click on **Tools  References** from the VBE menubar. You will
    see a list of available library references, with a checkmark besides
    all the references which are used by the RServer. The problem is
    likely to be that you don\'t have the following two libraries
    checked, or that the location reference for those libraries is
    pointing to a nonexistent file. **Browse** for the following two
    files from your R installation folder:

```{=html}
<!-- -->
```
a)  ..\\R\\rw1020\\bin\\StatConnectorClnt.dll

b)  ..\\R\\rw1020\\bin\\StatConnectorSrv.exe

> Once you have browsed for these two files, they should show up within
> the list of available references as:

a)  StatConnectorClnt 1.0 Type Library

b)  StatConnectorSrv 0.91 Type Library

```{=html}
<!-- -->
```
5)  Now click on **File  Save RServer.xla** from the VBE menubar.

Now close down and restart Excel, and try loading the RServer.xla and
ArrayTools.xla add-ins again. The problem will probably have been
resolved.

If the problem persists, then try manually updating the library
references in BRB-ArrayTools:

1)  Follow steps 1)-4) above, except browse for the file
    ..\\ArrayTools\\Excel\\RServer.xla from the BRB-ArrayTools
    installation folder instead. This should show up within the list of
    available references as **RServerVBAlib**.

2)  There should also be a reference to something like **Microsoft
    Visual Basic for Applications Extensibility** in the list of
    available references. If it is not present or not checked, then ask
    your system administrator where the library exists, since the
    location of that library would be dependent upon your individual
    Excel installation.

3)  Now click on **File  Save ArrayTools.xla** from the VBE menubar.

4)  Close down and restart Excel, and try loading the RServer.xla and
    ArrayTools.xla add-ins again.

## Reporting bugs

Bug reports should be e-mailed to Amy Lam at: <alam@emmes.com>. To make
comments or request help, please post a message on the message board at
the BRB-ArrayTools website:

<http://linus.nci.nih.gov/BRB-ArrayTools.html>

Due to limited resources, we cannot guarantee that we will be able to
diagnose and fix all bugs reported by users. However we do try our best
to respond to users within a reasonable time, and to advise the user or
fix the problem whenever we can.

# References

**[Published references:]{.underline}**

Hedenfalk, I., Duggan, D., Chen, Y., Radmacher, M., Bittner, M., Simon,
R., Meltzer, P., Gusterson, B., Esteller, M., Raffeld, M., et al.,
\"Gene expression profiles of hereditary breast cancer\", New England
Journal of Medicine 344:539-548, 2001.

Ross, D., Scherf, U., Eisen, M., Perou, C., Rees, C., Spellman, P.,
Iyer, V., Jeffrey, S., Van de Rijh, M., Waltham, M., Pergamenschikov,
A., Lee, J., Lashkari, D., Shalon, D., Myers, T., Weinstein, J.,
Botstein, D., Brown, P., \"Systematic variation in gene expression
patterns in human cancer cell lines\", Nature Genetics 24:227-235, 2000.

**[Technical reports:]{.underline}**

In addition, the following two references may be found as technical
reports from the BRB website:
<http://linus.nci.nih.gov/~brb/TechReport.htm>

Technical Report 001:[A paradigm for class prediction using gene
expression
profiles.](ftp://linus.nci.nih.gov/pub/techreport/TechReport001.pdf) by
Michael D. Radmacher, Lisa M. Mcshane, and Richard Simon

Technical Report 002:[Methods for assessing reproducibility of
clustering patterns observed in analyses of microarray
data.](ftp://linus.nci.nih.gov/pub/techreport/TechReport002.pdf) by Lisa
M. McShane, Michael D. Radmacher, Boris Freidlin, Ren Yu, Ming-Chung Li,
and Richard Simon