2.1 Handling GEO (Gene Expression Omnibus) Metadata

First, it is necessary to obtain and get a connection to the SQLite database. connectToGEODB returns a connection to the database given the path of the SQLite file. If the latter is missing, it is automatically downloaded into the current working directory. Because of the size of these files (0.5-4GB), the results of the queries illustrated below are available into Onassis for subsequent analysis illustrated in this document. Then, the getGEOmetadata function can be used to retrieve the metadata of specific GEO samples, taking as minimal parameters the connection to the database and one of the experiment types available. Optionally it is possible to specify the organism and the platform.

## Running this function might take long time if the database has to be downloaded.
geo_con <- connectToGEODB(system.file(getwd(), 'GEOmetadb.sqlite'))

#Showing the experiment types available in GEO
experiments <- experiment_types(geo_con)

#Showing the organism types available in GEO
species <- organism_types(geo_con)

#Retrieving the metadata associated to experiment type "Methylation profiling by high througput sequencing"
meth_metadata <- getGEOMetadata(geo_con, experiment_type='Methylation profiling by high throughput sequencing', organism = 'Homo sapiens')

#Retrieving Human gene expression metadata, knowing the GEO platform identifier, e.g. the Affymetrix Human Genome U133 Plus 2.0 Array
expression <- getGEOMetadata(geo_con, experiment_type='Expression profiling by array', gpl='GPL570')

Some of the experiment types available are the following:

Some of the organisms available are the following:

To avoid installing GEOmetadb meth_metadata was previously saved and can be loaded from Onassis:

meth_metadata <- readRDS(system.file('extdata', 'vignette_data', 'GEOmethylation.rds', package='Onassis'))

2.2 Handling SRA (Sequence Read Archive) Metadata

As for GEO, the getSRAMetadata function allows the retrieval of metadata of high througput sequencing data stored in SRA through the BiocStyle::Biocpkg("SRAdb") package. To facilitate the retrieval of experiment types in SRA, the Onassis function library_strategies can be used. Filters for the sample’s material (GENOMIC, TRANSCRIPTOMIC, METAGENOMIC…), the species and the center hosting the data are allowed. For example, to obtain SRA metadata of ChIP-Seq human samples and Bisulfite sequencing samples the following code can be used.

# Connection to the SRAmetadb and potential download of the sqlite file
sra_con <- connectToSRADB()

# Query for the ChIP-Seq experiments contained in GEO for human samples 
sra_chip_seq <- getSRAMetadata(sra_con, library_strategy='ChIP-Seq', library_source='GENOMIC', taxon_id=9606, center_name='GEO')

# The following example allows to retrieve Bisulfite sequencing samples' metadata.
bisulfite_seq <- getSRAMetadata(sra_con, library_strategy='Bisulfite-Seq', library_source='GENOMIC', taxon_id=9606, center_name='GEO' )

To avoid installing GEOmetadb sra_chip_seq was previously saved and can be loaded from Onassis:

sra_chip_seq <- readRDS(system.file('extdata', 'vignette_data', 'GEO_human_chip.rds',  package='Onassis'))

3.1 Data preparation

Input text can be provided as:

• The path of a directory containing named documents (findEntities method).
• The path of a single file containing multiple documents. In this case each row contains the name/identifier of the document followed by a ‘|’ separator and the text to annotate (findEntities method).
• A data frame. In this case each row represents a document, first column has to be the document identifier, and the remaining columns will be combined and contain the text to analyze (annotateDF method). This option can be conveniently used with the metadata retrieved from GEOmetadb and SRAdb, possibly selecting a subset of columns.

3.2 Creation of a Conceptmapper Dictionary

Conceptmapper dictionaries are XML files with a set of entries specified by the xml tag <token> with a canonical name (the name of the entry) and one or more variants (synonyms). Additional properties are allowed. The following code represents a sample of the Conceptmapper dictionary obtained from the Brenda tissue ontology.

   <?xml version="1.0" encoding="UTF-8" ?>
   <synonym>
      <token id="http://purl.obolibrary.org/obo/BTO_0005205" canonical="cerebral artery">
          <variant base="cerebral artery"/>
      </token>
      <token id="http://purl.obolibrary.org/obo/BTO_0002179" canonical="184A1N4 cell">
          <variant base="184A1N4 cell"/>
          <variant base="A1N4 cell"/>
      </token>
      <token id="http://purl.obolibrary.org/obo/BTO_0003871" canonical="uterine endometrial cancer cell">
          <variant base="uterine endometrial cancer cell"/>
          <variant base="endometrial cancer cell"/>
          <variant base="uterine endometrial carcinoma cell"/>
          <variant base="endometrial carcinoma cell"/>
      </token>
  </synonym>

The function dict dictionary creates an instance of the class CMdictionary (by internally calling the method buildDictionary).

• If an XML file containing the Conceptmapper dictionary is already available, it can be uploaded into Onassis indicating its path and setting the dictType option to “CMDICT”.
• If the dictionary has to be built from an OBO ontology (as a file in the OBO or OWL format), its path has to be provided and dictType has to be set to “OBO”. The synonymType argument can be set to EXACT_ONLY or ALL to consider only canonical concept names or also to include any synonym. The resulting XML file is written in the indicated outputdir.
• To build a dictionary containing only gene/protein names, dictType has to be set to either TARGET or ENTREZ, to include histone types and marks or not, respetively. If a specific Org.xx.eg.db Bioconductor library is indicated in the inputFileOrDb parameter as a character string, gene names will be derived from it. Alterantively, if a specific species is indicated in the taxID parameter, the gene_info.gz file hosted at NCBI is used. If available, this file can be located with the inputFile parameter. Otherwise, it will be automatically downloaded (300MB).

# If a Conceptmapper dictionary is already available the dictType CMDICT can be specified and the corresponding file loaded
sample_dict <- dictionary(inputFileOrDb=system.file('extdata', 'cmDict-sample.cs.xml', package = 'Onassis'), dictType = 'CMDICT')

#Creation of a dictionary from the file sample.cs.obo available in OnassisJavaLibs
obo <- system.file('extdata', 'sample.cs.obo', package='OnassisJavaLibs')

sample_dict <- dictionary(inputFileOrDb=obo, outputdir=getwd(), synonymType='ALL')

# Creation of a dictionary for human genes/proteins
require(org.Hs.eg.db)
targets <- dictionary(dictType='TARGET', inputFileOrDb = 'org.Hs.eg.db')

3.3 Setting the options for the annotator

Conceptmapper includes 7 different options controlling the annotation step. These are documented in detail in the documentation of the CMoptions function. They can be listed through the listCombinations method after creating a ‘CMoptions’ object, and they can be set through the CMoptions function. The set options are thus stored in an object of class CMoptions that will be required for the subsequent step of annotation.

#Showing configuration permutations 
opts <- CMoptions()  
combinations <- listCombinations(opts)
#Setting the combination of parameters through the paramValueIndex value
myopts <- CMoptions(c("CONTIGUOUS_MATCH", "CASE_INSENSITIVE", 'BIOLEMMATIZER', 'PUBMED', 'ON', 'YES', 'ALL'))

3.4 Running the entity finder

The class EntityFinder has methods to find concepts of any OBO ontology in a given text. The findEntities and annotateDF methods accept text within files or data.frame, respetively, as described in Section 3.1. Alternatively, the function annotate automatically adapts to the provided input type. For example, to annotate the metadata derived from ChIP-seq experiments obtained from SRA with tissue and cell type concepts belonging to BRENDA ontology the following code can be used:

chipseq_dict_annot <- annotate(sra_chip_seq[1:20,c('sample_accession', 'title', 'experiment_attribute', 'sample_attribute', 'description')], dictionary=sample_dict, options=myopts)

## [1] "/tmp/Rtmpzmmn37"
## [1] "/tmp/Rtmpzmmn37/SRS115184.a1"
## [1] "/tmp/Rtmpzmmn37/SRS117344.a1"
## [1] "/tmp/Rtmpzmmn37/SRS213443.a1"
## [1] "/tmp/Rtmpzmmn37/SRS241934.a1"
## [1] "/tmp/Rtmpzmmn37/SRS266173.a1"
## [1] "/tmp/Rtmpzmmn37/SRS285318.a1"
## [1] "/tmp/Rtmpzmmn37/SRS336079.a1"
## [1] "/tmp/Rtmpzmmn37/SRS346539.a1"
## [1] "/tmp/Rtmpzmmn37/SRS362733.a1"
## [1] "/tmp/Rtmpzmmn37/SRS362801.a1"
## [1] "/tmp/Rtmpzmmn37/SRS365824.a1"
## [1] "/tmp/Rtmpzmmn37/SRS371783.a1"
## [1] "/tmp/Rtmpzmmn37/SRS376074.a1"
## [1] "/tmp/Rtmpzmmn37/SRS410226.a1"
## [1] "/tmp/Rtmpzmmn37/SRS421364.a1"
## [1] "/tmp/Rtmpzmmn37/SRS468164.a1"
## [1] "/tmp/Rtmpzmmn37/SRS494656.a1"
## [1] "/tmp/Rtmpzmmn37/SRS598154.a1"
## [1] "/tmp/Rtmpzmmn37/SRS636394.a1"
## [1] "/tmp/Rtmpzmmn37/SRS724993.a1"

## Conceptmapper annotations created in directory: /tmp/Rtmpzmmn37

The resulting data.frame contains for each row a match to the provided dictionary for a specific document/sample (indicated in the first column). The annotation is reported with the id of the concept (term_id), its canonical name (term name), its URL in the obo format, and the matching sentence of the document.

The function annotate can also be used to identify the targeted entity of each ChIP-seq experiment, by retrieving gene names and histone types or modifications in the ChIP-seq metadata.

#Finding the TARGET entities
target_entities <- annotate(inputFileorDf=sra_chip_seq[1:20,c('sample_accession', 'title', 'experiment_attribute', 'sample_attribute', 'description')], options = myopts, dictionary=targets) 

## [1] "/tmp/Rtmpzmmn37"
## [1] "/tmp/Rtmpzmmn37/SRS115184.a1"
## [1] "/tmp/Rtmpzmmn37/SRS117344.a1"
## [1] "/tmp/Rtmpzmmn37/SRS213443.a1"
## [1] "/tmp/Rtmpzmmn37/SRS241934.a1"
## [1] "/tmp/Rtmpzmmn37/SRS266173.a1"
## [1] "/tmp/Rtmpzmmn37/SRS285318.a1"
## [1] "/tmp/Rtmpzmmn37/SRS336079.a1"
## [1] "/tmp/Rtmpzmmn37/SRS346539.a1"
## [1] "/tmp/Rtmpzmmn37/SRS362733.a1"
## [1] "/tmp/Rtmpzmmn37/SRS362801.a1"
## [1] "/tmp/Rtmpzmmn37/SRS365824.a1"
## [1] "/tmp/Rtmpzmmn37/SRS371783.a1"
## [1] "/tmp/Rtmpzmmn37/SRS376074.a1"
## [1] "/tmp/Rtmpzmmn37/SRS410226.a1"
## [1] "/tmp/Rtmpzmmn37/SRS421364.a1"
## [1] "/tmp/Rtmpzmmn37/SRS468164.a1"
## [1] "/tmp/Rtmpzmmn37/SRS494656.a1"
## [1] "/tmp/Rtmpzmmn37/SRS598154.a1"
## [1] "/tmp/Rtmpzmmn37/SRS636394.a1"
## [1] "/tmp/Rtmpzmmn37/SRS724993.a1"