Using curatedAdipoRNA

Mahmoud Ahmed

2020-10-29

Overview

In this document, we introduce the purpose of the curatedAdipoRNA package, its contents and its potential use cases. This package is a curated dataset of RNA-Seq samples. The samples are MDI-induced pre-phagocytes (3T3-L1) at different time points/stage of differentiation. The package document the data collection, pre-processing and processing. In addition to the documentation, the package contains the scripts that was used to generated the data in inst/scripts/ and the final RangedSummarizedExperiment object in data/.

Introduction

What is curatedAdipoRNA?

It is an R package for documenting and distributing a curated dataset. The package doesn’t contain any R functions.

What is contained in curatedAdipoRNA?

The package contains two different things:

  1. Scripts for documenting/reproducing the data in inst/scripts
  2. Final RangedSummarizedExperiment object in data/

What is curatedAdipoRNA for?

The RangedSummarizedExperiment object contains the adipo_counts, colData, rowRanges and metadata which can be used for the purposes of conducting differential expression or gene set enrichment analysis on the cell line model.

Installation

The curatedAdipoRNA package can be installed from Bioconductor using BiocManager.

if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("curatedAdipoRNA")

Docker image

The pre-processing and processing of the data setup environment is available as a docker image. This image is also suitable for reproducing this document. The docker image can be obtained using the docker CLI client.

$ docker pull bcmslab/adiporeg_rna:latest

Generating curatedAdipoRNA

Search strategy & data collection

The term “3T3-L1” was used to search the NCBI SRA repository. The results were sent to the run selector. 1,176 runs were viewed. The runs were faceted by Assay Type and the “rna-seq” which resulted in 323 runs. Only 98 samples from 16 different studies were included after being manually reviewed to fit the following criteria: * The raw data is available from GEO and has a GEO identifier (GSM#) * The raw data is linked to a published publicly available article * The protocols for generating the data sufficiently describe the origin of the cell line, the differentiation medium and the time points when the samples were collected. * In case the experimental designs included treatment other than the differentiation medias, the control (non-treated) samples were included.

Note: The data quality and the platform discrepancies are not included in these criteria.

Pre-processing

The scripts to download and process the raw data are located in inst/scripts/ and are glued together to run sequentially by the GNU make file Makefile. The following is basically a description of the recipes in the Makefile with emphasis on the software versions, options, inputs and outputs.

1. Downloading data download_fastq

  • Program: wget (1.18)
  • Input: run.csv, the URLs column
  • Output: *.fastq.gz
  • Options: -N

2. Making a genome index make_index

  • Program: hisat2-build (2.0.5)
  • Input: URL for mm10 mouse genome fasta files
  • Output: *.bt2 bowtie2 index for the mouse genome
  • Options: defaults

3. Dowinloading annotations get_annotation

  • Program: wget (1.18)
  • Input: URL for mm10 gene annotation file
  • Output: annotation.gtf
  • Options: -N

4. Aligning reads align_reads

  • Program: hisat2 (2.0.5)
  • Input: *.fastq.gz and mm10/ bowtie2 index for the mouse genome
  • Output: *.sam
  • Options: defaults

5. Counting features count_features

  • Program: featureCounts (1.5.1)
  • Input: *.bam and the annotation gtf file for the mm10 mouse genome.
  • Output: *.txt
  • Option: defaults

Quality assessment fastqc

  • Program: fastqc (0.11.5)
  • Input: *.fastq.gz and *.sam
  • Output: *_fastqc.zip
  • Option: defaults

Processing

The aim of this step is to construct a self-contained object with minimal manipulations of the pre-processed data followed by simple a simple exploration of the data in the next section.

Making Summarized experiment object make_object

The required steps to make this object from the pre-processed data are documented in the script and are supposed to be fully reproducible when run through this package. The output is a RangedSummarizedExperiment object containing the gene counts and the phenotype and features data and metadata.

The RangedSummarizedExperiment contains * The gene counts matrix gene_counts * The phenotype data colData * The feature data rowRanges * The metadata metadata which contains a data.frame of the studies from which the samples were collected.

Exploring the adipo_counts object

In this section, we conduct a simple exploration of the data objects to show the content of the package and how they can be loaded and used.

The count matrix can be accessed using assay. Here we show the first five entries of the first five samples.

The phenotype/samples data is a data.frame, It can be accessed using colData. The time and stage columns encode the time point in hours and stage of differentiation respectively.

Other columns in colData are selected information about the samples/runs or identifiers to different databases. The following table provides the description of each of these columns.

col_name description
id The GEO sample identifier.
study The SRA study identifier.
pmid The PubMed ID of the article where the data were published originally.
time The time point of the sample when collected in hours. The time is recorded from the beginning of the protocol as 0 hours.
stage The stage of differentiation of the sample when collected. Possible values are 0 to 3; 0 for non-differentiated; 1 for differentiating; and 2/3 for maturating samples.
bibtexkey The key of the study where the data were published originally. This maps to the studies object of the metadata which records the study information in bibtex format.
run The SRA run identifier.
submission The SRA study submission identifier.
sample The SRA sample identifier.
experiment The SRA experiment identifier.
study_name The GEO study/series identifier.
library_layout The type of RNA library. Possible values are SINGLE for single-end and PAIRED for paired-end runs.
instrument_model The name of the sequencing machine that was used to obtain the sequence reads.
qc The quality control output of fastqc on the separate files/runs.

Using the identifiers in colData along with Bioconductor packages such as GEOmetabd and/or SRAdb gives access to the sample metadata as submitted by the authors or recorded in the data repositories.

The features data are a GRanges object and can be accessed using rowRanges.

qc is a column of colData it is a list of lists. Each entry in the list correspond to one sample. Each sample has one or more objects of qc_read class. The reason for that is because paired-end samples has two separate files on which fastqc quality control were ran.

The metadata is a list of one object. studies is a data.frame containing the bibliography information of the studies from which the data were collected. Here we show the first entry in studies.

Summary of the studies in the dataset

#> `summarise()` ungrouping output (override with `.groups` argument)
GEO series ID PubMed ID Num. of Samples Time (hr) Differentiation Stage Instrument Model
GSE100056 29138456 4 -48/24 0/1 Ion Torrent Proton
GSE104508 29091029 3 192 3 NextSeq 500
GSE35724 24095730 3 192 3 Illumina Genome Analyzer II
GSE50612 25614607 8 -48/0/10/144 0/1/3 Illumina HiSeq 2000
GSE50934 24912735 6 0/168 0/3 Illumina HiSeq 2000
GSE53244 25412662 5 -48/0/48/120/240 0/1/3 Illumina HiSeq 2000
GSE57415 24857666 4 0/4 0/1 Illumina HiSeq 1500
GSE60745 26220403 12 0/24/48 0/1 Illumina HiSeq 2500
GSE64757 25596527 6 168 3 Illumina HiSeq 2000
GSE75639 27923061 6 -96/-48/0/6/48/168 0/1/3 Illumina HiSeq 2000
GSE84410 27899593 6 0/4/48/28 0/1 Illumina HiSeq 1500
GSE87113 27777310 6 0/1/2/4/48/168 0/1/3 Illumina HiSeq 2500
GSE89621 28009298 3 240 3 Illumina HiSeq 2500
GSE95029 29317436 10 0/48/96/144/192 0/1/2/3 Illumina HiSeq 2000
GSE95533 28475875 10 4/0/24/48/168 1/0/3 Illumina HiSeq 1500
GSE96764 29748257 6 0/2/4 0/1/2 Illumina HiSeq 2000

Example of using curatedAdipoRNA

Motivation

All the samples in this dataset come from the 3T3-L1 cell line. The MDI induction media, were used to induce adipocyte differentiation. The two important variables in the dataset are time and stage, which correspond to the time point and stage of differentiation when the sample were captured. Ideally, this dataset should be treated as a time course. However, for the purposes of this example, we only used samples from two time points 0 and 24 hours and treated them as independent groups. The goal of this example is to show how a typical differential expression analysis can be applied in the dataset. The main focus is to explain how the the data and metadata in adipo_counts fit in each main piece of the analysis. We started by filtering the low quality samples and low count genes. Then we applied the DESeq2 method with the default values.

Filtering low quality samples

First, we subset the adipo_counts object to all samples that has time points 0 or 24. The total number of samples is 30; 22 at 0 hour and 8 samples at 24 hours. The total number of features/genes in the set is 23916.

Since the quality metrics are reported per run file, we need to get the SSR* id for each of the samples. Notice that, some samples would have more than one file. In this case because some of the samples are paired-end, so each of them would have two files SRR\*_1 and SRR\*_2.

The qc object of the colData contains the output of fastqc in a qc_read class. More information on this object can be accessed by calling ?fastqcr::qc_read. Here, we only use the per_base_sequence_quality to filter out low quality samples. This is by no means enough quality control but it should drive the point home.

After tidying the data, we get a data.frame with three columns; run, Mean and Base for the run ID, the mean quality score and the base number in each read. fastqc provide thorough documentation of this quality control module and others. Notice that read length varies significantly between the runs and that the average of the mean score is suitable.

To identify the low quality samples, we categorize the runs by length and run_average which are the read length and the average of the per base mean scores. The following figure should make it easier to see why these cutoff were used in this case.

The run IDs of the “bad” samples is then used to remove them from the dataset.

Filtering low count genes

To identify the low count feature/genes (possibly not expressed), we keep only the features with at least 10 reads in 2 or more samples. Then we subset the object to exclude these genes.

Applying differential expression using DESeq2

DESeq2 is a well documented and widely used R package for the differential expression analysis. Here we use the default values of DESeq to find the genes which are deferentially expressed between the samples at 24 hours and 0 hours.

Citing the studies in this subset of the data

Speaking of studies, as mentioned earlier the studies object contains full information of the references of the original studies in which the data were published. Please cite them when using this dataset.

Citing curatedAdipoRNA

For citing the package use:

# citing the package
citation("curatedAdipoRNA")
#> 
#> To cite package 'curatedAdipoRNA' in publications use:
#> 
#>   Mahmoud Ahmed (2020). curatedAdipoRNA: A Curated RNA-Seq Dataset of
#>   MDI-induced Differentiated Adipocytes (3T3-L1). R package version
#>   1.7.0. https://github.com/MahShaaban/curatedAdipoRNA
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {curatedAdipoRNA: A Curated RNA-Seq Dataset of MDI-induced Differentiated Adipocytes
#> (3T3-L1)},
#>     author = {Mahmoud Ahmed},
#>     year = {2020},
#>     note = {R package version 1.7.0},
#>     url = {https://github.com/MahShaaban/curatedAdipoRNA},
#>   }

Session Info

devtools::session_info()
#> ─ Session info ───────────────────────────────────────────────────────────────
#>  setting  value                                             
#>  version  R Under development (unstable) (2020-10-17 r79346)
#>  os       Ubuntu 20.04.1 LTS                                
#>  system   x86_64, linux-gnu                                 
#>  ui       X11                                               
#>  language (EN)                                              
#>  collate  C                                                 
#>  ctype    en_US.UTF-8                                       
#>  tz       America/New_York                                  
#>  date     2020-10-29                                        
#> 
#> ─ Packages ───────────────────────────────────────────────────────────────────
#>  package              * version  date       lib source        
#>  annotate               1.69.0   2020-10-28 [2] Bioconductor  
#>  AnnotationDbi          1.53.0   2020-10-28 [2] Bioconductor  
#>  assertthat             0.2.1    2019-03-21 [2] CRAN (R 4.1.0)
#>  backports              1.1.10   2020-09-15 [2] CRAN (R 4.1.0)
#>  Biobase              * 2.51.0   2020-10-28 [2] Bioconductor  
#>  BiocGenerics         * 0.37.0   2020-10-28 [2] Bioconductor  
#>  BiocParallel           1.25.0   2020-10-28 [2] Bioconductor  
#>  bit                    4.0.4    2020-08-04 [2] CRAN (R 4.1.0)
#>  bit64                  4.0.5    2020-08-30 [2] CRAN (R 4.1.0)
#>  bitops                 1.0-6    2013-08-17 [2] CRAN (R 4.1.0)
#>  blob                   1.2.1    2020-01-20 [2] CRAN (R 4.1.0)
#>  callr                  3.5.1    2020-10-13 [2] CRAN (R 4.1.0)
#>  cli                    2.1.0    2020-10-12 [2] CRAN (R 4.1.0)
#>  colorspace             1.4-1    2019-03-18 [2] CRAN (R 4.1.0)
#>  crayon                 1.3.4    2017-09-16 [2] CRAN (R 4.1.0)
#>  curatedAdipoRNA      * 1.7.0    2020-10-29 [1] Bioconductor  
#>  DBI                    1.1.0    2019-12-15 [2] CRAN (R 4.1.0)
#>  DelayedArray           0.17.0   2020-10-28 [2] Bioconductor  
#>  desc                   1.2.0    2018-05-01 [2] CRAN (R 4.1.0)
#>  DESeq2               * 1.31.0   2020-10-28 [2] Bioconductor  
#>  devtools               2.3.2    2020-09-18 [2] CRAN (R 4.1.0)
#>  digest                 0.6.27   2020-10-24 [2] CRAN (R 4.1.0)
#>  dplyr                * 1.0.2    2020-08-18 [2] CRAN (R 4.1.0)
#>  ellipsis               0.3.1    2020-05-15 [2] CRAN (R 4.1.0)
#>  evaluate               0.14     2019-05-28 [2] CRAN (R 4.1.0)
#>  fansi                  0.4.1    2020-01-08 [2] CRAN (R 4.1.0)
#>  farver                 2.0.3    2020-01-16 [2] CRAN (R 4.1.0)
#>  fastqcr              * 0.1.2    2019-01-03 [2] CRAN (R 4.1.0)
#>  fs                     1.5.0    2020-07-31 [2] CRAN (R 4.1.0)
#>  genefilter             1.73.0   2020-10-28 [2] Bioconductor  
#>  geneplotter            1.69.0   2020-10-28 [2] Bioconductor  
#>  generics               0.0.2    2018-11-29 [2] CRAN (R 4.1.0)
#>  GenomeInfoDb         * 1.27.0   2020-10-28 [2] Bioconductor  
#>  GenomeInfoDbData       1.2.4    2020-10-19 [2] Bioconductor  
#>  GenomicRanges        * 1.43.0   2020-10-28 [2] Bioconductor  
#>  ggplot2              * 3.3.2    2020-06-19 [2] CRAN (R 4.1.0)
#>  glue                   1.4.2    2020-08-27 [2] CRAN (R 4.1.0)
#>  gtable                 0.3.0    2019-03-25 [2] CRAN (R 4.1.0)
#>  highr                  0.8      2019-03-20 [2] CRAN (R 4.1.0)
#>  htmltools              0.5.0    2020-06-16 [2] CRAN (R 4.1.0)
#>  httr                   1.4.2    2020-07-20 [2] CRAN (R 4.1.0)
#>  IRanges              * 2.25.0   2020-10-28 [2] Bioconductor  
#>  knitr                  1.30     2020-09-22 [2] CRAN (R 4.1.0)
#>  labeling               0.4.2    2020-10-20 [2] CRAN (R 4.1.0)
#>  lattice                0.20-41  2020-04-02 [2] CRAN (R 4.1.0)
#>  lifecycle              0.2.0    2020-03-06 [2] CRAN (R 4.1.0)
#>  locfit                 1.5-9.4  2020-03-25 [2] CRAN (R 4.1.0)
#>  magrittr               1.5      2014-11-22 [2] CRAN (R 4.1.0)
#>  Matrix                 1.2-18   2019-11-27 [2] CRAN (R 4.1.0)
#>  MatrixGenerics       * 1.3.0    2020-10-28 [2] Bioconductor  
#>  matrixStats          * 0.57.0   2020-09-25 [2] CRAN (R 4.1.0)
#>  memoise                1.1.0    2017-04-21 [2] CRAN (R 4.1.0)
#>  munsell                0.5.0    2018-06-12 [2] CRAN (R 4.1.0)
#>  pillar                 1.4.6    2020-07-10 [2] CRAN (R 4.1.0)
#>  pkgbuild               1.1.0    2020-07-13 [2] CRAN (R 4.1.0)
#>  pkgconfig              2.0.3    2019-09-22 [2] CRAN (R 4.1.0)
#>  pkgload                1.1.0    2020-05-29 [2] CRAN (R 4.1.0)
#>  prettyunits            1.1.1    2020-01-24 [2] CRAN (R 4.1.0)
#>  processx               3.4.4    2020-09-03 [2] CRAN (R 4.1.0)
#>  ps                     1.4.0    2020-10-07 [2] CRAN (R 4.1.0)
#>  purrr                  0.3.4    2020-04-17 [2] CRAN (R 4.1.0)
#>  R6                     2.5.0    2020-10-28 [2] CRAN (R 4.1.0)
#>  RColorBrewer           1.1-2    2014-12-07 [2] CRAN (R 4.1.0)
#>  Rcpp                   1.0.5    2020-07-06 [2] CRAN (R 4.1.0)
#>  RCurl                  1.98-1.2 2020-04-18 [2] CRAN (R 4.1.0)
#>  remotes                2.2.0    2020-07-21 [2] CRAN (R 4.1.0)
#>  rlang                  0.4.8    2020-10-08 [2] CRAN (R 4.1.0)
#>  rmarkdown              2.5      2020-10-21 [2] CRAN (R 4.1.0)
#>  rprojroot              1.3-2    2018-01-03 [2] CRAN (R 4.1.0)
#>  RSQLite                2.2.1    2020-09-30 [2] CRAN (R 4.1.0)
#>  S4Vectors            * 0.29.0   2020-10-28 [2] Bioconductor  
#>  scales                 1.1.1    2020-05-11 [2] CRAN (R 4.1.0)
#>  sessioninfo            1.1.1    2018-11-05 [2] CRAN (R 4.1.0)
#>  stringi                1.5.3    2020-09-09 [2] CRAN (R 4.1.0)
#>  stringr                1.4.0    2019-02-10 [2] CRAN (R 4.1.0)
#>  SummarizedExperiment * 1.21.0   2020-10-28 [2] Bioconductor  
#>  survival               3.2-7    2020-09-28 [2] CRAN (R 4.1.0)
#>  testthat               2.3.2    2020-03-02 [2] CRAN (R 4.1.0)
#>  tibble                 3.0.4    2020-10-12 [2] CRAN (R 4.1.0)
#>  tidyr                * 1.1.2    2020-08-27 [2] CRAN (R 4.1.0)
#>  tidyselect             1.1.0    2020-05-11 [2] CRAN (R 4.1.0)
#>  usethis                1.6.3    2020-09-17 [2] CRAN (R 4.1.0)
#>  utf8                   1.1.4    2018-05-24 [2] CRAN (R 4.1.0)
#>  vctrs                  0.3.4    2020-08-29 [2] CRAN (R 4.1.0)
#>  withr                  2.3.0    2020-09-22 [2] CRAN (R 4.1.0)
#>  xfun                   0.18     2020-09-29 [2] CRAN (R 4.1.0)
#>  XML                    3.99-0.5 2020-07-23 [2] CRAN (R 4.1.0)
#>  xtable                 1.8-4    2019-04-21 [2] CRAN (R 4.1.0)
#>  XVector                0.31.0   2020-10-28 [2] Bioconductor  
#>  yaml                   2.2.1    2020-02-01 [2] CRAN (R 4.1.0)
#>  zlibbioc               1.37.0   2020-10-28 [2] Bioconductor  
#> 
#> [1] /tmp/RtmplzURTS/Rinst2916d8656c02d2
#> [2] /home/biocbuild/bbs-3.13-bioc/R/library