AnnotationHubResource objects and their related methods and functions

Description

This class is utilized internally. AnnotationHubResources are created as an intermediate 'on the fly' process when loading a resource. It's accessor methods are used internally.

Seealso

AnnotationHub-class

Author

Bioconductor Core Team

AnnotationHub objects and their related methods and functions

Description

Use AnnotationHub to interact with Bioconductor's AnnotationHub service. Query the instance to discover and use resources that are of interest, and then easily download and import the resource into R for immediate use.

Use AnnotationHub() to retrieve information about all records in the hub. If working offline, add argument localHub=TRUE to work with a local, non-updated hub; It will only have resources available that have previously been downloaded.

Discover records in a hub using mcols() , query() , subset() , [ , and display() .

Retrieve individual records using [[ . On first use of a resource, the corresponding files or other hub resources are downloaded from the internet to a local cache. On this and all subsequent uses the files are quickly input from the cache into the R session. If a user wants to download the file again and not use the cache version add the argument force=TRUE .

AnnotationHub records can be added (and sometimes removed) at any time. snapshotDate() restricts hub records to those available at the time of the snapshot. possibleDates() lists snapshot dates valid for the current version of Bioconductor. You can check the status of a past record using recordStatus() .

The location of the local cache can be found (and updated) with getAnnotationHubCache and setAnnotationHubCache ; removeCache removes all cache resources.

Author

Martin Morgan, Marc Carlson, Sonali Arora, Dan Tenenbaum, and Lori Shepherd

Examples

## create an AnnotationHub object
library(AnnotationHub)
ah = AnnotationHub()

## Summary of available records
ah

## Detail for a single record
ah[1]

## and what is the date we are using?
snapshotDate(ah)

## how many resources?
length(ah)

## from which resources, is data available?
head(sort(table(ah$dataprovider), decreasing=TRUE))

## from which species, is data available ?
head(sort(table(ah$species),decreasing=TRUE))

## what web service and local cache does this AnnotationHub point to?
hubUrl(ah)
hubCache(ah)

### Examples ###

## One can  search the hub for multiple strings
ahs2 <- query(ah, c("GTF", "77","Ensembl", "Homo sapiens"))

## information about the file can be retrieved using
ahs2[1]

## one can further extract information from this show method
## like the sourceurl using:
ahs2$sourceurl
ahs2$description
ahs2$title

## We can download a file by name like this (using a list semantic):
gr <- ahs2[[1]]
## And we can also extract it by the names like this:
res <- ah[["AH28812"]]

## the gtf file is returned as a GenomicRanges object and contains
## data about which organism it belongs to, its seqlevels and seqlengths
seqinfo(gr)

## each GenomicRanges contains a metadata slot which can be used to get
## the name of the hub object and other associated metadata.
metadata(gr)
ah[metadata(gr)$AnnotationHubName]

## And we can also use "[" to restrict the things that are in the
## AnnotationHub object (by position, character, or logical vector).
## Here is a demo of position:
subHub <- ah[1:3]

if(interactive()) {
## Display method involves user interaction through web interface
ah2 <- display(ah)
}

## recordStatus
recordStatus(ah, "TEST")
recordStatus(ah, "AH7220")

Light-weight AnnotationHub 3.0 Client

Description

Client for discovery and retrieval of Bioconductor annotation resources.

Seealso

AnnotationHub-class

Author

Martin Morgan mtmorgan@fhcrc.org

Examples

library(AnnotationHub)
hub = AnnotationHub()
hub

Get information for selected ids

Description

Gets information from the Hub database for the given selection of ids. The information collected is ah_id, fetch_id, title, rdataclass, availablitiy status, biocversion when added, date when added, date when removed, and file size.

Usage

getInfoOnIds(hub, ids)

Arguments

Value

data.frame of information for selected ids. The information collected is ah_id, fetch_id, title, rdataclass, availablitiy status, biocversion when added, date when added, date when removed, and file size.

Seealso

AnnotationHub , convertHub

Author

Lori Shepherd

Examples

getInfoOnIds(hub, c("AH2","AH5012"))
getInfoOnIds(hub, 69303)

# If using in conjunction with convertHub,
#
# File not downloaded options:
#

# 1. Use the original file. In reality the file is not going to be
updated or should change. The original file does not need to be
tracked and could now be referenced directly for usage. It will not be
available in the Hub.

# 2. You could simply download the file for use
# The file will not change and not be updated so its static download not
# in the cache is fine

# You could type the following into a web browswer
"https://annotationhub.bioconductor.org/fetch/69303"

# or in R
httr::GET("https://annotationhub.bioconductor.org/fetch/69303",
write_disk(<pathToSave/69303>, overwrite=FALSE))

# 3. To add to a hub cache (not recommended)
hub <- AnnotationHub()
bfc <- AnnotationHub:::.get_cache(hub)

# the hub creates the rname is in the format of 'ah_id : fetch_id'
bfcadd(bfc, fpath="https://annotationhub.bioconductor.org/fetch/69303",
rname="AH62557 : 69303")

Convert old Hub to new Hub structure

Description

The Hub class was updated to utilize BiocFileCache to allow for file level caching control. This update changed the way files were stored and named. As a convenience for AnnotationHub and ExperimentHub we have provided this helper function to try to re-download files and add them into the BiocFileCache tracking database.

Usage

convertHub(oldcachepath=NULL,
           newcachepath=NULL,
           hubType=c("AnnotationHub", "ExperimentHub"),
           proxy=getAnnotationHubOption("PROXY"),
           max.downloads=getAnnotationHubOption("MAX_DOWNLOADS"),
           force=FALSE, verbose=TRUE)

Arguments

Value

character(1). File path of new cache location. If verbose also prints status messages for downloading files and any files that were not redownloaded.

Seealso

AnnotationHub , getAnnotationHubOption , getInfoOnIds

Author

Lori Shepherd

Examples

# To transition over from old default to new default location
convertHub()

Get and set options for default AnnotationHub behavior.

Description

These functions get or set options for creation of new AnnotationHub instances.

Usage

getAnnotationHubOption(arg)
setAnnotationHubOption(arg, value)

Arguments

Details

Supported options include:

list(" ", " ", " ", list(list(list("URL"), ":"), list("character(1). The base URL of the annotation ", " hub. Default: ", list("https://annotationhub.bioconductor.org"))), " ", " ", " ", list(list(list("CACHE"), ":"), list("character(1). The location of the hub ", " cache. Default: ", list("AnnotationHub"), " in the user's directory ", " established by ", list("rappdir::user_cache_dir"), ".")), " ", " ", " ", list(list(list("MAX_DOWNLOADS"), ":"), list("numeric(1). The integer number of ",

"      downloads allowed before triggering an error. This is to help

", " avoid accidental download of a large number of AnnotationHub ", " members.")), " ", " ", " ", list(list(list("PROXY"), ":"), list(list("request"), " object returned by ", " ", list("httr::use_proxy()"), ". The ", list("request"), " object describes a proxy ", " connection allowing Internet access, usually through a restrictive ", " firewall. Setting this option sends all AnnotationHub requests through ",

"      the proxy. Default: NULL.

", " ", " In ", list("setHubOption("PROXY", value)"), ", ", list("value"), " can be one of NULL, ", " a ", list("request"), " object returned by ", list("httr::use_proxy()"), ", or a ", " well-formed URL as character(1). The URL can be completely ", " specified by ", list("http://username:password@proxy.dom.com:8080"), "; ", " ", list("username:password"), " and port (e.g. ", list(":8080"), ") are optional.")), " ", " ", " ",

list(list(list("TESTING"), ":"), list("logical(1). TRUE/FALSE should the AnnotationHub

", " testing environment be used. AnnotationHub does automatic ", " filtering particularly with regards to OrgDbs. The ", " ", list("TESTING=TRUE"), " setting will allow for all OrgDbs for a given ", " devel version to also be displayed. (This option should really ", " only be set by a OrgDb contributing maintainer for testing and ", " debugging). Default: FALSE.")), " ",

"

", " ")

Default values may also be determined by system and global R environment variables visible list("before") the package is loaded. Use options or variables preceeded by list("ANNOTATIONHUB") , e.g., options(ANNOTATION_HUB_MAX_DOWNLOADS=10) prior to package load sets the default number of downloads to 10.

Value

The requested or successfully set option.

Author

Martin Morgan mtmorgan@fhcrc.org and Lori Shepherd

Examples

getAnnotationHubOption("URL")
setAnnotationHubOption("CACHE", "~/.myHub")

Utility functions for discovering package-specific Hub resources.

Description

List and load resources from ExperimentHub filtered by package name and optional search terms. Not Implemented for AnnotationHub.

Details

Currently listResources and loadResources are only meaningful for ExperimentHub objects.

Utility function to list currently available dispatchClass.

Description

When submitting resources to AnnotationHub or ExperimentHub a valid DispatchClass field must be specified in the inst/extdata/metadata.csv file for each resource. This list the currently available DispatchClass values and briefly how that class loads a resource. If your resource does not qualify for one of these methods contact Lori Shepherd Lori.Shepherd@RoswellPark.org to request a new DispatchClass be added

Author

Lori Shepherd

Examples

DispatchClassList()