3 An example

To display the usage and utility of NACHO, we show three examples in which the above mentioned functions are used and the results are briefly examined.

NACHO comes with presummarised data and in the first example we use this dataset to call the interactive web application using visualise().
In the second example, we show the process of going from raw RCC files to visualisations with a dataset queried from GEO using GEOquery.
In the third example, we use the summarised dataset from the second example to calculate the sample specific size factors using normalise() and its added functionality to predict housekeeping genes.

Besides creating interactive visualisations, NACHO also identifies poorly performing samples which can be seen under the Outlier Table tab in the interactive web application.
While calling normalise(), the user has the possibility to remove these outliers before size factor calculation.

3.1 Get NanoString nCounter data

3.1.1 Presummarised data from NACHO

This example shows how to use summarised data to call the interactive web application.
The raw data used is from a study of Liu et al. (2016) and was acquired from the NCBI GEO public database (Barrett et al. 2013).

library(NACHO)
data(GSE74821)
visualise(GSE74821)

3.1.2 Raw data from GEO

Numerous NanoString nCounter datasets are available from GEO (Barrett et al. 2013).
In this example, we use a mRNA dataset from the study of Bruce et al. (2015) with the GEO accession number: GSE70970. The data is extracted and prepared using the following code.

library(GEOquery)
# Download data
gse <- getGEO("GSE70970")
# Get phenotypes
targets <- pData(phenoData(gse[[1]]))
getGEOSuppFiles(GEO = "GSE70970", baseDir = tempdir())
# Unzip data
untar(
  tarfile = paste0(tempdir(), "/GSE70970/GSE70970_RAW.tar"), 
  exdir = paste0(tempdir(), "/GSE70970/Data")
)
# Add IDs
targets$IDFILE <- list.files(paste0(tempdir(), "/GSE70970/Data"))

After we extracted the dataset to the paste0(tempdir(), "/GSE70970/Data") directory, a Samplesheet.csv containing a column with the exact names of the files for each sample can be written or use as is.

3.2 The `summarise()` function

The first argument requires the path to the directory containing the RCC files, the second argument is the location of samplesheet followed by third argument with the column name containing the exact names of the files.
The housekeeping_genes and normalisation_method arguments respectively indicate which housekeeping genes and normalisation method should be used.

library(NACHO)
## 
## Attaching package: 'NACHO'
## The following object is masked from 'package:BiocGenerics':
## 
##     normalize
GSE70970_sum <- summarise(
  data_directory = paste0(tempdir(), "/GSE70970/Data"), # Where the data is
  ssheet_csv = targets, # The samplesheet
  id_colname = "IDFILE", # Name of the column that contains the identfiers
  housekeeping_genes = NULL, # Custom list of housekeeping genes
  housekeeping_predict = TRUE, # Predict the housekeeping genes based on the data?
  normalisation_method = "GEO", # Geometric mean or GLM
  n_comp = 5 # Number indicating the number of principal components to compute. 
)
## [NACHO] Importing RCC files.
## [NACHO] Performing QC and formatting data.
## [NACHO] Searching for the best housekeeping genes.
## [NACHO] Computing normalisation factors using "GEO" method for housekeeping genes prediction.
## [NACHO] The following predicted housekeeping genes will be used for normalisation:
##   - hsa-miR-103
##   - hsa-let-7e
##   - hsa-miR-1260
##   - hsa-miR-500+hsa-miR-501-5p
##   - hsa-miR-1274b
## [NACHO] Computing normalisation factors using "GEO" method.
## [NACHO] Missing values have been replaced with zeros for PCA.
## [NACHO] Normalising data using "GEO" method with housekeeping genes.
## [NACHO] Returning a list.
##   $ access              : character
##   $ housekeeping_genes  : character
##   $ housekeeping_predict: logical
##   $ housekeeping_norm   : logical
##   $ normalisation_method: character
##   $ remove_outliers     : logical
##   $ n_comp              : numeric
##   $ data_directory      : character
##   $ pc_sum              : data.frame
##   $ nacho               : data.frame
##   $ outliers_thresholds : list
##   $ raw_counts          : data.frame
##   $ normalised_counts   : data.frame

3.3 The `visualise()` function

When the summarisation is done, the summarised (or normalised) data can be visualised using the visualise() function as can be seen in the following chunk of code.

visualise(GSE70970_sum)

On the left, there are widgets that control the interactive plotting area. These widgets differ dependent on which main tab is chosen. The second layer of tabs is also interactive and changes based on which main tab is chosen. Each sample in the plots can be coloured based on either technical specifications which are included in the RCC files or based on specifications of your own choosing, though these specifications need to be included in the samplesheet.

3.4 The `normalise()` function

NACHO allows the discovery of housekeeping genes within your own dataset. NACHO finds the five best suitable housekeeping genes, however, it is possible that one of these five genes might not be suitable, which is why a subset of these discovered housekeeping genes might work better in some cases. For this example, we use the GSE70970 dataset from the previous example. The discovered housekeeping genes are saved in the result object as predicted_housekeeping.

print(GSE70970_sum[["housekeeping_genes"]])
## [1] "hsa-miR-103"                "hsa-let-7e"                
## [3] "hsa-miR-1260"               "hsa-miR-500+hsa-miR-501-5p"
## [5] "hsa-miR-1274b"

Let’s say hsa-miR-103 and hsa-let-7e are not suitable, therefore, you want to exclude these genes from the normalisation process.

my_housekeeping <- GSE70970_sum[["housekeeping_genes"]][-c(1, 2)]
print(my_housekeeping)
## [1] "hsa-miR-1260"               "hsa-miR-500+hsa-miR-501-5p"
## [3] "hsa-miR-1274b"

The next step is the actual normalisation. The first argument requires the summary which is created with the summarise() function. The second argument requires a vector of gene names. In this case, it is a subset of the discovered housekeeping genes we just made. With the third argument the user has the choice to remove the outliers. Lastly, the normalisation method can be choosed.
Here, the user has a choice between "GLM" or "GEO". The differences between normalisation methods are nuanced, however, a preference for either method are use case specific.
In this example, "GLM" is used.

GSE70970_norm <- normalise(
  nacho_object = GSE70970_sum,
  housekeeping_genes = my_housekeeping,
  housekeeping_predict = FALSE,
  housekeeping_norm = TRUE,
  normalisation_method = "GEO", 
  remove_outliers = TRUE
)
## [NACHO] Normalising "GSE70970_sum" with new value for parameters:
##   - housekeeping_genes = TRUE
##   - housekeeping_predict = TRUE
##   - remove_outliers = TRUE
## [NACHO] Computing normalisation factors using "GEO" method.
## [NACHO] Missing values have been replaced with zeros for PCA.
## [NACHO] Returning a list.
##   $ access              : character
##   $ housekeeping_genes  : character
##   $ housekeeping_predict: logical
##   $ housekeeping_norm   : logical
##   $ normalisation_method: character
##   $ remove_outliers     : logical
##   $ n_comp              : numeric
##   $ data_directory      : character
##   $ pc_sum              : data.frame
##   $ nacho               : data.frame
##   $ outliers_thresholds : list
##   $ raw_counts          : data.frame
##   $ normalised_counts   : data.frame

normalise() returns a list object (same as summarise()) with raw_counts and normalised_counts slots filled with the raw and normalised counts. Both counts are also in the NACHO data.frame.

3.5 The `autoplot()` function

The autoplot() function provides an easy way to plot any quality-control from the visualise() function.

autoplot(
  object = GSE74821, 
  x = "BD",
  colour = "CartridgeID", 
  size = 0.5, 
  show_legend = TRUE
)

The possible metrics (x) are:

"BD" (Binding Density)
"FoV" (Imaging)
"PC" (Positive Control Linearity)
"LoD" (Limit of Detection)
"Positive" (Positive Controls)
"Negative" (Negative Controls)
"Housekeeping" (Housekeeping Genes)
"PN" (Positive Controls vs. Negative Controls)
"ACBD" (Average Counts vs. Binding Density)
"ACMC" (Average Counts vs. Median Counts)
"PCA12" (Principal Component 1 vs. 2)
"PCAi" (Principal Component scree plot)
"PCA" (Principal Components planes)
"PFNF" (Positive Factor vs. Negative Factor)
"HF" (Housekeeping Factor)
"NORM" (Normalisation Factor)

3.5.1 Binding Density

3.5.2 Imaging

3.5.3 Positive Control Linearity

3.5.4 Limit of Detection

3.5.5 Positive Controls

3.5.6 Negative Controls

3.5.7 Housekeeping Genes

3.5.8 Positive Controls vs. Negative Controls

3.5.9 Average Counts vs. Binding Density

3.5.10 Average Counts vs. Median Counts

3.5.11 Principal Component 1 vs. 2

3.5.12 Principal Component scree plot

3.5.13 Principal Components planes

3.5.14 Positive Factor vs. Negative Factor

3.5.15 Housekeeping Factor

3.5.16 Normalisation Factor

3.6 The `render()` function

The render() function renders (using print(..., echo = TRUE) a comprehensive HTML report which includes all quality-control metrics and description of those metrics.

render(
  nacho_object = GSE74821,
  colour = "CartridgeID",
  output_file = "NACHO_QC.html",
  output_dir = ".",
  size = 0.5,
  show_legend = TRUE,
  clean = TRUE
)

The underneath function print() can be used directly within any Rmarkdown chunk, setting the parameter echo = TRUE.

print(
  x = GSE74821, 
  colour = "CartridgeID", 
  size = 0.5, 
  show_legend = TRUE, 
  echo = TRUE, 
  title_level = 3
)

3.6.1 RCC Summary

Samples: 20
Endogenous: 50
Housekeeping: 8
Negative: 8
Positive: 6

3.6.2 Settings

Predict housekeeping genes: FALSE
Normalise using housekeeping genes: TRUE
Housekeeping genes available: MRPL19, PSMC4, SF3A1, RPLP0, PUM1, ACTB, TFRC and GUSB
Normalise using: GLM
Principal components to compute: 10
Remove outliers: FALSE
- Binding Density (BD) < 0.1
- Binding Density (BD) > 2.25
- Imaging (FoV) < 75
- Positive Control Linearity (PC) < 0.95
- Limit of Detection (LoD) < 2
- Positive normalisation factor (Positive_factor) < 0.25
- Positive normalisation factor (Positive_factor) > 4
- Housekeeping normalisation factor (house_factor) < 0.091
- Housekeeping normalisation factor (house_factor) > 11

3.6.3 QC Metrics

3.6.3.1 Binding Density

The imaging unit only counts the codes that are unambiguously distinguishable. It simply will not count codes that overlap within an image. This provides increased confidence that the molecular counts you receive are from truly recognisable codes. Under most conditions, forgoing the few barcodes that do overlap will not impact your data. Too many overlapping codes in the image, however, will create a condition called image saturation in which significant data loss could occur (critical data loss from saturation is uncommon).

To determine the level of image saturation, the nCounter instrument calculates the number of optical features per square micron for each lane as it processes the images. This is called the Binding Density. The Binding Density is useful for determining whether data collection has been compromised due to image saturation. The acceptable range for Binding Density is:

0.1 - 2.25 for MAX/FLEX instruments
0.1 - 1.8 for SPRINT instruments

Within these ranges, relatively few reporters on the slide surface will overlap, enabling the instrument to accurately tabulate counts for each reporter species. A Binding Density significantly greater than the upper limit in either range is indicative of overlapping reporters on the slide surface. The counts observed in lanes with a Binding Density at this level may have had significant numbers of codes ignored, which could potentially affect quantification and linearity of the assay. Some of the factors that may contribute to increased Binding Density are listed in the Factors affecting Binding Density box.

3.6.3.2 Field of View (Imaging)

Each individual lane scanned on an nCounter system is divided into a few hundred imaging sections, called Fields of View (FOV), the exact number of which will depend on the system being used (i.e., MAX/FLEX or SPRINT), and the scanner settings selected by the user. The system images these FOVs separately, and sums the barcode counts of all FOVs from a single lane to form the final raw data count for each unique barcode target. Finally, the system reports the number of FOVs successfully imaged as FOV Counted.

Significant discrepancy between the number of FOV for which imaging was attempted (FOV Count) and for which imaging was successful (FOV Counted) may indicate an issue with imaging performance. Recommended percentage of registered FOVs (i.e., FOV Counted over FOV Count) is 75 %. Lanes will be flagged if this percentage is lower.

3.6.3.3 Positive Control linearity

Six synthetic DNA control targets are included with every nCounter Gene Expression assay. Their concentrations range linearly from 128 fM to 0.125 fM, and they are referred to as POS_A to POS_F, respectively. These Positive Controls are typically used to measure the efficiency of the hybridization reaction, and their step-wise concentrations also make them useful in checking the linearity performance of the assay. An R2 value is calculated from the regression between the known concentration of each of the Positive Controls and the resulting counts from them (this calculation is performed using log2-transformed values).

Since the known concentrations of the Positive Controls increase in a linear fashion, the resulting counts should, as well. Therefore, R2 values should be higher than 0.95.

Note that because POS_F has a known concentration of 0.125 fM, which is considered below the limit of detection of the system, it should be excluded from this calculation (although you will see that POS_F counts are significantly higher than the negative control counts in most cases).

3.6.3.4 Limit of Detection

The limit of detection is determined by measuring the ability to detect POS_E, the 0.5 fM positive control probe, which corresponds to about 10,000 copies of this target within each sample tube. On a FLEX/MAX system, the standard input of 100 ng of total RNA will roughly correspond to about 10,000 cell equivalents (assuming one cell contains 10 pg total RNA on average). An nCounter assay run on the FLEX/MAX system should thus conservatively be able to detect roughly one transcript copy per cell for each target (or 10,000 total transcript copies). In most assays, you will observe that even the POS_F probe (equivalent to 0.25 copies per cell) is detectable above background.

To determine whether POS_E is detectable, it can be compared to the counts for the negative control probes. Every nCounter Gene Expression assay is manufactured with eight negative control probes that should not hybridize to any targets within the sample. Counts from these will approximate general non-specific binding of probes within the samples being run. The counts of POS_E should be higher than two times the standard deviation above the mean of the negative control.

NACHO

A NAnostring quality Control dasHbOard

Mickaël Canouil, Ph.D., Gerard A. Bouland and Roderick C. Slieker, Ph.D.

October 07, 2019

1 Installation

2 Overview

3 An example

3.1 Get NanoString nCounter data

3.1.1 Presummarised data from NACHO

3.1.2 Raw data from GEO

3.2 The summarise() function

3.3 The visualise() function

3.4 The normalise() function

3.5 The autoplot() function

3.5.1 Binding Density

3.5.2 Imaging

3.5.3 Positive Control Linearity

3.5.4 Limit of Detection

3.5.5 Positive Controls

3.5.6 Negative Controls

3.5.7 Housekeeping Genes

3.5.8 Positive Controls vs. Negative Controls

3.5.9 Average Counts vs. Binding Density

3.5.10 Average Counts vs. Median Counts

3.5.11 Principal Component 1 vs. 2

3.5.12 Principal Component scree plot

3.5.13 Principal Components planes

3.5.14 Positive Factor vs. Negative Factor

3.5.15 Housekeeping Factor

3.5.16 Normalisation Factor

3.6 The render() function

3.6.1 RCC Summary

3.6.2 Settings

3.6.3 QC Metrics

3.6.3.1 Binding Density

3.6.3.2 Field of View (Imaging)

3.6.3.3 Positive Control linearity

3.6.3.4 Limit of Detection

3.6.4 Control Genes

3.6.4.1 Positive

3.6.4.2 Negative

3.6.4.3 Housekeeping

3.6.4.4 Control Probe Expression

3.6.5 QC Visuals

3.6.5.1 Average Count vs. Binding Density

3.6.5.2 Average Count vs. Median Count

3.6.5.3 Principal Component

3.6.5.3.1 PC1 vs. PC2

3.6.5.3.2 Factorial planes

3.6.5.3.3 Inertia

3.6.6 Normalisation Factors

3.6.6.1 Positive Factor vs. Background Threshold

3.6.6.2 Housekeeping Factor

3.6.6.3 Normalisation Result

References

3.2 The `summarise()` function

3.3 The `visualise()` function

3.4 The `normalise()` function

3.5 The `autoplot()` function

3.6 The `render()` function