Annotations in Cytoscape are stored as a set of ontologies (e.g. the Gene Ontology, or GO). An ontology consists of a set of controlled vocabulary terms that annotate the objects. For example, using the Gene Ontology, the Saccharomyces Cerevisiae '''CDC55''' gene has a biological process described as “protein biosynthesis”, to which GO has assigned the number 6412 (a GO ID). {{{ GO 8150 biological_process GO 7582 physiological processes GO 8152 metabolism GO 44238 primary metabolism GO 19538 protein metabolism GO 6412 protein biosynthesis }}} '''Graphical View of GO Term 6412: protein biosynthesis''' {{attachment:ontology_dag1.png}} Cytoscape can use this ontology DAG (Directed Acyclic Graph) to annotate objects in networks. The Ontology Server (originally called "!BioDataServer") is a Cytoscape feature which allows you to load, navigate, and assign annotation terms to nodes and edges in a network. Cytoscape 2.4 now has an enhanced GUI for loading ontology and associated annotation, enabling you to load both local and remote files. == Ontology and Annotation File Format == The standard file formats used in Cytoscape Ontology Server are OBO and Gene Association. The GO website details these file formats: * Ontologies and Definitions: http://www.geneontology.org/GO.downloads.shtml#ont * Current Annotations: http://www.geneontology.org/GO.current.annotations.shtml === OBO File === An OBO file is the ontology DAG itself. This file defines the relationships between ontology terms. Cytoscape 2.4 and onwards can load all ontology files written in OBO format. The full listing of ontology files are available from the Open Biomedical Ontologies (OBO) website: * OBO Ontology Browser: http://obo.sourceforge.net/browse.html Sample OBO File - gene_ontology.obo: http://www.geneontology.org/ontology/gene_ontology_edit.obo {{{ format-version: 1.2 date: 27:11:2006 17:12 saved-by: midori auto-generated-by: OBO-Edit 1.002 subsetdef: goslim_generic "Generic GO slim" subsetdef: goslim_goa "GOA and proteome slim" subsetdef: goslim_plant "Plant GO slim" subsetdef: goslim_yeast "Yeast GO slim" subsetdef: gosubset_prok "Prokaryotic GO subset" default-namespace: gene_ontology remark: cvs version: $Revision: 5.49 $ [Term] id: GO:0000001 name: mitochondrion inheritance namespace: biological_process def: "The distribution of mitochondria, including the mitochondrial genome, into daughter cells after mitosis or meiosis, mediated by interactions between mitochondria and the cytoskeleton." [GOC:mcc, PMID:10873824, PMID:11389764] synonym: "mitochondrial inheritance" EXACT [] is_a: GO:0048308 ! organelle inheritance is_a: GO:0048311 ! mitochondrion distribution [Term] id: GO:0000002 name: mitochondrial genome maintenance namespace: biological_process def: "The maintenance of the structure and integrity of the mitochondrial genome." [GOC:ai] is_a: GO:0007005 ! mitochondrion organization and biogenesis }}} === Default List of Ontologies === Cytoscape provides a list of ontologies available in OBO format. If an Internet connection is available, Cytoscape will import ontology and annotation files directly from the remote source. The table below lists the included ontologies. || '''Ontology Name''' || '''Description''' || ||Gene Ontology Full||This data source contains a full-size GO DAG, which contains all GO terms. This OBO file is written in version 1.2 format.|| ||Generic GO slim|| A subset of general GO Terms, including higer-level terms only.|| ||Yeast GO slim||A subset of GO Terms for annotating Yeast data sets maintained by SGD.|| ||Molecule role (INOH Protein name/family name ontology)||A structured controlled vocabulary of concrete and abstract (generic) protein names. This ontology is a INOH pathway annotation ontology, one of a set of ontologies intended to be used in pathway data annotation to ease data integration. This ontology is used to annotate protein names, protein family names, and generic/concrete protein names in the INOH pathway data. INOH is part of the BioPAX working group.|| ||Event (INOH pathway ontology)||A structured controlled vocabulary of pathway-centric biological processes. This ontology is a INOH pathway annotation ontology, one of a set of ontologies intended to be used in pathway data annotation to ease data integration. This ontology is used to annotate biological processes, pathways, and sub-pathways in the INOH pathway data. INOH is part of the BioPAX working group.|| ||Protein-protein interaction||A structured controlled vocabulary for the annotation of experiments concerned with protein-protein interactions.|| ||Pathway Ontology||The Pathway Ontology is a controlled vocabulary for pathways that provides standard terms for the annotation of gene products.|| ||PATO||PATO is an ontology of phenotypic qualities, intended for use in a number of applications, primarily phenotype annotation. For more information, please visit the PATO wiki (http://www.bioontology.org/wiki/index.php/PATO:Main_Page). || ||Mouse pathology||The Mouse Pathology Ontology (MPATH) is an ontology for mutant mouse pathology. This is Version 1.|| ||Human disease||This ontology is a comprehensive hierarchical controlled vocabulary for human disease representation. For more information, please visit the Disease Ontology website (http://diseaseontology.sourceforge.net/).|| Although Cytoscape can import all kinds of ontologies in OBO format, annotation files are associated with specific ontologies. Therefore, you need to provide the correct ontology-specific annotation file to annotate nodes/edges/networks in Cytoscape. For example, while you can annotate human network data using the GO Full ontology with human Gene Association files, you cannot use a combination of the human Disease Ontology file and human Gene Association files, because the Gene Association file is only compatible with GO. === Visualize and Browse Ontology DAG (for Advanced Users) === Relationships between ontology terms are usually represented as Directed Acyclic Graphs (DAGs). This is a special case of a network (or graph), where nodes are ontology terms and edges are relationships between terms. Originally, Cytoscape used a special data structure called !BioDataServer to store ontology DAGs. Starting in version 2.4, ontology data will now be stored in the same data structure as normal networks. This enables users and plugin writers to visualize, browse and manipulate ontology DAGs just like other networks. The following is an example of visualization of an ontology DAG (Generic GO Slim): {{attachment:ontology_dag2.png}} Every ontology term and relationship can have attributes. In the OBO files, ontology terms have optional fields such as definition, synonyms, comments, or cross-references. These fields will be imported as node attributes. To browse those attributes, please use the attribute browser (see the example below): {{attachment:ontology_attrs.png}} * Note 1: Some ontologies have a lot of terms. For example, the full Gene Ontology contains more than 20,000 terms. If you need to save memory, you can remove this ontology DAG from Network Panel (right-click on the ontology name at the left-hand side of the screen and select Destroy Network). * Note 2: All ontology DAGs will be saved in the session file. To minimize the session file size, you can delete the Ontology DAG before saving session. === Gene Association File === The Gene Association (GA) file provides annotation only for the Gene Ontology. It is a species-specific annotation file for GO terms. '''Gene Association files will only work with Gene Ontologies and NOT others!''' Sample Gene Association File (gene_association.sgd - annotation file for yeast): {{{ SGD S000003916 AAD10 GO:0006081 SGD_REF:S000042151|PMID:10572264 ISS P aryl-alcohol dehydrogenase (putative) YJR155W gene taxon:4932 20020902 SGD SGD S000005275 AAD14 GO:0008372 SGD_REF:S000069584 ND C aryl-alcohol dehydrogenase (putative) YNL331C gene taxon:4932 20010119 SGD }}} == Node Name Mapping == If you have a network file and an attribute file, they should have a common key to map attributes onto network data. If those two do not have a common key, you need to do an extra step to add a shared key. The following is a quick tutorial to learn how to use Gene Name Mapping files. === Import New ID Sets from BioMart === From Cytoscape 2.6.0, you can import various kinds of ID sets from !BioMart (http://www.biomart.org/index.html). !BioMart web service client is available as a set of plugins. You can install ''!BioMartClient'' and ''!BioMartUserInterface'' plugins from Plugin Manager window. {{attachment:id_mapping1.png}} 1. Select: '''File → Import → Import attributes from Biomart...''' 1. Select a data source. For ID mapping, select one of the ''Ensemble Genes'' data set. You need to choose correct species for your network. 1. Select '''Attribute'''. If you want to import new ID sets matching current node IDs, select ''ID''. 1. Select '''Data Type'''. This should be the type of ID set selected in '''Attribute''' list. For example, if you select ''ID'' for '''Attribute''' and your network uses ''Entrez Gene ID'' for its node ID, you need to select ''!EntrezGene ID(s)'' for '''Data Type'''. 1. Select new ID sets from the list. Because !BioMart server does not accept query to import lots of annotations at once, you can select only 3-5 attributes for each import. 1. Press '''Import'''. === Import Network and Name Mapping Files === 1. Download name mapping files. Mapping files are available at: http://chianti.ucsd.edu/kono/genenamemapping.html. In this tutorial, we are going to use ''dictionary_no_prefix.zip'', which is a file set '''without''' prefixes for each gene names. Unzip the archive. 2. Load sample network file. Open network import dialog from '''''File-->Import-->Network (multiple file types)...''''' Then click URL radio button and import '''''Human Protein-Protein: Rual et al. (Subnetwork for tutorial)'''''. 3. Open attribute table import dialog from '''''File-->Import-->Attribute from Table'''''. 4. Select '''''human.dic_cyto.txt''''' as the input file. 5. Check "Show Text File Import Options'' and click ''Transfer first line as attribute names'' checkbox. 6. Uncheck "Show Text File Import Options'' and check ''Mapping Options''. 7. Select '''!EntrezGene''' as '''Primary Key'''. 8. Right-click on '''!EntrezGene''' column name and set the type to ''String''. 9. Do the same for '''HGNC'''. 10. Right-click on '''Other Aliases''' and select ''List'' as the data type. 11. Check '''Other Aliases''' as Alias (under "Alias?" checkboxes). 12. Now the Table Import dialog looks like the following screenshot: {{attachment:importdialog1.png}} 13. Press ''Import''. The network has new names in the text file as attributes. {{attachment:nameMapping1.png}} At this point, nodes have multiple names including HGNC, UniProt, and EntrezGene ID. You can import other attribute files using these keys. These imported names (IDs) are useful when you import GO Annotation. == Import Ontology and Annotation == {{attachment:ontology_and_annotation_Import_main.png}} Cytoscape 2.4 provides a graphical user interface to import both ontology and annotation files at the same time. === Import Gene Ontology and Gene Association Files === For convenience, Cytoscape has a list of URLs for commonly used ontology data and a complete set of Gene Association files. To import Gene Ontology and Gene Association files for the loaded networks, please follow these steps: '''''Important: All data sources in the preset list are remote URLs, meaning a network connection is required!''''' ==== Step 1. Select an Annotation File ==== {{attachment:ontology_import_annotation.png}} Select File → Import → Ontology and Annotation... to open the "Import Ontology and Annotation" window. From the Annotation dropdown list, select a gene association file for your network. For example, if you want to annotate the yeast network, select "Gene Association file for Saccharomyces cerevisiae". ==== Step 2. Select an Ontology File ==== {{attachment:ontology_import_obo.png}} Select an Ontology data (OBO file) from the Ontology dropdown list. If the file is not loaded yet, it will be shown in red. The first three files are Gene Ontology files. You can load other ontologies, but you need your own annotation file to annotate networks. ==== Step 3. Import the files ==== Once you click the Import button, Cytoscape will start loading OBO and Gene Association files from the remote sources. If you choose GO Full it may take a while since it is a large data file. ==== Step 4. ==== When Cytoscape finishes importing files, the import window will be automatically closed. All attributes mapped by this function have the prefix "annotation" and look like this: {{{annotation.[attribute_name]}}}. All ontologies will be added to the end of the Ontology DAGs branch in the Network Manager. {{attachment:ontology_tree.png}} Ontology DAGs have some attributes associated with the terms. All attributes associated with ontology terms will have the prefix ''ontology''. They have at least one attribute: {{{ontology.name}}}. For more detailed information about attributes for ontology DAGs, please read the official [[http://www.geneontology.org/GO.format.obo-1_2.shtml|OBO specification document]]. * Note: Cytoscape supports both OBO formats: version 1.0 and 1.2. ==== Note: Switching Primary Key for Go Annotation Import ==== If node IDs in a network file are NOT ''DB_Object_Symbol'' (3rd column in Gene Association file), you need to select a primary key column. Click ''Show Mapping Options'' to change the key. Usually, ''DB_Object_ID'' can be an alternative primary key. == Custom Annotation Files for Ontologies Other than GO (for Advanced Users) == The "Import Ontology and Annotation" function is designed to import general ontology and annotation files. Internally, mapping ontology terms onto existing networks is the same as joining three data tables in Cytoscape. An Ontology DAG, an annotation file, and network data are used in this process (see the example below). __Network Data__ {{attachment:ontology_net_table.png}} __Ontology Data__ {{attachment:ontology_obo_table.png}} __Annotation Data__ {{attachment:ontology_ga_table.png}} __Mapping Result__ {{attachment:ontology_mapping_result.png}} If you want to map ontology terms onto network objects, you need to create a custom annotation file. The annotation file should contain at least 2 columns: a primary key and an ontology term ID. The primary key is the value used for mapping between the annotation file and network. Usually, the node/edge ID is used as the primary key, but you may choose any of the available attributes. The Ontology term ID is the key used for mapping between the annotation file and the ontology DAG. Using these data sources, you can annotate network objects in Cytoscape. Suppose you have a small network: {{{ node_1 pp node_2 node_3 pp node_1 node_2 pp node_3 }}} and you want to annotate this network with ''Ontology A'', which is an ontology DAG available in OBO format. In this case, you need an annotation table file that looks like this: {{{ node_1 OA_0000232 node_2 OA_0000441 node_3 OA_0000702 }}} where ''OA_***'' represents an ontology term ID. This example is a file with the minimum necessary number of columns; however, you can include additional columns that will appear as additional node attributes. Some ontologies will be used to annotate edges or networks. For example, the [[http://obo.sourceforge.net/cgi-bin/detail.cgi?psi-mi|Protein-protein interaction ontology]] is a controlled set of terms for annotating interactions between proteins, so ontology terms should be mapped onto edges (see example below). {{{ node_1 (pp) node_2 MI:0445 node_3 (pp) node_1 MI:0046 node_2 (pp) node_3 MI:0346 }}} {{attachment:ontology_import_custom1.png}} The basic operation of the Ontology and Annotation Import function is the same as that of the Attribute Table Import. The main difference is that you need to specify an additional key for mapping: {{attachment:ontology_import_custom2.png}} By selecting a column from the "Key Column in Annotation File" dropdown list, you can specify the key for mapping between ontology terms and the annotation file. * Note: When you load Gene Association files, Cytoscape uses a special loader program designed only for Gene Association files. Because of this program, all attributes will be named automatically. Also, ontology IDs will be converted into term names and NCBI taxonomy ID will be converted into actual species name. However, for custom annotation files, those processes will not be applied. All ontology terms will be mapped as term IDs.