MultiDb and OrganismDb objects

Description

The OrganismDb class is a container for storing knowledge about existing Annotation packages and the relationships between these resources. The purpose of this object and it's associated methods is to provide a means by which users can conveniently query for data from several different annotation resources at the same time using a familiar interface.

The supporting methods select , columns and keys are used together to extract data from an OrganismDb object in a manner that should be consistent with how these are used on the supporting annotation resources.

The family of seqinfo style getters ( seqinfo , seqlevels , seqlengths , isCircular , genome , and seqnameStyle ) is also supported for OrganismDb objects provided that the object in question has an embedded TxDb object.

Seealso

• AnnotationDb-class for more descriptsion of methods select , keytypes , keys and columns .

• makeOrganismPackage for functions used to generate an OrganismDb based package.

• rangeBasedAccessors for the range based methods used in extracting data from a OrganismDb object.

• list("GenomeInfoDb") .

• list("seqlevels") .

• list("seqlengths") .

• list("isCircular") .

• list("genome") .

Author

Marc Carlson

Examples

## load a package that creates an OrganismDb
library(Homo.sapiens)
ls(2)
## then the methods can be used on this object.
columns <- columns(Homo.sapiens)[c(7,10,11,12)]
keys <- head(keys(org.Hs.eg.db, "ENTREZID"))
keytype <- "ENTREZID"
res <- select(Homo.sapiens, keys, columns, keytype)
head(res)
res <-  mapIds(Homo.sapiens, keys=c('1','10'), column='ALIAS',
keytype='ENTREZID',  multiVals="CharacterList")

## get symbols for ranges in question:
ranges <-  GRanges(seqnames=Rle(c('chr11'), c(2)),
IRanges(start=c(107899550, 108025550),
end=c(108291889, 108050000)), strand='*',
seqinfo=seqinfo(Homo.sapiens))
selectByRanges(Homo.sapiens, ranges, 'SYMBOL')

## Or extract the gene model for the 'A1BG' gene:
selectRangesById(Homo.sapiens, 'A1BG', keytype='SYMBOL')


## Get the DB connections or DB file paths associated with those for
## each.
dbconn(Homo.sapiens)
dbfile(Homo.sapiens)

## extract the taxonomyId
taxonomyId(Homo.sapiens)

##extract the resources
resources(Homo.sapiens)

Map range coordinates between transcripts and genome space

Description

Map range coordinates between features in the transcriptome and genome (reference) space.

See ? in the GenomicAlignments package for mapping coordinates between reads (local) and genome (reference) space using a CIGAR alignment.

Usage

list(list("mapToTranscripts"), list("ANY,MultiDb"))(x, transcripts,
          ignore.strand = TRUE,
          extractor.fun = GenomicFeatures::transcripts, ...)

Arguments

• transcripts ## default

• exons

• cds

• genes

• promoters

• disjointExons

• microRNAs

• tRNAs

• transcriptsBy

• exonsBy

• cdsBy

• intronsByTranscript

• fiveUTRsByTranscript

• threeUTRsByTranscript
  |list() | Additional arguments passed to extractor.fun functions. |

Details

• list(list("mapToTranscripts")) list(" ", " The genomic range in ", list("x"), " is mapped to the local position in the ", " ", list("transcripts"), " ranges. A successful mapping occurs when ", list("x"), " ", " is completely within the ", list("transcripts"), " range, equivalent to: ", " ", list(" ", " findOverlaps(..., type="within") ", " "), " ", " Transcriptome-based coordinates start counting at 1 at the beginning ", " of the ", list("transcripts"), " range and return positions where ", list("x"), " ", " was aligned. The seqlevels of the return object are taken from the ", " ", list("transcripts"), " object and should be transcript names. In this ", " direction, mapping is attempted between all elements of ", list("x"), " and ", " all elements of ", list("transcripts"), ". ", " ")

Value

An object the same class as x .

Parallel methods return an object the same shape as x . Ranges that cannot be mapped (out of bounds or strand mismatch) are returned as zero-width ranges starting at 0 with a seqname of "UNMAPPED".

Non-parallel methods return an object that varies in length similar to a Hits object. The result only contains mapped records, strand mismatch and out of bound ranges are not returned. xHits and transcriptsHits metadata columns indicate the elements of x and transcripts used in the mapping.

When present, names from x are propagated to the output. When mapping to transcript coordinates, seqlevels of the output are the names on the transcripts object; most often these will be transcript names. When mapping to the genome, seqlevels of the output are the seqlevels of transcripts which are usually chromosome names.

Seealso

• list("mapToTranscripts") .

Author

V. Obenchain, M. Lawrence and H. Pagès; ported to work with OrganismDbi by Marc Carlson

Examples

## ---------------------------------------------------------------------
## A. Basic Use
## ---------------------------------------------------------------------

library(Homo.sapiens)
x <- GRanges("chr5",
IRanges(c(173315331,174151575), width=400,
names=LETTERS[1:2]))

## Map to transcript coordinates:
mapToTranscripts(x, Homo.sapiens)

Make a OrganismDb object from annotations available on a BioMart database

Description

The makeOrganismDbFromBiomart function allows the user to make a OrganismDb object from transcript annotations available on a BioMart database. This object has all the benefits of a TxDb, plus an associated OrgDb and GODb object.

Usage

makeOrganismDbFromBiomart(biomart="ENSEMBL_MART_ENSEMBL",
                    dataset="hsapiens_gene_ensembl",
                    transcript_ids=NULL,
                    circ_seqs=DEFAULT_CIRC_SEQS,
                    filter="",
                    id_prefix="ensembl_",
                    host="www.ensembl.org",
                    port=80,
                    miRBaseBuild=NA,
                    keytype = "ENSEMBL",
                    orgdb = NA)

Arguments

Details

makeOrganismDbFromBiomart is a convenience function that feeds data from a BioMart database to the lower level OrganismDb constructor. See ? for a similar function that feeds data from the UCSC source.

The listMarts function from the biomaRt package can be used to list all public BioMart databases. Not all databases returned by this function contain datasets that are compatible with (i.e. understood by) makeOrganismDbFromBiomart . Here is a list of datasets known to be compatible (updated on Sep 24, 2014):

• All the datasets in the main Ensembl database: use biomart="ensembl" .

• All the datasets in the Ensembl Fungi database: use biomart="fungi_mart_XX" where XX is the release version of the database e.g. "fungi_mart_22" .

• All the datasets in the Ensembl Metazoa database: use biomart="metazoa_mart_XX" where XX is the release version of the database e.g. "metazoa_mart_22" .

• All the datasets in the Ensembl Plants database: use biomart="plants_mart_XX" where XX is the release version of the database e.g. "plants_mart_22" .

• All the datasets in the Ensembl Protists database: use biomart="protists_mart_XX" where XX is the release version of the database e.g. "protists_mart_22" .

• All the datasets in the Gramene Mart: use biomart="ENSEMBL_MART_PLANT" .
  Not all these datasets have CDS information.

Value

A OrganismDb object.

Seealso

• makeOrganismDbFromUCSC for convenient ways to make a OrganismDb object from UCSC online resources.

• The listMarts , useMart , and listDatasets functions in the biomaRt package.

• DEFAULT_CIRC_SEQS .

• The supportedMiRBaseBuildValues function for listing all the possible values for the miRBaseBuild argument.

• The OrganismDb class.

Author

M. Carlson

Examples

## Discover which datasets are available in the "ensembl" BioMart
## database:
library(biomaRt)
head(listDatasets(useMart("ensembl")))

## Retrieving an incomplete transcript dataset for Human from the
## "ensembl" BioMart database:
transcript_ids <- c(
"ENST00000013894",
"ENST00000268655",
"ENST00000313243",
"ENST00000435657",
"ENST00000384428",
"ENST00000478783"
)
odb <- makeOrganismDbFromBiomart(transcript_ids=transcript_ids)
odb  # note that these annotations match the GRCh38 genome assembly

## Now what if we want to use another mirror?  We might make use of the
## new host argument.  But wait!  If we use biomaRt, we can see that
## this host has named the mart differently!
listMarts(host="useast.ensembl.org")
## Therefore we must also change the name passed into the "mart"
## argument thusly:
try(
odb <- makeOrganismDbFromBiomart(biomart="ENSEMBL_MART_ENSEMBL",
transcript_ids=transcript_ids,
host="useast.ensembl.org")
)
odb

Make an OrganismDb object from an existing TxDb object.

Description

The makeOrganismDbFromTxDb function allows the user to make a OrganismDb object from an existing TxDb object.

Usage

makeOrganismDbFromTxDb(txdb, keytype=NA, orgdb=NA)

Arguments

Details

makeOrganismDbFromTxDb is a convenience function that processes a TxDb object and pairs it up with GO.db and an appropriate OrgDb object to make a OrganismDb object. See ? and ? for a similar function that feeds data from either a BioMart or UCSC.

Value

A OrganismDb object.

Seealso

• makeOrganismDbFromBiomart for convenient ways to make a OrganismDb object from BioMart online resources.

• The OrganismDb class.

Author

M. Carlson

Examples

## lets start with a txdb object
transcript_ids <- c(
"uc009uzf.1",
"uc009uzg.1",
"uc009uzh.1",
"uc009uzi.1",
"uc009uzj.1"
)
txdbMouse <- makeTxDbFromUCSC(genome="mm9", tablename="knownGene",
transcript_ids=transcript_ids)

## Using that, we can call our function to promote it to an OrgDb object:
odb <- makeOrganismDbFromTxDb(txdb=txdbMouse)

columns(odb)

Make a OrganismDb object from annotations available at the UCSC Genome Browser

Description

The makeOrganismDbFromUCSC function allows the user to make a OrganismDb object from transcript annotations available at the UCSC Genome Browser.

Usage

makeOrganismDbFromUCSC(
        genome="hg19",
        tablename="knownGene",
        transcript_ids=NULL,
        circ_seqs=DEFAULT_CIRC_SEQS,
        url="http://genome.ucsc.edu/cgi-bin/",
        goldenPath_url="http://hgdownload.cse.ucsc.edu/goldenPath",
        miRBaseBuild=NA)

Arguments

Details

makeOrganismDbFromUCSC is a convenience function that feeds data from the UCSC source to the lower level OrganismDb function. See ? for a similar function that feeds data from a BioMart database.

Value

A OrganismDb object.

Seealso

• makeOrganismDbFromBiomart for convenient ways to make a OrganismDb object from BioMart online resources.

• ucscGenomes in the rtracklayer package.

• DEFAULT_CIRC_SEQS .

• The supportedMiRBaseBuildValues function for listing all the possible values for the miRBaseBuild argument.

• The OrganismDb class.

Author

M. Carlson

Examples

## Display the list of genomes available at UCSC:
library(rtracklayer)
library(RMariaDB)
ucscGenomes()[ , "db"]

## Display the list of tables supported by makeOrganismDbFromUCSC():
supportedUCSCtables()

ontrun{
## Retrieving a full transcript dataset for Yeast from UCSC:
odb1 <- makeOrganismDbFromUCSC(genome="sacCer2", tablename="ensGene")
}

## Retrieving an incomplete transcript dataset for Mouse from UCSC
## (only transcripts linked to Entrez Gene ID 22290):
transcript_ids <- c(
"uc009uzf.1",
"uc009uzg.1",
"uc009uzh.1",
"uc009uzi.1",
"uc009uzj.1"
)

odb2 <- makeOrganismDbFromUCSC(genome="mm9", tablename="knownGene",
transcript_ids=transcript_ids)
odb2

Making OrganismDb packages from annotation packages.

Description

makeOrganismPackage is a method that generates a package that will load an appropriate annotationOrganismDb object that will in turn point to existing annotation packages.

Usage

makeOrganismPackage (pkgname,
                     graphData,
                     organism,
                     version,
                     maintainer,
                     author,
                     destDir,
                     license="Artistic-2.0")

Arguments

Details

The purpose of this method is to create a special package that will depend on existing annotation packages and which will load a special annotationOrganismDb object that will allow proper dispatch of special select methods. These methods will allow the user to easily query across multiple annotation resources via information contained by the annotationOrganismDb object. Because the end result will be a package that treats all the data mapped together as a single source, the user is encouraged to take extra care to ensure that the different packages used are from the same build etc.

Value

A special package to load an OrganismDb object.

Seealso

OrganismDb

Author

M. Carlson

Examples

## set up the list with the relevant relationships:
gd <- list(join1 = c(GO.db="GOID", org.Hs.eg.db="GO"),
join2 = c(org.Hs.eg.db="ENTREZID",
TxDb.Hsapiens.UCSC.hg19.knownGene="GENEID"))

## sets up a temporary directory for this example
## (users won't need to do this step)
destination <- tempfile()
dir.create(destination)

## makes an Organism package for human called Homo.sapiens
if(interactive()){
makeOrganismPackage(pkgname = "Homo.sapiens",
graphData = gd,
organism = "Homo sapiens",
version = "1.0.0",
maintainer = "Bioconductor Package Maintainer <maintainer@bioconductor.org>",
author = "Bioconductor Core Team",
destDir = destination,
license = "Artistic-2.0")
}

Extract genomic features from an object

Description

Generic functions to extract genomic features from an object. This page documents the methods for OrganismDb objects only.

Usage

list(list("transcripts"), list("MultiDb"))(x, columns=c("TXID", "TXNAME"), filter=NULL)
list(list("exons"), list("MultiDb"))(x, columns="EXONID", filter=NULL)
list(list("cds"), list("MultiDb"))(x, columns="CDSID", filter=NULL)
list(list("genes"), list("MultiDb"))(x, columns="GENEID", filter=NULL)
list(list("transcriptsBy"), list("MultiDb"))(x, by, columns, use.names=FALSE,
                                     outerMcols=FALSE)
list(list("exonsBy"), list("MultiDb"))(x, by, columns, use.names=FALSE, outerMcols=FALSE)
list(list("cdsBy"), list("MultiDb"))(x, by, columns, use.names=FALSE, outerMcols=FALSE)
list(list("getTxDbIfAvailable"), list("MultiDb"))(x, ...)
% S4method{columns}{MultiDb}(x)% new stuff: (replace TxDb with MultiDb)list(list("asBED"), list("MultiDb"))(x)
list(list("asGFF"), list("MultiDb"))(x)
list(list("disjointExons"), list("MultiDb"))(x, aggregateGenes=FALSE, 
              includeTranscripts=TRUE, ...) 
list(list("microRNAs"), list("MultiDb"))(x)
list(list("tRNAs"), list("MultiDb"))(x)
list(list("promoters"), list("MultiDb"))(x, upstream=2000, downstream=200, use.names=TRUE, ...)
list(list("distance"), list("GenomicRanges,MultiDb"))(x, y, ignore.strand=FALSE,
    ..., id, type=c("gene", "tx", "exon", "cds"))
list(list("extractTranscriptSeqs"), list("BSgenome"))(x, transcripts, strand = "+")
list(list("extractUpstreamSeqs"), list("MultiDb"))(x, genes, width=1000, exclude.seqlevels=NULL)
list(list("intronsByTranscript"), list("MultiDb"))(x, use.names=FALSE)
list(list("fiveUTRsByTranscript"), list("MultiDb"))(x, use.names=FALSE)
list(list("threeUTRsByTranscript"), list("MultiDb"))(x, use.names=FALSE)
list(list("isActiveSeq"), list("MultiDb"))(x)

Arguments

Details

These are the range based functions for extracting transcript information from a MultiDb object.

Value

a GRanges or GRangesList object

Seealso

• MultiDb-class for how to use the simple "select" interface to extract information from a MultiDb object.

• transcripts for the original transcripts method and related methods.

• transcriptsBy for the original transcriptsBy method and related methods.

Author

M. Carlson

Examples

## extracting all transcripts from Homo.sapiens with some extra metadata
library(Homo.sapiens)
cols = c("TXNAME","SYMBOL")
res <- transcripts(Homo.sapiens, columns=cols)

## extracting all transcripts from Homo.sapiens, grouped by gene and
## with extra metadata
res <- transcriptsBy(Homo.sapiens, by="gene", columns=cols)

## list possible values for columns argument:
columns(Homo.sapiens)

## Get the TxDb from an MultiDb object (if it's available)
getTxDbIfAvailable(Homo.sapiens)

## Other functions listed above should work in way similar to their TxDb
## counterparts.  So for example:
promoters(Homo.sapiens)
## Should give the same value as:
promoters(getTxDbIfAvailable(Homo.sapiens))