From 20a7e7f6009c1d79f0bbbf0f8c51f41e9ba36288 Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Tue, 14 Feb 2023 08:59:18 -0500 Subject: [PATCH 1/8] Convert file to Rmd --- vignettes/IntroToAnnotationPackages.Rmd | 339 ++++++++++++++++++++++++ vignettes/databaseTypes.png | Bin 0 -> 65837 bytes 2 files changed, 339 insertions(+) create mode 100644 vignettes/IntroToAnnotationPackages.Rmd create mode 100644 vignettes/databaseTypes.png diff --git a/vignettes/IntroToAnnotationPackages.Rmd b/vignettes/IntroToAnnotationPackages.Rmd new file mode 100644 index 0000000..9d60206 --- /dev/null +++ b/vignettes/IntroToAnnotationPackages.Rmd @@ -0,0 +1,339 @@ +--- +title: "AnnotationDbi: Introduction To Bioconductor Annotation Packages" +author: + - name: "Marc Carlson" + - name: "Beryl Kanali" + affiliation: "Converted vignette from Sweave to Rmarkdown" +date: "Last modified: November 2022; Compiled: `r format(Sys.time(), '%B %d , %Y')`" + +vignette: > + %\VignetteIndexEntry{1. Introduction To Bioconductor Annotation Packages} + %\VignetteDepends{org.Hs.eg.db, TxDb.Hsapiens.UCSC.hg19.knownGene, EnsDb.Hsapiens.v75} + %\VignetteKeywords{annotation, database} + %\VignettePackage{AnnotationDbi} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +output: + BiocStyle::html_document +editor_options: + markdown: + wrap: 72 +--- + +```{r label = fig:dbtypes, echo = FALSE, fig.align="center", fig.cap = "Annotation Packages: the big picture", out.width = '60%'} +knitr::include_graphics("databaseTypes.png") +``` + +```{r echo=FALSE, include=FALSE} +if (!require("BiocManager", quietly = TRUE)) + install.packages("BiocManager") + +BiocManager::install("BiocStyle", force = TRUE) +``` + + +```{r include=FALSE} +library(knitr) +opts_chunk$set(tidy=FALSE) +``` + + +```{r include=FALSE} +library(BiocStyle) +``` + +*Bioconductor* provides extensive annotation resources. These can be +*genecentric*, or *genome centric*. Annotations can be provided in packages +curated by *Bioconductor*, or obtained from web-based resources. This vignette +is primarily concerned with describing the annotation resources that are +availableas packages. More advanced users who wish to learn about how to make +newannotation packages should see the vignette titled "Creating select +Interfacesfor custom Annotation resources" from the +`r Biocpkg("AnnotationForge")`package. + +Gene centric `r Biocpkg("AnnotationDbi")` packages include: + +- Organism level: e.g. `r Biocpkg("org.Mm.eg.db")`. +- Platform level: e.g. `r Biocpkg("hgu133plus2.db")`, +`r Biocpkg("hgu133plus2.probes")`, `r Biocpkg("hgu133plus2.cdf")` +- System-biology level: `r Biocpkg("GO.db")` + + +Genome centric `r Biocpkg("GenomicFeatures")` packages include + +- Transcriptome level: e.g. `r Biocpkg("TxDb.Hsapiens.UCSC.hg19.knownGene")`, +`r Biocpkg("EnsDb.Hsapiens.v75")`. +- Generic genome features: Can generate via `r Biocpkg("GenomicFeatures")` + +One web-based resource accesses [biomart](http://www.biomart.org/), via the `r +Biocpkg("biomaRt")` package: - Query web-based \`biomart' resource for genes, +sequence, SNPs, and etc. + +The most popular annotation packages have been modified so that they can make +use of a new set of methods to more easily access their contents. These four +methods are named: `columns`, `keytypes`, `keys` and `select`. And they are +described in this vignette. They can currently be used with all chip, organism, +and `TxDb` packages along with the popular GO.db package. + +For the older less popular packages, there are still conventient ways to +retrieve the data. The *How to use bimaps from the ".db" annotation packages* +vignette in the `r Biocpkg("AnnotationDbi")` package is a key reference for +learnign about how to use bimap objects. + +Finally, all of the \`.db' (and most other *Bioconductor* annotation packages) +are updated every 6 months corresponding to each release of *Bioconductor*. +Exceptions are made for packages where the actual resources that the packages +are based on have not themselves been updated. + +# AnnotationDb objects and the select method + +As previously mentioned, a new set of methods have been added that allow a +simpler way of extracting identifier based annotations. All the annotation +packages that support these new methods expose an object named exactly the same +as the package itself. These objects are collectively called `AnnotationDb` +objects for the class that they all inherit from. The more specific classes (the +ones that you will actually see in the wild) have names like `OrgDb`, `ChipDb` +or `TxDb` objects. These names correspond to the kind of package (and underlying +schema) being represented. The methods that can be applied to all of these +objects are `columns`, `keys`, `keytypes` and `select`. + +In addition, another accessor has recently been added which allows extraction of +one column at at time. the `mapIds` method allows users to extract data into +either a named character vector, a list or even a SimpleCharacterList. This +method should work with all the different kinds of `AnntoationDb` objects +described below. + +# ChipDb objects and the select method + +An extremely common kind of Annotation package is the so called platform based +or chip based package type. This package is intended to make the manufacturer +labels for a series of probes or probesets to a wide range of gene-based +features. A package of this kind will load an `ChipDb` object. Below is a set of +examples to show how you might use the standard 4 methods to interact with an +object of this type. + +First we need to load the package: + +```{r loadChip} +suppressPackageStartupMessages({ + library(hgu95av2.db) +}) +``` + +If we list the contents of this package, we can see that one of the many things +loaded is an object named after the package "hgu95av2.db": + +```{r listContents} +ls("package:hgu95av2.db") +``` + +We can look at this object to learn more about it: + +```{r show} +hgu95av2.db +``` + +If we want to know what kinds of data are retriveable via `select`, then we should use the `columns` method like this: + +```{r columns} +columns(hgu95av2.db) +``` + +If we are further curious to know more about those values for columns, we can consult the help pages. Asking about any of these values will pull up a manual page describing the different fields and what they mean. + +```{r help, eval=FALSE} +help("SYMBOL") +``` + +If we are curious about what kinds of fields we could potentiall use as keys to query the database, we can use the `keytypes` method. In a perfect world, this method will return values very similar to what was returned by `columns`, but in reality, some kinds of values make poor keys and so this list is often shorter. + +```{r keytypes} +keytypes(hgu95av2.db) +``` + +If we want to extract some sample keys of a particular type, we can use the `keys` method. + +```{r keys} +head(keys(hgu95av2.db, keytype="SYMBOL")) +``` + +And finally, if we have some keys, we can use `select` to extract them. By simply using appropriate argument values with select we can specify what keys we want to look up values for (keys), what we want returned back (columns) and the type of keys that we are passing in (keytype) + +```{r selectChip} +#1st get some example keys +k <- head(keys(hgu95av2.db,keytype="PROBEID")) +# then call select +select(hgu95av2.db, keys=k, columns=c("SYMBOL","GENENAME"), keytype="PROBEID") +``` + +And as you can see, when you call the code above, select will try to return a data.frame with all the things you asked for matched up to each other. + +Finally if you wanted to extract only one column of data you could instead use the mapIds method like this: + +```{r mapIdsChip} +#1st get some example keys +k <- head(keys(hgu95av2.db,keytype="PROBEID")) +# then call mapIds +mapIds(hgu95av2.db, keys=k, column=c("GENENAME"), keytype="PROBEID") +``` + +# OrgDb objects and the select method + +An organism level package (an 'org' package) uses a central gene identifier (e.g. Entrez Gene id) and contains mappings between this identifier and other kinds of identifiers (e.g. GenBank or Uniprot accession number, RefSeq id, etc.). The name of an org package is always of the form *org...db* (e.g.`r Biocpkg("org.Sc.sgd.db")`where ** is a 2-letter abbreviation of the organism (e.g.`r Biocpkg("Sc")` for *Saccharomyces cerevisiae*) and is an abbreviation (in lower-case) describing the type of central identifier (e.g. \Rpackage{sgd} for gene identifiers assigned by the Saccharomyces Genome Database, or \Rpackage{eg} for Entrez Gene ids). + +Just as the chip packages load a `ChipDb` object, the org packages will load a `OrgDb` object. The following exercise should acquaint you with the use of these methods in the context of an organism package. + +%% select exercise \bgroup \renewcommand{\labelenumi}{\alph{enumi}.} + +```{=tex} +\begin{Ext}% + + Display the `OrgDb` object for the `r Biocpkg("org.Hs.eg.db")` + package. + + Use the `columns` method to discover which sorts of + annotations can be extracted from it. Is this the same as the result + from the `keytypes` method? Use the `keytypes` + method to find out. + + Finally, use the `keys` method to extract UNIPROT + identifiers and then pass those keys in to the `select` + method in such a way that you extract the gene symbol and KEGG + pathway information for each. Use the help system as needed to + learn which values to pass in to columns in order to achieve this. +\end{Ext}\egroup +``` +\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% + +\<\>= library(org.Hs.eg.db) columns(org.Hs.eg.db) \@ \<\\>= help("SYMBOL") \## for explanation of these columns and keytypes values \@ \<\>= keytypes(org.Hs.eg.db) uniKeys \<- head(keys(org.Hs.eg.db, keytype="UNIPROT")) cols \<- c("SYMBOL", "PATH") select(org.Hs.eg.db, keys=uniKeys, columns=cols, keytype="UNIPROT") \@ \bigskip\egroup + +So how could you use select to annotate your results? This next exercise should hlep you to understand how that should generally work. + +````{=tex} +\bgroup + \renewcommand{\labelenumi}{\alph{enumi}.}\begin{Ext}% + + Please run the following code snippet (which will load a fake data + result that I have provided for the purposes of illustration): + +```{r selectData} +load(system.file("extdata", "resultTable.Rda", package="AnnotationDbi")) +head(resultTable) +``` + + The rownames of this table happen to provide entrez gene identifiers + for each row (for human). Find the gene symbol and gene name for + each of the rows in resultTable and then use the merge method to + attach those annotations to it. +\end{Ext}\egroup +```` + +\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% + +\<\>= annots \<- select(org.Hs.eg.db, keys=rownames(resultTable), columns=c("SYMBOL","GENENAME"), keytype="ENTREZID") resultTable \<- merge(resultTable, annots, by.x=0, by.y="ENTREZID") head(resultTable) \@ \bigskip\egroup + +# \`Using select with GO.db + +When you load the GO.db package, a `GODb` object is also loaded. This allows you to use the `columns`, `keys`, `keytypes` and `select` methods on the contents of the GO ontology. So if for example, you had a few GO IDs and wanted to know more about it, you could do it like this: + +```{r selectGO} +library(GO.db) +GOIDs <- c("GO:0042254","GO:0044183") +select(GO.db, keys=GOIDs, columns="DEFINITION", keytype="GOID") +``` + +# Using select with TxDb packages + +A `TxDb` package (a 'TxDb' package) connects a set of genomic coordinates to various transcript oriented features. The package can also contain Identifiers to features such as genes and transcripts, and the internal schema describes the relationships between these different elements. All TxDb containing packages follow a specific naming scheme that tells where the data came from as well as which build of the genome it comes from. + +%% select exercise TxDb \bgroup \renewcommand{\labelenumi}{\alph{enumi}.} + +```{=tex} +\begin{Ext}% + + Display the \Rclass{TxDb} object for the + \Biocpkg{TxDb.Hsapiens.UCSC.hg19.knownGene} package. + + As before, use the `columns` and `keytypes` + methods to discover which sorts of annotations can be extracted from + it. + + Use the `keys` method to extract just a few gene + identifiers and then pass those keys in to the `select` + method in such a way that you extract the transcript ids and + transcript starts for each. +\end{Ext}\egroup +``` +\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% + +```{r selectTxDb} +library(TxDb.Hsapiens.UCSC.hg19.knownGene) +txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene +txdb +columns(txdb) +keytypes(txdb) +keys <- head(keys(txdb, keytype="GENEID")) +cols <- c("TXID", "TXSTART") +select(txdb, keys=keys, columns=cols, keytype="GENEID") +``` + +\bigskip\egroup + +As is widely known, in addition to providing access via the `select` method, `TxDb` objects also provide access via the more familiar `transcripts`, `exons`, `cds`, `transcriptsBy`, `exonsBy` and `cdsBy` methods. For those who do not yet know about these other methods, more can be learned by seeing the vignette called: *Making and Utilizing TxDb Objects* in the `r Biocpkg("GenomicFeatures")` package. + +# Using select with EnsDb packages + +Similar to the `TxDb` objects/packages discussed in the previous section, `EnsDb` objects/packages provide genomic coordinates of gene models along with additional annotations (e.g. gene names, biotypes etc) but are tailored to annotations provided by Ensembl. The central methods `columns`, `keys`, `keytypes` and `select` are all implemented for `EnsDb` objects. In addition, these methods allow also the use of the `EnsDb` specific filtering framework to retrieve only selected information from the database (see vignette of the `r Biocpkg("ensembldb")` package for more information). + +In the example below we first evaluate which columns, keys and keytypes are available for `EnsDb` objects and fetch then the transcript ids, genomic start coordinate and transcript biotype for some genes. + +```{r} +if (!require("BiocManager", quietly = TRUE)) + install.packages("BiocManager") + +BiocManager::install("EnsDb.Hsapiens.v75") +``` + +```{r selectEnsDb} +library(EnsDb.Hsapiens.v75) +edb <- EnsDb.Hsapiens.v75 +edb + +## List all columns +columns(edb) + +## List all keytypes +keytypes(edb) + +## Get the first +keys <- head(keys(edb, keytype="GENEID")) + +## Get the data +select(edb, keys=keys, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), + keytype="GENEID") +``` + +We can modify the queries above to retrieve only genes encoded on chromosome Y. To this end we use filter objects available for `EnsDb` objects and its methods. + +```{r selectEnsDb.Y} +## Retrieve all gene IDs of all lincRNAs encoded on chromosome Y +linkY <- keys(edb, + filter=list(GeneBiotypeFilter("lincRNA"), SeqNameFilter("Y"))) +length(linkY) + +## We get now all transcripts for these genes. +txs <- select(edb, keys=linkY, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), + keytype="GENEID") +nrow(txs) + +## Alternatively, we could specify/pass the filters with the keys argument. +txs <- select(edb, keys=list(GeneBiotypeFilter("lincRNA"), SeqNameFilter("Y")), + columns=c("TXID", "TXSEQSTART", "TXBIOTYPE")) +nrow(txs) +``` + +The version number of R and packages loaded for generating the vignette were: + +```{r SessionInfo, echo=FALSE} +sessionInfo() +``` diff --git a/vignettes/databaseTypes.png b/vignettes/databaseTypes.png new file mode 100644 index 0000000000000000000000000000000000000000..5e51480f57fda5d12a4b5d8861ec83052c8e18ae GIT binary patch literal 65837 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 z%0DA*>+M_0=_G7snr}S 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

m);goNY7&dJHl1dgAi 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 literal 0 HcmV?d00001 From 3c659a7da5349494a6638408f05415a09308ce3b Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Thu, 23 Feb 2023 04:08:05 -0500 Subject: [PATCH 2/8] Update Rmd file --- vignettes/IntroToAnnotationPackages.Rmd | 180 +++++++++++++++--------- 1 file changed, 112 insertions(+), 68 deletions(-) diff --git a/vignettes/IntroToAnnotationPackages.Rmd b/vignettes/IntroToAnnotationPackages.Rmd index 9d60206..c71f9a0 100644 --- a/vignettes/IntroToAnnotationPackages.Rmd +++ b/vignettes/IntroToAnnotationPackages.Rmd @@ -15,9 +15,6 @@ vignette: > %\VignetteEncoding{UTF-8} output: BiocStyle::html_document -editor_options: - markdown: - wrap: 72 --- ```{r label = fig:dbtypes, echo = FALSE, fig.align="center", fig.cap = "Annotation Packages: the big picture", out.width = '60%'} @@ -66,7 +63,9 @@ Genome centric `r Biocpkg("GenomicFeatures")` packages include - Generic genome features: Can generate via `r Biocpkg("GenomicFeatures")` One web-based resource accesses [biomart](http://www.biomart.org/), via the `r -Biocpkg("biomaRt")` package: - Query web-based \`biomart' resource for genes, +Biocpkg("biomaRt")` package: + +- Query web-based \`biomart' resource for genes, sequence, SNPs, and etc. The most popular annotation packages have been modified so that they can make @@ -100,7 +99,7 @@ objects are `columns`, `keys`, `keytypes` and `select`. In addition, another accessor has recently been added which allows extraction of one column at at time. the `mapIds` method allows users to extract data into either a named character vector, a list or even a SimpleCharacterList. This -method should work with all the different kinds of `AnntoationDb` objects +method should work with all the different kinds of `AnnotationDb` objects described below. # ChipDb objects and the select method @@ -139,25 +138,34 @@ If we want to know what kinds of data are retriveable via `select`, then we shou columns(hgu95av2.db) ``` -If we are further curious to know more about those values for columns, we can consult the help pages. Asking about any of these values will pull up a manual page describing the different fields and what they mean. +If we are further curious to know more about those values for columns, we can +consult the help pages. Asking about any of these values will pull up a manual +page describing the different fields and what they mean. ```{r help, eval=FALSE} help("SYMBOL") ``` -If we are curious about what kinds of fields we could potentiall use as keys to query the database, we can use the `keytypes` method. In a perfect world, this method will return values very similar to what was returned by `columns`, but in reality, some kinds of values make poor keys and so this list is often shorter. +If we are curious about what kinds of fields we could potentiall use as keys to +query the database, we can use the `keytypes` method. In a perfect world, this +method will return values very similar to what was returned by `columns`, but in +reality, some kinds of values make poor keys and so this list is often shorter. ```{r keytypes} keytypes(hgu95av2.db) ``` -If we want to extract some sample keys of a particular type, we can use the `keys` method. +If we want to extract some sample keys of a particular type, we can use the +`keys` method. ```{r keys} head(keys(hgu95av2.db, keytype="SYMBOL")) ``` -And finally, if we have some keys, we can use `select` to extract them. By simply using appropriate argument values with select we can specify what keys we want to look up values for (keys), what we want returned back (columns) and the type of keys that we are passing in (keytype) +And finally, if we have some keys, we can use `select` to extract them. By +simply using appropriate argument values with select we can specify what keys we +want to look up values for (keys), what we want returned back (columns) and the +type of keys that we are passing in (keytype) ```{r selectChip} #1st get some example keys @@ -166,9 +174,11 @@ k <- head(keys(hgu95av2.db,keytype="PROBEID")) select(hgu95av2.db, keys=k, columns=c("SYMBOL","GENENAME"), keytype="PROBEID") ``` -And as you can see, when you call the code above, select will try to return a data.frame with all the things you asked for matched up to each other. +And as you can see, when you call the code above, select will try to return a +data.frame with all the things you asked for matched up to each other. -Finally if you wanted to extract only one column of data you could instead use the mapIds method like this: +Finally if you wanted to extract only one column of data you could instead use +the mapIds method like this: ```{r mapIdsChip} #1st get some example keys @@ -179,62 +189,84 @@ mapIds(hgu95av2.db, keys=k, column=c("GENENAME"), keytype="PROBEID") # OrgDb objects and the select method -An organism level package (an 'org' package) uses a central gene identifier (e.g. Entrez Gene id) and contains mappings between this identifier and other kinds of identifiers (e.g. GenBank or Uniprot accession number, RefSeq id, etc.). The name of an org package is always of the form *org...db* (e.g.`r Biocpkg("org.Sc.sgd.db")`where ** is a 2-letter abbreviation of the organism (e.g.`r Biocpkg("Sc")` for *Saccharomyces cerevisiae*) and is an abbreviation (in lower-case) describing the type of central identifier (e.g. \Rpackage{sgd} for gene identifiers assigned by the Saccharomyces Genome Database, or \Rpackage{eg} for Entrez Gene ids). +An organism level package (an 'org' package) uses a central gene identifier +(e.g. Entrez Gene id) and contains mappings between this identifier and other +kinds of identifiers (e.g. GenBank or Uniprot accession number, RefSeq id, +etc.). The name of an org package is always of the form org.\\.\\.db +(e.g.`r Biocpkg("org.Sc.sgd.db")`where \\ is a 2-letter abbreviation of the +organism (e.g.`r Biocpkg("Sc")` for *Saccharomyces cerevisiae*) and \\ is an +abbreviation (in lower-case) describing the type of central identifier (e.g. +`r Biocpkg("sgd")` for gene identifiers assigned by the Saccharomyces Genome +Database, or `r Biocpkg("eg")` for Entrez Gene ids). + +Just as the chip packages load a `ChipDb` object, the org packages will load a +`OrgDb` object. The following exercise should acquaint you with the use of these +methods in the context of an organism package. -Just as the chip packages load a `ChipDb` object, the org packages will load a `OrgDb` object. The following exercise should acquaint you with the use of these methods in the context of an organism package. +**Exercise 1** -%% select exercise \bgroup \renewcommand{\labelenumi}{\alph{enumi}.} +Display the `OrgDb` object for the `r Biocpkg("org.Hs.eg.db")` package. -```{=tex} -\begin{Ext}% +Use the `columns` method to discover which sorts of annotations can be extracted +from it. Is this the same as the result from the `keytypes` method? Use the +`keytypes` method to find out. - Display the `OrgDb` object for the `r Biocpkg("org.Hs.eg.db")` - package. +Finally, use the `keys` method to extract UNIPROT identifiers and then pass +those keys in to the `select` method in such a way that you extract the gene +symbol and KEGG pathway information for each. Use the help system as needed to +learn which values to pass in to columns in order to achieve this. - Use the `columns` method to discover which sorts of - annotations can be extracted from it. Is this the same as the result - from the `keytypes` method? Use the `keytypes` - method to find out. +**Solution:** - Finally, use the `keys` method to extract UNIPROT - identifiers and then pass those keys in to the `select` - method in such a way that you extract the gene symbol and KEGG - pathway information for each. Use the help system as needed to - learn which values to pass in to columns in order to achieve this. -\end{Ext}\egroup +```{r} +library(org.Hs.eg.db) +columns(org.Hs.eg.db) ``` -\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% -\<\>= library(org.Hs.eg.db) columns(org.Hs.eg.db) \@ \<\\>= help("SYMBOL") \## for explanation of these columns and keytypes values \@ \<\>= keytypes(org.Hs.eg.db) uniKeys \<- head(keys(org.Hs.eg.db, keytype="UNIPROT")) cols \<- c("SYMBOL", "PATH") select(org.Hs.eg.db, keys=uniKeys, columns=cols, keytype="UNIPROT") \@ \bigskip\egroup +```{r} +help("SYMBOL") ## for explanation of these columns and keytypes values +keytypes(org.Hs.eg.db) +``` + +```{r} +uniKeys <- head(keys(org.Hs.eg.db, keytype="UNIPROT")) +cols <- c("SYMBOL", "PATH") +select(org.Hs.eg.db, keys=uniKeys, columns=cols, keytype="UNIPROT") +``` -So how could you use select to annotate your results? This next exercise should hlep you to understand how that should generally work. +So how could you use select to annotate your results? This next exercise should +hlep you to understand how that should generally work. -````{=tex} -\bgroup - \renewcommand{\labelenumi}{\alph{enumi}.}\begin{Ext}% +**Exercise 2** - Please run the following code snippet (which will load a fake data - result that I have provided for the purposes of illustration): +Please run the following code snippet (which will load a fake data result that I +have provided for the purposes of illustration): ```{r selectData} load(system.file("extdata", "resultTable.Rda", package="AnnotationDbi")) head(resultTable) ``` - The rownames of this table happen to provide entrez gene identifiers - for each row (for human). Find the gene symbol and gene name for - each of the rows in resultTable and then use the merge method to - attach those annotations to it. -\end{Ext}\egroup -```` +The rownames of this table happen to provide entrez gene identifiers for each +row (for human). Find the gene symbol and gene name for each of the rows in +resultTable and then use the merge method to attach those annotations to it. -\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% -\<\>= annots \<- select(org.Hs.eg.db, keys=rownames(resultTable), columns=c("SYMBOL","GENENAME"), keytype="ENTREZID") resultTable \<- merge(resultTable, annots, by.x=0, by.y="ENTREZID") head(resultTable) \@ \bigskip\egroup +**Solution:** +```{r} +annots <- select(org.Hs.eg.db, keys=rownames(resultTable), +columns=c("SYMBOL","GENENAME"), keytype="ENTREZID") -# \`Using select with GO.db +resultTable <- merge(resultTable, annots, by.x=0, by.y="ENTREZID") +head(resultTable) +``` -When you load the GO.db package, a `GODb` object is also loaded. This allows you to use the `columns`, `keys`, `keytypes` and `select` methods on the contents of the GO ontology. So if for example, you had a few GO IDs and wanted to know more about it, you could do it like this: +# Using select with GO.db + +When you load the GO.db package, a `GODb` object is also loaded. This allows you +to use the `columns`, `keys`, `keytypes` and `select` methods on the contents of +the GO ontology. So if for example, you had a few GO IDs and wanted to know more +about it, you could do it like this: ```{r selectGO} library(GO.db) @@ -244,27 +276,26 @@ select(GO.db, keys=GOIDs, columns="DEFINITION", keytype="GOID") # Using select with TxDb packages -A `TxDb` package (a 'TxDb' package) connects a set of genomic coordinates to various transcript oriented features. The package can also contain Identifiers to features such as genes and transcripts, and the internal schema describes the relationships between these different elements. All TxDb containing packages follow a specific naming scheme that tells where the data came from as well as which build of the genome it comes from. +A `TxDb` package (a 'TxDb' package) connects a set of genomic coordinates to +various transcript oriented features. The package can also contain Identifiers +to features such as genes and transcripts, and the internal schema describes the +relationships between these different elements. All TxDb containing packages +follow a specific naming scheme that tells where the data came from as well as +which build of the genome it comes from. -%% select exercise TxDb \bgroup \renewcommand{\labelenumi}{\alph{enumi}.} +**Exercise 3** -```{=tex} -\begin{Ext}% +Display the `TxDb` object for the `r Biocpkg("TxDb.Hsapiens.UCSC.hg19.knownGene")` +package. - Display the \Rclass{TxDb} object for the - \Biocpkg{TxDb.Hsapiens.UCSC.hg19.knownGene} package. +As before, use the `columns` and `keytypes` methods to discover which sorts of +annotations can be extracted from it. - As before, use the `columns` and `keytypes` - methods to discover which sorts of annotations can be extracted from - it. +Use the `keys` method to extract just a few gene identifiers and then pass those +keys in to the `select` method in such a way that you extract the transcript ids +and transcript starts for each. - Use the `keys` method to extract just a few gene - identifiers and then pass those keys in to the `select` - method in such a way that you extract the transcript ids and - transcript starts for each. -\end{Ext}\egroup -``` -\bgroup % \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% +**Solution:** ```{r selectTxDb} library(TxDb.Hsapiens.UCSC.hg19.knownGene) @@ -277,15 +308,27 @@ cols <- c("TXID", "TXSTART") select(txdb, keys=keys, columns=cols, keytype="GENEID") ``` -\bigskip\egroup - -As is widely known, in addition to providing access via the `select` method, `TxDb` objects also provide access via the more familiar `transcripts`, `exons`, `cds`, `transcriptsBy`, `exonsBy` and `cdsBy` methods. For those who do not yet know about these other methods, more can be learned by seeing the vignette called: *Making and Utilizing TxDb Objects* in the `r Biocpkg("GenomicFeatures")` package. +As is widely known, in addition to providing access via the `select` method, +`TxDb` objects also provide access via the more familiar `transcripts`, `exons`, +`cds`, `transcriptsBy`, `exonsBy` and `cdsBy` methods. For those who do not yet +know about these other methods, more can be learned by seeing the vignette +called: *Making and Utilizing TxDb Objects* in the +`r Biocpkg("GenomicFeatures")` package. # Using select with EnsDb packages -Similar to the `TxDb` objects/packages discussed in the previous section, `EnsDb` objects/packages provide genomic coordinates of gene models along with additional annotations (e.g. gene names, biotypes etc) but are tailored to annotations provided by Ensembl. The central methods `columns`, `keys`, `keytypes` and `select` are all implemented for `EnsDb` objects. In addition, these methods allow also the use of the `EnsDb` specific filtering framework to retrieve only selected information from the database (see vignette of the `r Biocpkg("ensembldb")` package for more information). +Similar to the `TxDb` objects/packages discussed in the previous section, +`EnsDb` objects/packages provide genomic coordinates of gene models along with +additional annotations (e.g. gene names, biotypes etc) but are tailored to +annotations provided by Ensembl. The central methods `columns`, `keys`, +`keytypes` and `select` are all implemented for `EnsDb` objects. In addition, +these methods allow also the use of the `EnsDb` specific filtering framework to +retrieve only selected information from the database (see vignette of the +`r Biocpkg("ensembldb")` package for more information). -In the example below we first evaluate which columns, keys and keytypes are available for `EnsDb` objects and fetch then the transcript ids, genomic start coordinate and transcript biotype for some genes. +In the example below we first evaluate which columns, keys and keytypes are +available for `EnsDb` objects and fetch then the transcript ids, genomic start +coordinate and transcript biotype for some genes. ```{r} if (!require("BiocManager", quietly = TRUE)) @@ -313,7 +356,8 @@ select(edb, keys=keys, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), keytype="GENEID") ``` -We can modify the queries above to retrieve only genes encoded on chromosome Y. To this end we use filter objects available for `EnsDb` objects and its methods. +We can modify the queries above to retrieve only genes encoded on chromosome Y. +To this end we use filter objects available for `EnsDb` objects and its methods. ```{r selectEnsDb.Y} ## Retrieve all gene IDs of all lincRNAs encoded on chromosome Y From 1132c5cbb1846665563b88decb457f66159a44d4 Mon Sep 17 00:00:00 2001 From: BerylKanali <50364045+BerylKanali@users.noreply.github.com> Date: Thu, 2 Mar 2023 15:00:49 +0300 Subject: [PATCH 3/8] Update DESCRIPTION --- DESCRIPTION | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index a95de9d..80e93e6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -8,7 +8,13 @@ BugReports: https://github.com/Bioconductor/AnnotationDbi/issues Version: 1.61.0 License: Artistic-2.0 Encoding: UTF-8 -Author: Hervé Pagès, Marc Carlson, Seth Falcon, Nianhua Li +Authors@R: c( + person("Hervé", "Pagès", role="aut"), + person("Marc", "Carlson", role="aut"), + person("Seth", "Falcon", role="aut"), + person("Nianhua", "Li", role="aut"), + person("Beryl", "Kanali", role="ctb", + comment="Converted 'IntoToAnnotationPackages' vignette from Sweave to RMarkdown.")) Maintainer: Bioconductor Package Maintainer Depends: R (>= 2.7.0), methods, utils, stats4, BiocGenerics (>= 0.29.2), Biobase (>= 1.17.0), IRanges From 29bbca944115b4dc3ef8d32be1ba6eb530a58647 Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Thu, 2 Mar 2023 07:07:52 -0500 Subject: [PATCH 4/8] update Rmd contents --- vignettes/IntroToAnnotationPackages.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/IntroToAnnotationPackages.Rmd b/vignettes/IntroToAnnotationPackages.Rmd index c71f9a0..f1f81cc 100644 --- a/vignettes/IntroToAnnotationPackages.Rmd +++ b/vignettes/IntroToAnnotationPackages.Rmd @@ -46,7 +46,7 @@ is primarily concerned with describing the annotation resources that are availableas packages. More advanced users who wish to learn about how to make newannotation packages should see the vignette titled "Creating select Interfacesfor custom Annotation resources" from the -`r Biocpkg("AnnotationForge")`package. +`r Biocpkg("AnnotationForge")` package. Gene centric `r Biocpkg("AnnotationDbi")` packages include: From 5d66af67ccdfbd41680360025644909c1cacfb5a Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Thu, 2 Mar 2023 07:11:37 -0500 Subject: [PATCH 5/8] delete Rnw file --- vignettes/IntroToAnnotationPackages.Rnw | 413 ------------------------ 1 file changed, 413 deletions(-) delete mode 100644 vignettes/IntroToAnnotationPackages.Rnw diff --git a/vignettes/IntroToAnnotationPackages.Rnw b/vignettes/IntroToAnnotationPackages.Rnw deleted file mode 100644 index 105567d..0000000 --- a/vignettes/IntroToAnnotationPackages.Rnw +++ /dev/null @@ -1,413 +0,0 @@ -%\VignetteIndexEntry{1. Introduction To Bioconductor Annotation Packages} -%\VignetteDepends{org.Hs.eg.db, TxDb.Hsapiens.UCSC.hg19.knownGene, EnsDb.Hsapiens.v75} -%\VignetteKeywords{annotation, database} -%\VignettePackage{AnnotationDbi} -%\VignetteEngine{knitr::knitr} - -\documentclass[11pt]{article} - -<>= -BiocStyle::latex() -@ - -%% Question, Exercise, Solution -\usepackage{theorem} -\theoremstyle{break} -\newtheorem{Ext}{Exercise} -\newtheorem{Question}{Question} - -\newenvironment{Exercise}{ - \renewcommand{\labelenumi}{\alph{enumi}.}\begin{Ext}% -}{\end{Ext}} -\newenvironment{Solution}{% - \noindent\textbf{Solution:}\renewcommand{\labelenumi}{\alph{enumi}.}% -}{\bigskip} - -\title{AnnotationDbi: Introduction To Bioconductor Annotation Packages} -\author{Marc Carlson} - -<>= -library(knitr) -opts_chunk$set(tidy=FALSE) -@ - -\begin{document} - -\maketitle - -\begin{figure}[ht] -\centering -\includegraphics[width=.6\textwidth]{databaseTypes.pdf} -\caption{Annotation Packages: the big picture} -\label{fig:dbtypes} -\end{figure} - -\Bioconductor{} provides extensive annotation resources. These can be -\emph{gene centric}, or \emph{genome centric}. Annotations can be -provided in packages curated by \Bioconductor, or obtained from -web-based resources. This vignette is primarily concerned with -describing the annotation resources that are available as -packages. More advanced users who wish to learn about how to make new -annotation packages should see the vignette titled "Creating select -Interfaces for custom Annotation resources" from the -\Rpackage{AnnotationForge} package. - -Gene centric \Rpackage{AnnotationDbi} packages include: -\begin{itemize} - \item Organism level: e.g. \Rpackage{org.Mm.eg.db}. - \item Platform level: e.g. \Rpackage{hgu133plus2.db}, - \Rpackage{hgu133plus2.probes}, \Rpackage{hgu133plus2.cdf}. - \item System-biology level: \Rpackage{GO.db} -\end{itemize} -Genome centric \Rpackage{GenomicFeatures} packages include -\begin{itemize} - \item Transcriptome level: - e.g. \Rpackage{TxDb.Hsapiens.UCSC.hg19.knownGene}, - \Rpackage{EnsDb.Hsapiens.v75}. - \item Generic genome features: Can generate via \Rpackage{GenomicFeatures} -\end{itemize} -One web-based resource accesses -\href{http://www.biomart.org/}{biomart}, via the \Rpackage{biomaRt} -package: -\begin{itemize} - \item Query web-based `biomart' resource for genes, sequence, - SNPs, and etc. -\end{itemize} - -The most popular annotation packages have been modified so that they -can make use of a new set of methods to more easily access their -contents. These four methods are named: \Rfunction{columns}, -\Rfunction{keytypes}, \Rfunction{keys} and \Rfunction{select}. And -they are described in this vignette. They can currently be used with -all chip, organism, and \Rclass{TxDb} packages along with the popular -GO.db package. - -For the older less popular packages, there are still conventient ways -to retrieve the data. The \emph{How to use bimaps from the ".db" - annotation packages} vignette in the \Rpackage{AnnotationDbi} -package is a key reference for learnign about how to use bimap -objects. - -Finally, all of the `.db' (and most other \Bioconductor{} annotation -packages) are updated every 6 months corresponding to each release of -\Bioconductor{}. Exceptions are made for packages where the actual -resources that the packages are based on have not themselves been -updated. - -\section{AnnotationDb objects and the select method} - -As previously mentioned, a new set of methods have been added that -allow a simpler way of extracting identifier based annotations. All -the annotation packages that support these new methods expose an -object named exactly the same as the package itself. These objects -are collectively called \Rclass{AnntoationDb} objects for the class -that they all inherit from. The more specific classes (the ones that -you will actually see in the wild) have names like \Rclass{OrgDb}, -\Rclass{ChipDb} or \Rclass{TxDb} objects. These names correspond to -the kind of package (and underlying schema) being represented. The -methods that can be applied to all of these objects are -\Rfunction{columns}, \Rfunction{keys}, \Rfunction{keytypes} and -\Rfunction{select}. - -In addition, another accessor has recently been added which allows -extraction of one column at at time. the \Rfunction{mapIds} method -allows users to extract data into either a named character vector, a -list or even a SimpleCharacterList. This method should work with all -the different kinds of \Rclass{AnntoationDb} objects described below. - -\section{ChipDb objects and the select method} - -An extremely common kind of Annotation package is the so called -platform based or chip based package type. This package is intended -to make the manufacturer labels for a series of probes or probesets to -a wide range of gene-based features. A package of this kind will load -an \Rclass{ChipDb} object. Below is a set of examples to show how you -might use the standard 4 methods to interact with an object of this -type. - -First we need to load the package: - -<>= -suppressPackageStartupMessages({ - library(hgu95av2.db) -}) -@ - -If we list the contents of this package, we can see that one of the -many things loaded is an object named after the package "hgu95av2.db": - -<>= -ls("package:hgu95av2.db") -@ - -We can look at this object to learn more about it: - -<>= -hgu95av2.db -@ - -If we want to know what kinds of data are retriveable via -\Rfunction{select}, then we should use the \Rfunction{columns} method -like this: - -<>= -columns(hgu95av2.db) -@ - -If we are further curious to know more about those values for columns, -we can consult the help pages. Asking about any of these values will -pull up a manual page describing the different fields and what they -mean. - -<>= -help("SYMBOL") -@ - -If we are curious about what kinds of fields we could potentiall use -as keys to query the database, we can use the \Rfunction{keytypes} -method. In a perfect world, this method will return values very -similar to what was returned by \Rfunction{columns}, but in reality, -some kinds of values make poor keys and so this list is often shorter. - -<>= -keytypes(hgu95av2.db) -@ - -If we want to extract some sample keys of a particular type, we can -use the \Rfunction{keys} method. - -<>= -head(keys(hgu95av2.db, keytype="SYMBOL")) -@ - -And finally, if we have some keys, we can use \Rfunction{select} to -extract them. By simply using appropriate argument values with select -we can specify what keys we want to look up values for (keys), what we -want returned back (columns) and the type of keys that we are passing -in (keytype) - -<>= -#1st get some example keys -k <- head(keys(hgu95av2.db,keytype="PROBEID")) -# then call select -select(hgu95av2.db, keys=k, columns=c("SYMBOL","GENENAME"), keytype="PROBEID") -@ - -And as you can see, when you call the code above, select will try to -return a data.frame with all the things you asked for matched up to -each other. - -Finally if you wanted to extract only one column of data you could -instead use the mapIds method like this: - -<>= -#1st get some example keys -k <- head(keys(hgu95av2.db,keytype="PROBEID")) -# then call mapIds -mapIds(hgu95av2.db, keys=k, column=c("GENENAME"), keytype="PROBEID") -@ - -\section{OrgDb objects and the select method} - -An organism level package (an `org' package) uses a central gene -identifier (e.g. Entrez Gene id) and contains mappings between this -identifier and other kinds of identifiers (e.g. GenBank or Uniprot -accession number, RefSeq id, etc.). The name of an org package is -always of the form \emph{org...db} -(e.g. \Rpackage{org.Sc.sgd.db}) where \emph{} is a 2-letter -abbreviation of the organism (e.g. \Rpackage{Sc} for -\emph{Saccharomyces cerevisiae}) and \emph{} is an abbreviation -(in lower-case) describing the type of central identifier -(e.g. \Rpackage{sgd} for gene identifiers assigned by the -Saccharomyces Genome Database, or \Rpackage{eg} for Entrez Gene ids). - -Just as the chip packages load a \Rclass{ChipDb} object, the org -packages will load a \Rclass{OrgDb} object. The following exercise -should acquaint you with the use of these methods in the context of an -organism package. - -%% select exercise -\begin{Exercise} - Display the \Rclass{OrgDb} object for the \Biocpkg{org.Hs.eg.db} - package. - - Use the \Rfunction{columns} method to discover which sorts of - annotations can be extracted from it. Is this the same as the result - from the \Rfunction{keytypes} method? Use the \Rfunction{keytypes} - method to find out. - - Finally, use the \Rfunction{keys} method to extract UNIPROT - identifiers and then pass those keys in to the \Rfunction{select} - method in such a way that you extract the gene symbol and KEGG - pathway information for each. Use the help system as needed to - learn which values to pass in to columns in order to achieve this. -\end{Exercise} -\begin{Solution} -<>= -library(org.Hs.eg.db) -columns(org.Hs.eg.db) -@ -<>= -help("SYMBOL") ## for explanation of these columns and keytypes values -@ -<>= -keytypes(org.Hs.eg.db) -uniKeys <- head(keys(org.Hs.eg.db, keytype="UNIPROT")) -cols <- c("SYMBOL", "PATH") -select(org.Hs.eg.db, keys=uniKeys, columns=cols, keytype="UNIPROT") -@ -\end{Solution} - -So how could you use select to annotate your results? This next -exercise should hlep you to understand how that should generally work. - -\begin{Exercise} - Please run the following code snippet (which will load a fake data - result that I have provided for the purposes of illustration): - -<>= -load(system.file("extdata", "resultTable.Rda", package="AnnotationDbi")) -head(resultTable) -@ - - The rownames of this table happen to provide entrez gene identifiers - for each row (for human). Find the gene symbol and gene name for - each of the rows in resultTable and then use the merge method to - attach those annotations to it. -\end{Exercise} -\begin{Solution} -<>= -annots <- select(org.Hs.eg.db, keys=rownames(resultTable), - columns=c("SYMBOL","GENENAME"), keytype="ENTREZID") -resultTable <- merge(resultTable, annots, by.x=0, by.y="ENTREZID") -head(resultTable) -@ -\end{Solution} - -\section{Using select with GO.db} - -When you load the GO.db package, a \Rclass{GODb} object is also -loaded. This allows you to use the \Rfunction{columns}, -\Rfunction{keys}, \Rfunction{keytypes} and \Rfunction{select} methods -on the contents of the GO ontology. So if for example, you had a few -GO IDs and wanted to know more about it, you could do it like this: - -<>= -library(GO.db) -GOIDs <- c("GO:0042254","GO:0044183") -select(GO.db, keys=GOIDs, columns="DEFINITION", keytype="GOID") -@ - -\section{Using select with TxDb packages} - -A \Rclass{TxDb} package (a 'TxDb' package) connects a set of genomic -coordinates to various transcript oriented features. The package can -also contain Identifiers to features such as genes and transcripts, -and the internal schema describes the relationships between these -different elements. All TxDb containing packages follow a specific -naming scheme that tells where the data came from as well as which -build of the genome it comes from. - -%% select exercise TxDb -\begin{Exercise} - Display the \Rclass{TxDb} object for the - \Biocpkg{TxDb.Hsapiens.UCSC.hg19.knownGene} package. - - As before, use the \Rfunction{columns} and \Rfunction{keytypes} - methods to discover which sorts of annotations can be extracted from - it. - - Use the \Rfunction{keys} method to extract just a few gene - identifiers and then pass those keys in to the \Rfunction{select} - method in such a way that you extract the transcript ids and - transcript starts for each. -\end{Exercise} -\begin{Solution} -<>= -library(TxDb.Hsapiens.UCSC.hg19.knownGene) -txdb <- TxDb.Hsapiens.UCSC.hg19.knownGene -txdb -columns(txdb) -keytypes(txdb) -keys <- head(keys(txdb, keytype="GENEID")) -cols <- c("TXID", "TXSTART") -select(txdb, keys=keys, columns=cols, keytype="GENEID") - -@ -\end{Solution} - -As is widely known, in addition to providing access via the -\Rfunction{select} method, \Rclass{TxDb} objects also provide access -via the more familiar \Rfunction{transcripts}, \Rfunction{exons}, -\Rfunction{cds}, \Rfunction{transcriptsBy}, \Rfunction{exonsBy} and -\Rfunction{cdsBy} methods. For those who do not yet know about these -other methods, more can be learned by seeing the vignette called: -\emph{Making and Utilizing TxDb Objects} in the -\Rpackage{GenomicFeatures} package. - -\section{Using select with EnsDb packages} - -Similar to the \Rclass{TxDb} objects/packages discussed in the -previous section, \Rclass{EnsDb} objects/packages provide genomic -coordinates of gene models along with additional annotations -(e.g. gene names, biotypes etc) but are tailored to annotations -provided by Ensembl. The central methods \Rfunction{columns}, -\Rfunction{keys}, \Rfunction{keytypes} and \Rfunction{select} are all -implemented for \Rclass{EnsDb} objects. In addition, these methods -allow also the use of the \Rclass{EnsDb} specific filtering framework -to retrieve only selected information from the database (see vignette -of the \Rpackage{ensembldb} package for more information). - -In the example below we first evaluate which columns, keys and -keytypes are available for \Rclass{EnsDb} objects and fetch then the -transcript ids, genomic start coordinate and transcript biotype for -some genes. - -<>= -library(EnsDb.Hsapiens.v75) -edb <- EnsDb.Hsapiens.v75 -edb - -## List all columns -columns(edb) - -## List all keytypes -keytypes(edb) - -## Get the first -keys <- head(keys(edb, keytype="GENEID")) - -## Get the data -select(edb, keys=keys, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), - keytype="GENEID") -@ - -We can modify the queries above to retrieve only genes encoded on -chromosome Y. To this end we use filter objects available for -\Rclass{EnsDb} objects and its methods. - -<>= -## Retrieve all gene IDs of all lincRNAs encoded on chromosome Y -linkY <- keys(edb, - filter=list(GeneBiotypeFilter("lincRNA"), SeqNameFilter("Y"))) -length(linkY) - -## We get now all transcripts for these genes. -txs <- select(edb, keys=linkY, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), - keytype="GENEID") -nrow(txs) - -## Alternatively, we could specify/pass the filters with the keys argument. -txs <- select(edb, keys=list(GeneBiotypeFilter("lincRNA"), SeqNameFilter("Y")), - columns=c("TXID", "TXSEQSTART", "TXBIOTYPE")) -nrow(txs) -@ - -The version number of R and packages loaded for generating the -vignette were: - -<>= -sessionInfo() -@ - -\end{document} From 161d09f913dba31eff04e4d533ff2288e8b3cf50 Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Thu, 6 Jul 2023 08:32:15 -0400 Subject: [PATCH 6/8] Update Rmd file --- vignettes/IntroToAnnotationPackages.Rmd | 43 ++++++++----------------- 1 file changed, 13 insertions(+), 30 deletions(-) diff --git a/vignettes/IntroToAnnotationPackages.Rmd b/vignettes/IntroToAnnotationPackages.Rmd index f1f81cc..4f04fd0 100644 --- a/vignettes/IntroToAnnotationPackages.Rmd +++ b/vignettes/IntroToAnnotationPackages.Rmd @@ -17,36 +17,18 @@ output: BiocStyle::html_document --- -```{r label = fig:dbtypes, echo = FALSE, fig.align="center", fig.cap = "Annotation Packages: the big picture", out.width = '60%'} +```{r dbtypes, fig.cap = "Annotation Packages: the big picture", echo = FALSE, out.width = '60%'} knitr::include_graphics("databaseTypes.png") ``` -```{r echo=FALSE, include=FALSE} -if (!require("BiocManager", quietly = TRUE)) - install.packages("BiocManager") - -BiocManager::install("BiocStyle", force = TRUE) -``` - - -```{r include=FALSE} -library(knitr) -opts_chunk$set(tidy=FALSE) -``` - - -```{r include=FALSE} -library(BiocStyle) -``` - *Bioconductor* provides extensive annotation resources. These can be -*genecentric*, or *genome centric*. Annotations can be provided in packages +*gene centric*, or *genome centric*. Annotations can be provided in packages curated by *Bioconductor*, or obtained from web-based resources. This vignette is primarily concerned with describing the annotation resources that are -availableas packages. More advanced users who wish to learn about how to make -newannotation packages should see the vignette titled "Creating select -Interfacesfor custom Annotation resources" from the -`r Biocpkg("AnnotationForge")` package. +available as packages. More advanced users who wish to learn about how to make +new annotation packages should see the vignette titled "Creating select +Interfaces for custom Annotation resources" from the `r +Biocpkg("AnnotationForge")` package. Gene centric `r Biocpkg("AnnotationDbi")` packages include: @@ -69,12 +51,12 @@ Biocpkg("biomaRt")` package: sequence, SNPs, and etc. The most popular annotation packages have been modified so that they can make -use of a new set of methods to more easily access their contents. These four -methods are named: `columns`, `keytypes`, `keys` and `select`. And they are +use of a new set of methods to more easily access their contents. These +four methods are named: `columns`, `keytypes`, `keys` and `select`. And they are described in this vignette. They can currently be used with all chip, organism, and `TxDb` packages along with the popular GO.db package. -For the older less popular packages, there are still conventient ways to +For the older less popular packages, there are still convenient ways to retrieve the data. The *How to use bimaps from the ".db" annotation packages* vignette in the `r Biocpkg("AnnotationDbi")` package is a key reference for learnign about how to use bimap objects. @@ -132,7 +114,8 @@ We can look at this object to learn more about it: hgu95av2.db ``` -If we want to know what kinds of data are retriveable via `select`, then we should use the `columns` method like this: +If we want to know what kinds of data are retriveable via `select`, then we +should use the `columns` method like this: ```{r columns} columns(hgu95av2.db) @@ -146,7 +129,7 @@ page describing the different fields and what they mean. help("SYMBOL") ``` -If we are curious about what kinds of fields we could potentiall use as keys to +If we are curious about what kinds of fields we could potentially use as keys to query the database, we can use the `keytypes` method. In a perfect world, this method will return values very similar to what was returned by `columns`, but in reality, some kinds of values make poor keys and so this list is often shorter. @@ -192,7 +175,7 @@ mapIds(hgu95av2.db, keys=k, column=c("GENENAME"), keytype="PROBEID") An organism level package (an 'org' package) uses a central gene identifier (e.g. Entrez Gene id) and contains mappings between this identifier and other kinds of identifiers (e.g. GenBank or Uniprot accession number, RefSeq id, -etc.). The name of an org package is always of the form org.\\.\\.db +etc.). The name of an org package is always of the form org.\\.\\.db (e.g.`r Biocpkg("org.Sc.sgd.db")`where \\ is a 2-letter abbreviation of the organism (e.g.`r Biocpkg("Sc")` for *Saccharomyces cerevisiae*) and \\ is an abbreviation (in lower-case) describing the type of central identifier (e.g. From 6c696dda7b19cab72c5b6f6d2ff96972a8c2d122 Mon Sep 17 00:00:00 2001 From: BerylKanali <50364045+BerylKanali@users.noreply.github.com> Date: Thu, 6 Jul 2023 16:02:24 +0300 Subject: [PATCH 7/8] Update DESCRIPTION --- DESCRIPTION | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/DESCRIPTION b/DESCRIPTION index 80e93e6..281a832 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -13,9 +13,10 @@ Authors@R: c( person("Marc", "Carlson", role="aut"), person("Seth", "Falcon", role="aut"), person("Nianhua", "Li", role="aut"), + person("Bioconductor Package Maintainer", role="cre", + email="maintainer@bioconductor.org"), person("Beryl", "Kanali", role="ctb", comment="Converted 'IntoToAnnotationPackages' vignette from Sweave to RMarkdown.")) -Maintainer: Bioconductor Package Maintainer Depends: R (>= 2.7.0), methods, utils, stats4, BiocGenerics (>= 0.29.2), Biobase (>= 1.17.0), IRanges Imports: DBI, RSQLite, S4Vectors (>= 0.9.25), stats, KEGGREST From dd1721367efca019c7d27394e208d8ea393b53ae Mon Sep 17 00:00:00 2001 From: BerylKanali Date: Thu, 20 Jul 2023 09:28:27 -0400 Subject: [PATCH 8/8] Update Rmd after review --- vignettes/IntroToAnnotationPackages.Rmd | 111 +++++++++++------------- 1 file changed, 53 insertions(+), 58 deletions(-) diff --git a/vignettes/IntroToAnnotationPackages.Rmd b/vignettes/IntroToAnnotationPackages.Rmd index 4f04fd0..646bc59 100644 --- a/vignettes/IntroToAnnotationPackages.Rmd +++ b/vignettes/IntroToAnnotationPackages.Rmd @@ -17,7 +17,7 @@ output: BiocStyle::html_document --- -```{r dbtypes, fig.cap = "Annotation Packages: the big picture", echo = FALSE, out.width = '60%'} +```{r dbtypes, fig.cap = "Annotation Packages: the big picture", echo = FALSE, fig.width=0.6} knitr::include_graphics("databaseTypes.png") ``` @@ -27,8 +27,8 @@ curated by *Bioconductor*, or obtained from web-based resources. This vignette is primarily concerned with describing the annotation resources that are available as packages. More advanced users who wish to learn about how to make new annotation packages should see the vignette titled "Creating select -Interfaces for custom Annotation resources" from the `r -Biocpkg("AnnotationForge")` package. +Interfaces for custom Annotation resources" from the +`r Biocpkg("AnnotationForge")` package. Gene centric `r Biocpkg("AnnotationDbi")` packages include: @@ -44,8 +44,8 @@ Genome centric `r Biocpkg("GenomicFeatures")` packages include `r Biocpkg("EnsDb.Hsapiens.v75")`. - Generic genome features: Can generate via `r Biocpkg("GenomicFeatures")` -One web-based resource accesses [biomart](http://www.biomart.org/), via the `r -Biocpkg("biomaRt")` package: +One web-based resource accesses [biomart](http://www.biomart.org/), via the +`r Biocpkg("biomaRt")` package: - Query web-based \`biomart' resource for genes, sequence, SNPs, and etc. @@ -54,7 +54,7 @@ The most popular annotation packages have been modified so that they can make use of a new set of methods to more easily access their contents. These four methods are named: `columns`, `keytypes`, `keys` and `select`. And they are described in this vignette. They can currently be used with all chip, organism, -and `TxDb` packages along with the popular GO.db package. +and `TxDb` packages along with the popular `r Biocpkg("GO.db")` package. For the older less popular packages, there are still convenient ways to retrieve the data. The *How to use bimaps from the ".db" annotation packages* @@ -71,27 +71,27 @@ are based on have not themselves been updated. As previously mentioned, a new set of methods have been added that allow a simpler way of extracting identifier based annotations. All the annotation packages that support these new methods expose an object named exactly the same -as the package itself. These objects are collectively called `AnnotationDb` +as the package itself. These objects are collectively called *AnnotationDb* objects for the class that they all inherit from. The more specific classes (the -ones that you will actually see in the wild) have names like `OrgDb`, `ChipDb` -or `TxDb` objects. These names correspond to the kind of package (and underlying +ones that you will actually see in the wild) have names like *OrgDb*, *ChipDb* +or *TxDb* objects. These names correspond to the kind of package (and underlying schema) being represented. The methods that can be applied to all of these objects are `columns`, `keys`, `keytypes` and `select`. In addition, another accessor has recently been added which allows extraction of -one column at at time. the `mapIds` method allows users to extract data into +one column at a time. the `mapIds` method allows users to extract data into either a named character vector, a list or even a SimpleCharacterList. This -method should work with all the different kinds of `AnnotationDb` objects +method should work with all the different kinds of *AnnotationDb* objects described below. # ChipDb objects and the select method -An extremely common kind of Annotation package is the so called platform based -or chip based package type. This package is intended to make the manufacturer -labels for a series of probes or probesets to a wide range of gene-based -features. A package of this kind will load an `ChipDb` object. Below is a set of -examples to show how you might use the standard 4 methods to interact with an -object of this type. +An extremely common kind of `r Biocpkg("Annotation")` package is the so called +platform based or chip based package type. This package is intended to make the +manufacturer labels for a series of probes or probesets to a wide range of +gene-based features. A package of this kind will load an *ChipDb* object. Below +is a set of examples to show how you might use the standard 4 methods to +interact with an object of this type. First we need to load the package: @@ -182,22 +182,23 @@ abbreviation (in lower-case) describing the type of central identifier (e.g. `r Biocpkg("sgd")` for gene identifiers assigned by the Saccharomyces Genome Database, or `r Biocpkg("eg")` for Entrez Gene ids). -Just as the chip packages load a `ChipDb` object, the org packages will load a -`OrgDb` object. The following exercise should acquaint you with the use of these +Just as the chip packages load a *ChipDb* object, the org packages will load a +*OrgDb* object. The following exercise should acquaint you with the use of these methods in the context of an organism package. **Exercise 1** -Display the `OrgDb` object for the `r Biocpkg("org.Hs.eg.db")` package. +*Display the OrgDb object for the `r Biocpkg("org.Hs.eg.db")` +package.* -Use the `columns` method to discover which sorts of annotations can be extracted +*Use the `columns` method to discover which sorts of annotations can be extracted from it. Is this the same as the result from the `keytypes` method? Use the -`keytypes` method to find out. +`keytypes` method to find out.* -Finally, use the `keys` method to extract UNIPROT identifiers and then pass +*Finally, use the `keys` method to extract UNIPROT identifiers and then pass those keys in to the `select` method in such a way that you extract the gene symbol and KEGG pathway information for each. Use the help system as needed to -learn which values to pass in to columns in order to achieve this. +learn which values to pass in to columns in order to achieve this.* **Solution:** @@ -222,20 +223,21 @@ hlep you to understand how that should generally work. **Exercise 2** -Please run the following code snippet (which will load a fake data result that I -have provided for the purposes of illustration): +*Please run the following code snippet (which will load a fake data result that +I have provided for the purposes of illustration):* ```{r selectData} load(system.file("extdata", "resultTable.Rda", package="AnnotationDbi")) head(resultTable) ``` -The rownames of this table happen to provide entrez gene identifiers for each +*The rownames of this table happen to provide entrez gene identifiers for each row (for human). Find the gene symbol and gene name for each of the rows in -resultTable and then use the merge method to attach those annotations to it. +resultTable and then use the merge method to attach those annotations to it.* **Solution:** + ```{r} annots <- select(org.Hs.eg.db, keys=rownames(resultTable), columns=c("SYMBOL","GENENAME"), keytype="ENTREZID") @@ -246,10 +248,10 @@ head(resultTable) # Using select with GO.db -When you load the GO.db package, a `GODb` object is also loaded. This allows you -to use the `columns`, `keys`, `keytypes` and `select` methods on the contents of -the GO ontology. So if for example, you had a few GO IDs and wanted to know more -about it, you could do it like this: +When you load the ` r Biocpkg("GO.db")` package, a *GODb* object is also loaded. +This allows you to use the `columns`, `keys`, `keytypes` and `select` methods on +the contents of the GO ontology. So if for example, you had a few GO IDs and +wanted to know more about it, you could do it like this: ```{r selectGO} library(GO.db) @@ -259,24 +261,24 @@ select(GO.db, keys=GOIDs, columns="DEFINITION", keytype="GOID") # Using select with TxDb packages -A `TxDb` package (a 'TxDb' package) connects a set of genomic coordinates to -various transcript oriented features. The package can also contain Identifiers -to features such as genes and transcripts, and the internal schema describes the -relationships between these different elements. All TxDb containing packages -follow a specific naming scheme that tells where the data came from as well as -which build of the genome it comes from. +A `r Biocpkg("TxDb")` package (a 'TxDb' package) connects a set of genomic +coordinates to various transcript oriented features. The package can also +contain Identifiers to features such as genes and transcripts, and the internal +schema describes the relationships between these different elements. All TxDb +containing packages follow a specific naming scheme that tells where the data +came from as well as which build of the genome it comes from. **Exercise 3** -Display the `TxDb` object for the `r Biocpkg("TxDb.Hsapiens.UCSC.hg19.knownGene")` -package. +*Display the TxDb object for the `r Biocpkg("TxDb.Hsapiens.UCSC.hg19.knownGene")` +package.* -As before, use the `columns` and `keytypes` methods to discover which sorts of -annotations can be extracted from it. +*As before, use the `columns` and `keytypes` methods to discover which sorts of +annotations can be extracted from it.* -Use the `keys` method to extract just a few gene identifiers and then pass those +*Use the `keys` method to extract just a few gene identifiers and then pass those keys in to the `select` method in such a way that you extract the transcript ids -and transcript starts for each. +and transcript starts for each.* **Solution:** @@ -292,7 +294,7 @@ select(txdb, keys=keys, columns=cols, keytype="GENEID") ``` As is widely known, in addition to providing access via the `select` method, -`TxDb` objects also provide access via the more familiar `transcripts`, `exons`, +*TxDb* objects also provide access via the more familiar `transcripts`, `exons`, `cds`, `transcriptsBy`, `exonsBy` and `cdsBy` methods. For those who do not yet know about these other methods, more can be learned by seeing the vignette called: *Making and Utilizing TxDb Objects* in the @@ -300,26 +302,19 @@ called: *Making and Utilizing TxDb Objects* in the # Using select with EnsDb packages -Similar to the `TxDb` objects/packages discussed in the previous section, -`EnsDb` objects/packages provide genomic coordinates of gene models along with +Similar to the *TxDb* objects/packages discussed in the previous section, +*EnsDb* objects/packages provide genomic coordinates of gene models along with additional annotations (e.g. gene names, biotypes etc) but are tailored to annotations provided by Ensembl. The central methods `columns`, `keys`, -`keytypes` and `select` are all implemented for `EnsDb` objects. In addition, -these methods allow also the use of the `EnsDb` specific filtering framework to +`keytypes` and `select` are all implemented for *EnsD* objects. In addition, +these methods allow also the use of the *EnsDb* specific filtering framework to retrieve only selected information from the database (see vignette of the `r Biocpkg("ensembldb")` package for more information). In the example below we first evaluate which columns, keys and keytypes are -available for `EnsDb` objects and fetch then the transcript ids, genomic start +available for *EnsDb* objects and fetch then the transcript ids, genomic start coordinate and transcript biotype for some genes. -```{r} -if (!require("BiocManager", quietly = TRUE)) - install.packages("BiocManager") - -BiocManager::install("EnsDb.Hsapiens.v75") -``` - ```{r selectEnsDb} library(EnsDb.Hsapiens.v75) edb <- EnsDb.Hsapiens.v75 @@ -340,7 +335,7 @@ select(edb, keys=keys, columns=c("TXID", "TXSEQSTART", "TXBIOTYPE"), ``` We can modify the queries above to retrieve only genes encoded on chromosome Y. -To this end we use filter objects available for `EnsDb` objects and its methods. +To this end we use filter objects available for *EnsDb* objects and its methods. ```{r selectEnsDb.Y} ## Retrieve all gene IDs of all lincRNAs encoded on chromosome Y