NCBO Wiki - User contributions [en]

Immunology Ontologies and Their Applications in Processing Clinical Data

2013-04-12T19:45:10Z

Maseda: test: reverting my recent addition of whitespace and text

The National Center for Biomedical Ontology [http://bioontology.org (NCBO)] in collaboration with the Protein Ontology [http://pir.georgetown.edu/pro/ (PRO)] and the Infectious Disease Ontology [http://infectiousdiseaseontology.org/page/Main_Page (IDO)] will host a three-day dissemination workshop in Buffalo, NY on June 11-13, 2012.
:Day 1 will provide a survey of current ontology-based research in immunology and infectious disease with a view to future coordination among ontology developers and users in this field.
:Day 2 will be focused on flow cytometry, including the question of the Cell and Protein Ontologies and of the role of surface protein expression in cell type classification.
:Day 3 will include a session devoted to the use of ontologies to assist clinicians working with infectious disease data, followed by a session on the Ontology for General Medical Science.

'''Venue: [http://www.universityinn.com/ Ramada Inn, UB North Campus, Buffalo]'''

'''Goals'''

The goals of this meeting are: To identify and coordinate activities on-going in immunology ontology and related fields, with special attention to the use of ontologies to support clinical data analysis in flow cytometry and related fields.

'''Registration'''

'''THIS MEETING IS NOW FULL. NO FURTHER REGISTRATIONS ACCEPTED.'''

----
'''
== Day 1: Monday, June 11, 2012 ==
'''

08:30 Registration and Breakfast

'''An Overview of Ontologies to Support Research in Immunology and Infectious Disease'''

09:15 Barry Smith (University at Buffalo) and Cathy Wu (University of Delaware) [http://ontology.buffalo.edu/12/immunology_ontology/smith.pptx slides]
::Bio-Ontologies for Immunology Research: An Introduction
:::Brief survey of the goals of the meeting.

09:30 Alexander Diehl (University at Buffalo) [http://ontology.buffalo.edu/12/immunology_ontology/Diehl_GO_IP.pptx slides]
::The Gene Ontology and Immune System Processes
:::The Gene Ontology contains a wealth of terms covering immune system processes for the annotation of proteins involved in the functioning of the immune system. I will provide a overview of these terms and their use in GO annotation.

10:00 Cliburn Chan (Duke University) [http://ontology.buffalo.edu/12/immunology_ontology/Chan_Networks.pptx slides]
::Ontology for Cellular Immune Networks
:::Will describe initial work on an ontology of cellular immune networks that is designed to capture the qualitative cytokine expression patterns and cellular phenotypes associated with specific immune activation networks (e.g. Th1 network). We will outline use of the ontology for immune assay integration and statistical enrichment analysis.

10:30 Break

11:00 Anna Maria Masci (Duke University) [http://ontology.buffalo.edu/12/immunology_ontology/Masci%20AM.pdf slides]
::The Immunology Ontology (with special focus on the liver)
:::An emerging scenario is uncovering immune response as a sophisticated biological process, which requires an intensive cross-talk between immunocytes, parenchymal and stromal cell types. These timely and anatomically restricted interactions regulate the outcome of immune response to damage induced by stress and pathogens. Due to its complexity and patho-physiological relevance, the liver represents an interesting prototype of context-dependent immune response. We will introduce the Liver Immunology Ontology (LIO), which has as primary goal the representation of the immune response induced in the context of the liver.

11:30 Peter d'Eustacho (New York University) [http://ontology.buffalo.edu/12/immunology_ontology/dEustachio.pptx slides]
::Innate Immunity: Signaling via Toll-Like Receptors in Reactome
:::The innate immune responses mediated by Toll-like receptors (TLR) provide a first line of defense against microbial pathogens in many vertebrates. In Reactome we have integrated annotations of human TLR molecular functions with those of 6800 other human proteins involved in diverse biological processes to generate a resource suitable for data mining, pathway analysis, and other systems biology approaches. These annotations allow human TLR proteins, the complexes they form, and the functions they mediate to be classified and related to those of structurally similar TLR proteins from chicken, mouse, and other species.

12:00 '''Lunchtime talk'''
Atul Butte (Stanford) [http://ontology.buffalo.edu/12/immunology_ontology/Butte.pptx slides]
::Discovery of a novel inflammatory receptor and related drug for type 2 diabetes from integration of publicly-available microarray data

14:00 Lindsay Cowell (University of Texas Southwestern Medical Center) [http://ontology.buffalo.edu/12/immunology_ontology/Cowell.pdf slides]
::An Introduction to the Infectious Disease Ontology
:::The IDO-Core; new approach to MIREOTing; new terms/definitions/relations; a template for creating an IDO Extension

14:30 Albert Goldfain (Blue Highway) [http://ontology.buffalo.edu/12/immunology_ontology/Goldfain_IDO-Staph.pptx slides]
::Staph Aureus (Sa) IDO

15:00 Break

15:30 Christos (Kitsos) Louis (IMBB-FORTH, Crete) [http://ontology.buffalo.edu/12/immunology_ontology/Louis_IDOMAL.ppt slides]
::IDO Mal (Malaria Ontology)
:::We will outline the Malaria Ontology, including three new sub-domains dealing with:
::::a) drug resistance
::::b) remedies and traditional medicinal plants
::::c) vector-mediated transmission.
:::We will also describe our conversion from the OBO to the OWL format.

16:00 Yu Lin (University of Michigan)[http://ontology.buffalo.edu/12/immunology_ontology/YuLun.pdf slides]
::IDO Bru (Brucellosis Ontology)
:::IDO Bru is an extension ontology of IDO. We will focus on those aspects of Brucellosis represented in IDOBru as outlined in [http://www.jbiomedsem.com/content/2/1/9]. We will also discuss IDOBru's policy on use of IDs, and its treatment of Brucella-host interaction.

16:30 Oliver He (University of Michigan) [http://ontology.buffalo.edu/12/immunology_ontology/He_VO.pptx slides]
::Contributions of the Vaccine Ontology (VO) to Immunology Research and Public Health
:::Vaccinology is applied immunology. VO is a community-based biomedical ontology in the domain of vaccine and vaccination. We will introduce the top level of VO, and sketch applications of VO in elucidating fundamental protective immune mechanisms and improving public health.

----
'''

== Day 2: Tuesday, June 12, 2012 ==
'''

'''Ontologies and Flow Cytometry Informatics'''

:'''Background''' Increasingly, flow cytometry is being employed in clinical laboratories for the diagnosis, prognosis and monitoring of disease. The advent of highly multidimensional flow cytometry and automated gating algorithms for the analysis of flow cytometry data, coupled with the rise of personalized medicine, are poised to expand greatly the need for a reliable, structured framework for the representation of the types of cells present in human blood and tissues. We are currently enhancing the representation of hematopoietic and other cell types in the Cell Ontology (CL) to allow for the logical definition of cell types based on cellular attributes, and in doing so we rely on relations to terms of the Protein Ontology (PRO) as a key component of these definitions. The goal of today's session is explore how the use of clinical flow cytometry data can serve as a driver of ontology development in both the PRO and the CL by assessing current standard clinical assays and recent approaches based on automated gating of multidimensional flow cytometry.

:Examples of questions to be addressed include:
::Which protein isoforms and post-translationally modified forms identified by flow cytometry typing reagents need to be represented in the PRO to enable cell types defined in their terms to be represented in the CL?
::How can use of the PRO and CL ontologies will promote standardization in interpretation and integration of clinical flow cytometry data?

:Background Reading
::[http://www.ncbi.nlm.nih.gov/pmc/articles/PMC3013777/?tool=pubmed The Protein Ontology: a structured representation of protein forms and complexes]
::[http://www.biomedcentral.com/1471-2105/12/6 Logical Development of the Cell Ontology]
::Cytometry-Ontology Framework ([http://ontology.buffalo.edu/pro/CytometryOntologyFramework.pdf Draft])

08:30 Breakfast

'''9:00-noon: Introduction to the Protein Ontology Flow Cytometry Driving Biological Project'''

9:00 Cathy Wu (University of Delaware): Introduction to the Protein Ontology [http://ontology.buffalo.edu/12/immunology_ontology/Wu_PRO.pdf slides]

9:30 Alexander Diehl (Buffalo) [http://ontology.buffalo.edu/12/immunology_ontology/Diehl_CL.pptx slides]
::Hematopoietic Cell Types in the Cell Ontology
:::The Cell Ontology includes over 350 terms that represent hematopoietic cell types. I will provide an overview of these terms and our strategy for representing key properties of cell types through logical definitions, with examples from Leukemia and Multiple Myeloma

10:00 Discussion of the PRO Driving Biomedical Project
Moderator: Alexander Diehl (Buffalo)
:Presentation of key issues:
::Assessing representation requirements for Flow Cytometry in PRO, CL, IEDB, OBI, ImmPort, and Immune System Modeling.
::Development of a data store to collect extended cell type-protein relationships.
::Defining a tool wish-list for CL-linked flow cytometry analysis and CL-assisted marker selection for cell type analysis.

10:45 Break

11:15 Oliver He (University of Michigan) [http://ontology.buffalo.edu/12/immunology_ontology/He_Flow_Cytometry.pptx slides]
::How Flow Cytometry can be used in Vaccine Research
:::To better understand fundamental protective immune mechanisms, flow cytometry has frequently been used to measure vaccine-induced innate immunity, and antigen-specific T-cell and B-cell responses. Biomedical ontologies (e.g., VO, OBI, and PRO) play important roles in data representation, integration, and automated reasoning in vaccine-related flow cytometry research.

11:45 Dave Parrish ([http://www.labanswer.com/ LabAnswer])
::Storing and Retrieving Flow Cytometry Data
:::The Flow Cytometry Laboratory at Roswell Park Cancer Institute has recently deployed an internally developed application managing the operational workflow of the laboratory. We will describe the use of the relational database in capturing assay results and ultimately associating with a final interpretation. Although early in the process the goal is to support the use of the Cell and Protein Ontologies in panel design and interpretation classification.

12:30 Lunch

'''Afternoon: Automated gating of Flow Cytometry results and linking to the Cell Ontology. Flow cytometry typing of normal and malignant cell types'''

13:30 Cliburn Chan (Duke) [http://ontology.buffalo.edu/12/immunology_ontology/Chan_HIV.pptx slides]
::Automated flow cytometry analysis in HIV studies
:::Will describe recent work on automated cell subset identification and alignment across multiple HIV-related data sets with statistical mixture models. What do we need in order to be able to use ontologies for automated annotation and labeling of cell subsets?

14:00 Nikesh Kotecha (Cytobank) [http://ontology.buffalo.edu/12/immunology_ontology/kotecha.pdf slides]
::Incorporating annotations into the analysis workflow - examples using Cytobank and NCBO's BioPortal
:::Cytobank is a platform to manage, share and analyze flow cytometry data over the web. I will describe the challenges addressed in working with large numbers of samples as well as incorporating novel visualizations and algorithms (e.g. SPADE) for high dimensional data (e.g. 40+ parameter mass cytometry experiments). Central to much of this work is interfaces to promote and incorporate annotations into the analysis workflow. I will also highlight some recent work in Cytobank to incorporate ontologies via NCBO's BioPortal

14:30 Melanie Courtot (Ryan Brinkman's group, Vancouver) [http://ontology.buffalo.edu/12/immunology_ontology/Courtot_CytometryOntologyFramework.pdf slides]
::1. Overview of the representation of flow cytometry assays in [http://purl.obolibrary.org/obo/obi OBI]
::2. Connecting results from automated FCM analysis systems with the Cell Ontology

15:00 Break

15:30 General Discussion of Ontologies and Flow Cytometry (Moderator: Alan Ruttenberg, Buffalo)

16:30 End

----
'''

== Day 3: Wednesday, June 13, 2012 ==
'''

8:30 Breakfast

'''9:00-noon: Immunology Ontologies (Continued)'''

9:00 Bjoern Peters (La Jolla Institute for Allergy and Immunology) [http://ontology.buffalo.edu/12/immunology_ontology/Peters.pptx slides]
::Representation of immunology experiments using OBI
::Representing epitope mapping experiments for the Immune Epitope Database (IEDB)
:::The Ontology for Biomedical Investigations (OBI) is an ontology that provides terms with precisely defined meaning to describe all aspects of how biomedical investigations are conducted. OBI builds on the Gene Ontology (GO) and related efforts that provide a formal and interoperable representation of biomedical knowledge. OBI adds the ability to describe how this knowledge was derived. OBI covers all phases of the investigation process, such as planning, execution and reporting. It represents information and material entities that participate in these processes, as well as roles and functions. The presentation will describe the state of OBI and several applications that are using it. Specific focus will be on epitope mapping and characterization experiments captured in the Immune Epitope Database (IEDB) which heavily utilizes OBI. The presentation will also point out gaps in coverage of immunological terms that are currently in OBI but poorly defined and outside the scope of OBI, and which deserve a better home.

10: Alex Yu (Buffalo) [http://ontology.buffalo.edu/12/immunology_ontology/Alex_Yu.pdf slides]
:The Allergy Ontology

10:30 Break

11:00 Alexander Diehl (Buffalo) [http://ontology.buffalo.edu/12/immunology_ontology/Diehl_Autoimmune.pptx slides]
:Towards an Auto-Immune Disease Ontology
::I will discuss the construction of an auto-immune disease ontology through use of the Ontology of General Medical Sciences as a general framework for ontology development.

'''The Role of Ontologies in Clinical Medicine'''

12:00: Lunch

1:00pm :Albert Goldfain (Blue Highway / Syracuse)
::Creating Personalized Infectious Disease Ontologies

1:30 Christos (Kitsos) Louis (IMBB-FORTH, Crete)
::Ontologies and Vector-Borne Diseases

2:00 Werner Ceusters (Buffalo) [http://www.referent-tracking.com/RTU/sendfile/?file=20120613.ppt slides]
::Assessment instruments and biomedical reality: examples in the pain domain

2:30 Refreshment Break

'''3pm-6pm: Working Session on the Ontology for General Medical Science (OGMS)'''

:Moderator: Albert Goldfain (Blue Highway / Syracuse)
:Topics to be treated will include:
::Current status of OGMS and the OGMS Reference
::Linking diseases to their underlying disorders using basis relations
::Defining 'relapse' and 'remission' processes.
::Updates on the Vital Sign Ontology
::Recipes for OGMS-conformant extension ontologies
:''Close: 6:00pm''
----
'''Relevant ontology efforts'''

:GO-IP Gene Ontology -- Immunological Process (Alexander Diehl)
:CL Cell ontology immune branches
:PRO Protein Ontology
:IO Immunology Ontology (Lindsay Cowell and Alexander Diehl)
:IEO Immune Epitope Ontology (Bjoern Peters)
:MHC Major Histocompatibility Complex Ontology (Bjoern Peters)
:OGMS Ontology for General Medical Science (Albert Goldfain)
:IDO Infectious Disease Ontology (Lindsay Cowell)
:Vaccine Ontology (Oliver He)
:AO Allergy Ontology (Alex C. Yu)
:ND Neurological Disease Ontology (Alexander Diehl)
----
'''

== Participants ==

:Alex Benns (Frontier Science, Amherst, NY)
:Anthony Bloom (Frontier Science, Amherst, NY)
:Kenneth Braun (Frontier Science, Amherst, NY)
:Ryan Brinkman (University of British Columbia, Vancouver)
:Atul Butte (Stanford University)
:James S. Cavenaugh (University of Rochester Medical Center)
:Werner Ceusters (University at Buffalo)
:Cliburn Chan (Duke University)
:Quan Chen (NIH/NIAID)
:Melanie Courtot (BCCRC, Vancouver)
:Alexander Cox (University at Buffalo)
:Lindsay Cowell (University of Texas Southwestern Medical Center)
:Oliver Crespo (BD Biosciences, San Jose, CA)
:Paresh Dandona (Diabetes and Endocrinology Center of Western New York / University at Buffalo)
:Peter d'Eustachio (New York University)
:Alexander Diehl (University at Buffalo)
:William Duncan (University at Buffalo)
:Chester Fox (University at Buffalo)
:Lee Ann Garrett-Sinha (University at Buffalo)
:Carmelo Gaudioso (Roswell Park Cancer Institute, Buffalo)
:Albert Goldfain (University at Buffalo, Syracuse University and Blue Highway, Inc.)
:Oliver He (University of Michigan)
:Leonard Jacuzzo (University at Buffalo)
:Mark Jensen (University at Buffalo)
:Christos (Kitsos) Louis (IMBB-FORTH, Crete)
:Nikesh Kotecha (Cytobank)
:Yu Lin (University of Michigan)
:Wei Luo (University at Buffalo)
:Supriya Mahajan (University at Buffalo)
:Anna Maria Masci (Duke University)
:Darren Natale (Georgetown University)
:Dave Parrish (Digital Infuzion)
:Bjoern Peters (La Jolla Institute for Allergy and Immunology)
:Mark Ressler (University at Buffalo)
:Jessica L. Reynolds (University at Buffalo)
:Alan Ruttenberg (University at Buffalo)
:Stanley A. Schwartz (University at Buffalo)
:Prontip Saelee (University at Buffalo)
:Veronica Shamovsky (NYU School of Medicine)
:Barry Smith (University at Buffalo)
:Cathy Wu (University of Delaware, Georgetown University)
:Alex C. Yu (University at Buffalo)

2012-03-07T01:41:42Z

Maseda:

= Ontology Management =

== How do I identify version numbers for ontologies stored in the system? ==
NCBO Ontology Web Services can be used with either the ontology identifier (sometimes referred to as the virtual identifier) or the ontology version identifier (sometimes referred to as the version id). The ontology identifier is used to identify and ontology and all of its versions. The ontology version identifier represents a single ontology version. The following screenshot shows how to identify these version numbers using the BioPortal Web UI.
 [[Image:Bioportal_internal_ontology_ids.png|200px|x]]

== How do I add or change categories? ==
<ol>
<li>Download the Protégé client '''(Version Protégé 3.4.4)'''</li>
<ol>
<li>[http://protege.stanford.edu/download/download.html http://protege.stanford.edu/download/download.html] 
</li>
</ol>
<li>Download a copy of the [http://www.bioontology.org/wiki/images/e/ef/Bioportal_metadata.pprj.zip BioPortal Metadata Protégé project file] and modify as follows</li>
<ol>
<li>Line 639: make sure this matches your BioPortal Ontology Services database (ip address or domain of the virtual appliance)</li>
<li>Line 649: this should be your MySQL username (bp_protege)</li>
<li>Line 654: this should be your MySQL password (bioportalprotege)</li>
<li>'''Note:''' These are the default username/password which should be changed for security purposes. If you have already changed them, please use the new username/password.</li>
</ol>
<li>Open the project file using Protégé</li>
<li>Go to the "Individuals" tab</li>
<li>Look for OMV:OntologyDomain and click it</li>
<li>A list of "Asserted Instances" should show up, these are the defaults</li>
<li>You can create or delete instances by clicking on the buttons</li>
<li>Instances should have the following properties:</li>
<ol>
<li>id = unique integer value</li>
<li>omv:name = display name for the category</li>
<li>omv:isSubDomainOf = you can create hierarchies by making
categories subDomains of one another</li>
</ol>
</ol>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
NCBO developers have created a script that can be used to automatically import ontologies from BioPortal or previous versions of the Virtual Appliance. The script was written in Ruby and is included on the Appliance. To use the script, do the following (requires knowledge of Linux command-line tools):

* Edit the script, located here: <code>/var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
** Make sure you have valid API keys for the FROM and TO systems.
** Assign the $FROM and $TO variables and ports as appropriate. The default configuration points to NCBO's BioPortal but can be changed to the location of your Virtual Appliance instance.
** The $ONTOLOGY_OWNER is the user id of the user who should own the ontologies on the TO system.
** $INCLUDE_ONTOLOGIES can be uncommented and used to import specific ontologies only. Otherwise all ontologies from the FROM system will be imported.
** Save your edits and continue below.
* Run the script using this command: <code>sh /var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
* The script will take some time to complete, updating the console as it runs. If automatic parsing is enabled, the ontologies should get parsed when the process next runs.

'''Please Note:''' The import script will attempt to use category and group IDs assigned to ontologies on the FROM system if they exist on the TO system as well. Ontology artifacts, such as notes, views, and mappings, are not imported. Only the most recent version of ontologies are imported; there is no method to import multiple versions of the same ontology using a common virtual id.

= Ontology Parsing =
== When are new ontologies parsed? ==
The BioPortal Ontology Services application uses a scheduler to run a process that collects newly submitted ontologies and parses them, adds them to the search index, and calculates metrics. You can also parse ontologies manually, but you will need to index them for search and calculate metrics manually to have that information available.

The default schedule can be disabled by doing the following:
* Open /ncbo/sources/bioportal/tags/1030/build.properties
* Look for the section that starts with "# Ontology Parse Scheduler properties"
* Set <code>ontology.parse.scheduler.enabled</code> to 'false'
* From the /ncbo/sources/bioportal/tags/1030/ directory, run 'ant clean deploywar'

== How do I manually parse an ontology? ==
To manually parse an ontology, visit the admin interface at http://example:8080/bioportal_admin and select "Parse Ontologies" from the list at the right. You must enter the version id, or a comma-separated list of ids, and then click "Run". The process will return with errors if it encounters any.

== How do I manually add an ontology to the search index? ==
To manually add an ontology to the search index, go to the admin interface and select "Index Ontologies". You can provide a single version id for an ontology or a comma-separated list of ids. You can also choose to index all ontologies currently stored in the Appliance (this may take some time if you have many terms in the system).

== How do I know if an ontology has parsed? ==
Because the BioPortal Web UI uses aggressive caching, it may not immediately reflect the status of an ontology once it's been submitted. By default the ontology status on the Web UI is updated once every four or 12 hours (depending where you are viewing the information). You can change these default options by doing the following:
* Open /var/rails/BioPortal/current/app/models/data_access.rb
* Change the following in the getOntologyList method:
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, MEDIUM_CACHE_EXPIRE_TIME)</code>
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, 60*15)</code>
* Change the following in the getOntology method:
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id })</code>
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id }, 60*15)</code>
* This will change the Web UI so that it refreshed information about ontologies every 15 minutes
* You will need to run /sbin/service httpd restart to have the change take affect
* '''NOTE:''' You will need to make this change again if you update the Web UI code. In addition, if you have a large list of ontologies this could slow down the Web UI for users as it will be required to retrieve more information more often.

In addition, you can look at the REST service directly, which will always give you the most updated information. To do this, visit the following URL:
* http://example:8080/bioportal/ontologies/{ontology_version_id}
* You can look for the statusId element to get the status, the codes are as follows:
** 1 - Waiting
** 2 - Parsing
** 3 - Ready
** 4 - Error
** 5 - Not Applicable (for metadata-only ontologies)

== Is there a log file for parsing? ==
Parsing progress is logged in the BioPortal Ontology Services log files.

There is a separate log file for OBO ontologies that can be monitored:
<code>tail -f /var/log/tomcat6/lexgrid/LexBIG_load_log.txt</code>

OWL and Protege-based ontologies are logged into the general log file:
<code>tail -f /var/log/tomcat6/bioportal.log</code>

== How can I manually remove the hierarchy information from an ontology like NCI Metathesaurus? ==
* Find the database prefix of the ontology by looking up the ontology in the LexEVS registry.xml file.
* Connect to the database that stores the LexEVS tables.
* Find the set of tables that stores the ontology using the table prefix.
* The table called codingSchemeSupportedAttrib needs to be updated to disable the hierarchy. To do so, find the row that has the column supportedAttributeTab that has a value called Hierarchy. Update that column to value HierarchyDisabled so that the loaded hierarchy is ignored.
* Restart Tomcat so that the new values are read in and the cache gets cleared.

= Systems Administration =

== How do I increase the Java heap size that Tomcat uses? ==
* By default we use a 512MB initial heap with a 2GB maximum. You can change these values by editing this file:
** <code>/usr/local/tomcat6/conf/tomcat6.conf</code>
* Change the following line to match your requirements. -Xms is initial size, -Xmx is maximum size.
** <code>JAVA_OPTS="${DEBUG} -Xms512m -Xmx2G -Djava.awt.headless=true -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"</code>
* Restart Tomcat by running the following command:
** <code>/sbin/service tomcat6 restart</code>

[[Category:NCBO Virtual Appliance]]

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==

=== Working with Javascript-based widgets (Form Autocomplete, Quick Jump/Jump To) ===
In addition to the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions], you must define an additional Javascript variable in order to have the widgets communicate with your instance of the Virtual Appliance.
<code>
var BP_SEARCH_SERVER = "http://{your_appliance_ip_or_domain_name}";
</code>
Replace the '{your_appliance_ip_or_domain_name}' text with the IP address or domain name that's assigned to your Virtual Appliance.

=== Working with Flex/Flash-based widgets (FlexViz, Ontology Tree Widget) ===

When working with Flash widgets, you'll need to modify the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions] to change and add your ip address or domain name. See below and look for '{your_appliance_ip_or_domain_name}' and '{ontology_id}'. The '{ontology_id}' is the numerical id for the ontology you want to use with the widget, sometimes called a virtual id. You can find this via the REST service by looking for the <ontologyId> element, or looking in the Web UI on the Browse page. The links for ontologies contain a number that should be the virtual id.

This example is for the Tree Browser.

<pre>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="OntologyTree" width="300" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<param name="allowScriptAccess" value="always" />
<param name="flashVars" value="ontology=<%= @ontology.ontologyId%>&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal" />
<embed src="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" quality="high" bgcolor="#ffffff"
width="300" height="100%" name="OntologyTree" align="middle"
play="true"
loop="false"
allowScriptAccess="always"
type="application/x-shockwave-flash"
flashVars="ontology={ontology_id}&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>
</pre>

In addition, there is a bug in existing versions of the Virtual Appliance that is scheduled to be fixed for the .5 version release in March 2012. Until then, you will need to run the following SQL commands to insert records into the 'bioportal' database:

<pre>
INSERT INTO `ncbo_user` (`id`, `username`, `api_key`, `open_id`, `password`, `email`, `firstname`, `lastname`, `phone`, `date_created`)
VALUES
(39108, 'annotator_flex', X'32626535656235352D383665622D343164362D386238312D653238653532356163633063', NULL, '8qQ8v8cjUZBCs99voQ2+i4mR1VhyFuj70ZCQUV9caXrPQv4K9FuDIfsfrn+ICoXp\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:09:32'),
(39109, 'search_flex', X'39626437366335382D323230642D346337662D386164302D306135363731313634313939', NULL, '/jj4oWOmI1SXbfczyReBZI9z4DSzRoZP/iX9WJe9lb/7vm1owez/yAh6lIRpNOyj\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:10:18'),
(39110, 'recommender_flex', X'35636564383837322D646636342D343838372D613338652D376338653736333935633830', NULL, 'RBmX8e1X2oUEEcqdp73/X7P7JkrfA7lbK8+svGPEojYmcmxDoHui3gC011Pg1cRF\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:11:16'),
(39111, 'flexviz', X'34363832396130352D386331632D343232622D393530642D313836373633616530663763', NULL, 'uivHblEQJII216fGfG0No4RGELzBtY7Bo14IQulDsQOJY4cLUItYuTtU+TkPs1ln\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:13:18');
</pre>

= How can I use the OVF image with my virtualization software? (VMware, VirtualBox, KVM, Xen, etc) =

== VMware ==
You can use [http://communities.vmware.com/community/vmtn/vsphere/automationtools/ovf VMware's ovftool] to convert the appliance to work with your VMware product. For example, to convert the appliance for use in VMware Player or Workstation, you would run the command: <code>ovftool ncbo-appliance.ovf ncbo-appliance.vmx</code>

== VirtualBox ==
VirtualBox supports importing OVF images directly. Simply start your VirtualBox software, then select '''File->Import Appliance''' and select the OVF file included in the NCBO Virtual Appliance download.

== KVM ==

=== HVM ===
You will need to convert the OVF to VMX format as mentioned in the VMware section above.

You must also ensure that the <code>kvm-qemu-img</code> RPM (or <code>qemu-kvm</code> DEB) is installed. Convert the [new] VMDKs (from the VMX conversion step) to raw disk images via the following command:
<code>for disk in `ls -1 *.vmdk`; do diskbase=`basename $disk .vmdk`; qemu-img convert -O raw ${diskbase}.vmdk${diskbase}.img; done</code>

Create <code>/etc/libvirt/qemu/ncbo-appliance.xml</code> with the following contents:
<code>
<domain type='kvm'>
<name>ncbo-appliance</name>
<memory>4194304</memory>
<vcpu>2</vcpu>
<os>
<type arch='x86_64' machine='rhel5.4.0'>hvm</type>
<boot dev='hd'/>
</os>
<features>
<acpi/>
<apic/>
<pae/>
</features>
<clock offset='utc'>
<timer name='pit' tickpolicy='delay'/>
</clock>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>restart</on_crash>
<devices>
<emulator>/usr/libexec/qemu-kvm</emulator>
<disk type='file' device='disk'>
<driver name='qemu' type='raw'/>
<source file='/var/lib/libvirt/images/ncbo-appliance-0.5/ncbo-appliance-0.5-disk1.img'/>
<target dev='hda' bus='ide'/>
<address type='drive' controller='0' bus='0' unit='0'/>
</disk>
<disk type='file' device='disk'>
<driver name='qemu' type='raw'/>
<source file='/var/lib/libvirt/images/ncbo-appliance-0.5/ncbo-appliance-0.5-disk2.img'/>
<target dev='hdb' bus='ide'/>
<address type='drive' controller='0' bus='0' unit='1'/>
</disk>
<controller type='ide' index='0'/>
<interface type='network'>
<source network='default'/>
<model type='virtio'/>
</interface>
<serial type='pty'>
<target port='0'/>
</serial>
<console type='pty'>
<target port='0'/>
</console>
<input type='mouse' bus='ps2'/>
<graphics type='vnc' port='-1' autoport='yes' keymap='en-us'/>
<video>
<model type='cirrus' vram='9216' heads='1'/>
</video>
</devices>
</domain>
</code>

Make any necessary edits to the above file, and run <code>virsh start ncbo-appliance</code>.

=== PVM ===
Xen PVMs (Paravirtual Machines) are not supported.

== Xen ==

=== HVM ===
You will need to convert the VMDKs to raw disk images as mentioned in the KVM section above.

Create <code>/etc/libvirt/qemu/ncbo-appliance.xml</code> with the following contents:
<code>
name = "ncbo-appliance"
memory = 4096
vcpus = 2
builder = "hvm"
kernel = "/usr/lib/xen/boot/hvmloader"
boot = "c"
pae = 1
acpi = 1
apic = 1
localtime = 0
on_poweroff = "destroy"
on_reboot = "destroy"
on_crash = "destroy"
device_model = "/usr/lib64/xen/bin/qemu-dm"
sdl = 0
vnc = 1
vncunused = 1
keymap = "en-us"
disk = [ "file:/var/lib/xen/images/ncbo-appliance-0.5/ncbo-appliance-0.5-disk1.img,hda,w", "file:/var/lib/xen/images/ncbo-appliance-0.5/ncbo-appliance-0.5-disk2.img,hdb,w" ]
vif = [ "bridge=xenbr0,script=vif-bridge,vifname=vif41.0" ]
parallel = "none"
serial = "pty"
</code>

Make any necessary edits to the above file, and run <code>xm create ncbo-appliance</code>.

=== PVM ===
KVM PVMs (Paravirtual Machines) are not supported.

Virtual Appliance FAQ

2012-03-06T23:12:42Z

Maseda: /* VMWare */

= Ontology Management =

== How do I identify version numbers for ontologies stored in the system? ==
NCBO Ontology Web Services can be used with either the ontology identifier (sometimes referred to as the virtual identifier) or the ontology version identifier (sometimes referred to as the version id). The ontology identifier is used to identify and ontology and all of its versions. The ontology version identifier represents a single ontology version. The following screenshot shows how to identify these version numbers using the BioPortal Web UI.
 [[Image:Bioportal_internal_ontology_ids.png|200px|x]]

== How do I add or change categories? ==
<ol>
<li>Download the Protégé client '''(Version Protégé 3.4.4)'''</li>
<ol>
<li>[http://protege.stanford.edu/download/download.html http://protege.stanford.edu/download/download.html] 
</li>
</ol>
<li>Download a copy of the [http://www.bioontology.org/wiki/images/e/ef/Bioportal_metadata.pprj.zip BioPortal Metadata Protégé project file] and modify as follows</li>
<ol>
<li>Line 639: make sure this matches your BioPortal Ontology Services database (ip address or domain of the virtual appliance)</li>
<li>Line 649: this should be your MySQL username (bp_protege)</li>
<li>Line 654: this should be your MySQL password (bioportalprotege)</li>
<li>'''Note:''' These are the default username/password which should be changed for security purposes. If you have already changed them, please use the new username/password.</li>
</ol>
<li>Open the project file using Protégé</li>
<li>Go to the "Individuals" tab</li>
<li>Look for OMV:OntologyDomain and click it</li>
<li>A list of "Asserted Instances" should show up, these are the defaults</li>
<li>You can create or delete instances by clicking on the buttons</li>
<li>Instances should have the following properties:</li>
<ol>
<li>id = unique integer value</li>
<li>omv:name = display name for the category</li>
<li>omv:isSubDomainOf = you can create hierarchies by making
categories subDomains of one another</li>
</ol>
</ol>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
NCBO developers have created a script that can be used to automatically import ontologies from BioPortal or previous versions of the Virtual Appliance. The script was written in Ruby and is included on the Appliance. To use the script, do the following (requires knowledge of Linux command-line tools):

* Edit the script, located here: <code>/var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
** Make sure you have valid API keys for the FROM and TO systems.
** Assign the $FROM and $TO variables and ports as appropriate. The default configuration points to NCBO's BioPortal but can be changed to the location of your Virtual Appliance instance.
** The $ONTOLOGY_OWNER is the user id of the user who should own the ontologies on the TO system.
** $INCLUDE_ONTOLOGIES can be uncommented and used to import specific ontologies only. Otherwise all ontologies from the FROM system will be imported.
** Save your edits and continue below.
* Run the script using this command: <code>sh /var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
* The script will take some time to complete, updating the console as it runs. If automatic parsing is enabled, the ontologies should get parsed when the process next runs.

'''Please Note:''' The import script will attempt to use category and group IDs assigned to ontologies on the FROM system if they exist on the TO system as well. Ontology artifacts, such as notes, views, and mappings, are not imported. Only the most recent version of ontologies are imported; there is no method to import multiple versions of the same ontology using a common virtual id.

= Ontology Parsing =
== When are new ontologies parsed? ==
The BioPortal Ontology Services application uses a scheduler to run a process that collects newly submitted ontologies and parses them, adds them to the search index, and calculates metrics. You can also parse ontologies manually, but you will need to index them for search and calculate metrics manually to have that information available.

The default schedule can be disabled by doing the following:
* Open /ncbo/sources/bioportal/tags/1030/build.properties
* Look for the section that starts with "# Ontology Parse Scheduler properties"
* Set <code>ontology.parse.scheduler.enabled</code> to 'false'
* From the /ncbo/sources/bioportal/tags/1030/ directory, run 'ant clean deploywar'

== How do I manually parse an ontology? ==
To manually parse an ontology, visit the admin interface at http://example:8080/bioportal_admin and select "Parse Ontologies" from the list at the right. You must enter the version id, or a comma-separated list of ids, and then click "Run". The process will return with errors if it encounters any.

== How do I manually add an ontology to the search index? ==
To manually add an ontology to the search index, go to the admin interface and select "Index Ontologies". You can provide a single version id for an ontology or a comma-separated list of ids. You can also choose to index all ontologies currently stored in the Appliance (this may take some time if you have many terms in the system).

== How do I know if an ontology has parsed? ==
Because the BioPortal Web UI uses aggressive caching, it may not immediately reflect the status of an ontology once it's been submitted. By default the ontology status on the Web UI is updated once every four or 12 hours (depending where you are viewing the information). You can change these default options by doing the following:
* Open /var/rails/BioPortal/current/app/models/data_access.rb
* Change the following in the getOntologyList method:
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, MEDIUM_CACHE_EXPIRE_TIME)</code>
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, 60*15)</code>
* Change the following in the getOntology method:
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id })</code>
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id }, 60*15)</code>
* This will change the Web UI so that it refreshed information about ontologies every 15 minutes
* You will need to run /sbin/service httpd restart to have the change take affect
* '''NOTE:''' You will need to make this change again if you update the Web UI code. In addition, if you have a large list of ontologies this could slow down the Web UI for users as it will be required to retrieve more information more often.

In addition, you can look at the REST service directly, which will always give you the most updated information. To do this, visit the following URL:
* http://example:8080/bioportal/ontologies/{ontology_version_id}
* You can look for the statusId element to get the status, the codes are as follows:
** 1 - Waiting
** 2 - Parsing
** 3 - Ready
** 4 - Error
** 5 - Not Applicable (for metadata-only ontologies)

== Is there a log file for parsing? ==
Parsing progress is logged in the BioPortal Ontology Services log files.

There is a separate log file for OBO ontologies that can be monitored:
<code>tail -f /var/log/tomcat6/lexgrid/LexBIG_load_log.txt</code>

OWL and Protege-based ontologies are logged into the general log file:
<code>tail -f /var/log/tomcat6/bioportal.log</code>

== How can I manually remove the hierarchy information from an ontology like NCI Metathesaurus? ==
* Find the database prefix of the ontology by looking up the ontology in the LexEVS registry.xml file.
* Connect to the database that stores the LexEVS tables.
* Find the set of tables that stores the ontology using the table prefix.
* The table called codingSchemeSupportedAttrib needs to be updated to disable the hierarchy. To do so, find the row that has the column supportedAttributeTab that has a value called Hierarchy. Update that column to value HierarchyDisabled so that the loaded hierarchy is ignored.
* Restart Tomcat so that the new values are read in and the cache gets cleared.

= Systems Administration =

== How do I increase the Java heap size that Tomcat uses? ==
* By default we use a 512MB initial heap with a 2GB maximum. You can change these values by editing this file:
** <code>/usr/local/tomcat6/conf/tomcat6.conf</code>
* Change the following line to match your requirements. -Xms is initial size, -Xmx is maximum size.
** <code>JAVA_OPTS="${DEBUG} -Xms512m -Xmx2G -Djava.awt.headless=true -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"</code>
* Restart Tomcat by running the following command:
** <code>/sbin/service tomcat6 restart</code>

[[Category:NCBO Virtual Appliance]]

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==

=== Working with Javascript-based widgets (Form Autocomplete, Quick Jump/Jump To) ===
In addition to the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions], you must define an additional Javascript variable in order to have the widgets communicate with your instance of the Virtual Appliance.
<code>
var BP_SEARCH_SERVER = "http://{your_appliance_ip_or_domain_name}";
</code>
Replace the '{your_appliance_ip_or_domain_name}' text with the IP address or domain name that's assigned to your Virtual Appliance.

=== Working with Flex/Flash-based widgets (FlexViz, Ontology Tree Widget) ===

When working with Flash widgets, you'll need to modify the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions] to change and add your ip address or domain name. See below and look for '{your_appliance_ip_or_domain_name}' and '{ontology_id}'. The '{ontology_id}' is the numerical id for the ontology you want to use with the widget, sometimes called a virtual id. You can find this via the REST service by looking for the <ontologyId> element, or looking in the Web UI on the Browse page. The links for ontologies contain a number that should be the virtual id.

This example is for the Tree Browser.

<pre>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="OntologyTree" width="300" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<param name="allowScriptAccess" value="always" />
<param name="flashVars" value="ontology=<%= @ontology.ontologyId%>&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal" />
<embed src="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" quality="high" bgcolor="#ffffff"
width="300" height="100%" name="OntologyTree" align="middle"
play="true"
loop="false"
allowScriptAccess="always"
type="application/x-shockwave-flash"
flashVars="ontology={ontology_id}&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>
</pre>

In addition, there is a bug in existing versions of the Virtual Appliance that is scheduled to be fixed for the .5 version release in March 2012. Until then, you will need to run the following SQL commands to insert records into the 'bioportal' database:

<pre>
INSERT INTO `ncbo_user` (`id`, `username`, `api_key`, `open_id`, `password`, `email`, `firstname`, `lastname`, `phone`, `date_created`)
VALUES
(39108, 'annotator_flex', X'32626535656235352D383665622D343164362D386238312D653238653532356163633063', NULL, '8qQ8v8cjUZBCs99voQ2+i4mR1VhyFuj70ZCQUV9caXrPQv4K9FuDIfsfrn+ICoXp\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:09:32'),
(39109, 'search_flex', X'39626437366335382D323230642D346337662D386164302D306135363731313634313939', NULL, '/jj4oWOmI1SXbfczyReBZI9z4DSzRoZP/iX9WJe9lb/7vm1owez/yAh6lIRpNOyj\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:10:18'),
(39110, 'recommender_flex', X'35636564383837322D646636342D343838372D613338652D376338653736333935633830', NULL, 'RBmX8e1X2oUEEcqdp73/X7P7JkrfA7lbK8+svGPEojYmcmxDoHui3gC011Pg1cRF\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:11:16'),
(39111, 'flexviz', X'34363832396130352D386331632D343232622D393530642D313836373633616530663763', NULL, 'uivHblEQJII216fGfG0No4RGELzBtY7Bo14IQulDsQOJY4cLUItYuTtU+TkPs1ln\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:13:18');
</pre>

= How can I use the OVF image with my virtualization software? (VMWare, VirtualBox, KVM, Xen, etc) =

== VMWare ==
You can use [http://communities.vmware.com/community/vmtn/vsphere/automationtools/ovf VMWare's ovftool] to convert the appliance to work with your VMWare product. For example, to convert the appliance for use in VMWare Player or Workstation, you would run the command: <code>ovftool ncbo-appliance.ovf ncbo-appliance.vmx</code>

== VirtualBox ==
VirtualBox supports importing OVF images directly. Simply start your VirtualBox software, then select '''File->Import Appliance''' and select the OVF file included in the NCBO Virtual Appliance download.

Virtual Appliance FAQ

2012-03-06T23:11:44Z

Maseda: /* How can I use the OVF image with my virtualization software? (VMWare, VirtualBox, KVM, Xen, etc) */

= Ontology Management =

== How do I identify version numbers for ontologies stored in the system? ==
NCBO Ontology Web Services can be used with either the ontology identifier (sometimes referred to as the virtual identifier) or the ontology version identifier (sometimes referred to as the version id). The ontology identifier is used to identify and ontology and all of its versions. The ontology version identifier represents a single ontology version. The following screenshot shows how to identify these version numbers using the BioPortal Web UI.
 [[Image:Bioportal_internal_ontology_ids.png|200px|x]]

== How do I add or change categories? ==
<ol>
<li>Download the Protégé client '''(Version Protégé 3.4.4)'''</li>
<ol>
<li>[http://protege.stanford.edu/download/download.html http://protege.stanford.edu/download/download.html] 
</li>
</ol>
<li>Download a copy of the [http://www.bioontology.org/wiki/images/e/ef/Bioportal_metadata.pprj.zip BioPortal Metadata Protégé project file] and modify as follows</li>
<ol>
<li>Line 639: make sure this matches your BioPortal Ontology Services database (ip address or domain of the virtual appliance)</li>
<li>Line 649: this should be your MySQL username (bp_protege)</li>
<li>Line 654: this should be your MySQL password (bioportalprotege)</li>
<li>'''Note:''' These are the default username/password which should be changed for security purposes. If you have already changed them, please use the new username/password.</li>
</ol>
<li>Open the project file using Protégé</li>
<li>Go to the "Individuals" tab</li>
<li>Look for OMV:OntologyDomain and click it</li>
<li>A list of "Asserted Instances" should show up, these are the defaults</li>
<li>You can create or delete instances by clicking on the buttons</li>
<li>Instances should have the following properties:</li>
<ol>
<li>id = unique integer value</li>
<li>omv:name = display name for the category</li>
<li>omv:isSubDomainOf = you can create hierarchies by making
categories subDomains of one another</li>
</ol>
</ol>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
NCBO developers have created a script that can be used to automatically import ontologies from BioPortal or previous versions of the Virtual Appliance. The script was written in Ruby and is included on the Appliance. To use the script, do the following (requires knowledge of Linux command-line tools):

* Edit the script, located here: <code>/var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
** Make sure you have valid API keys for the FROM and TO systems.
** Assign the $FROM and $TO variables and ports as appropriate. The default configuration points to NCBO's BioPortal but can be changed to the location of your Virtual Appliance instance.
** The $ONTOLOGY_OWNER is the user id of the user who should own the ontologies on the TO system.
** $INCLUDE_ONTOLOGIES can be uncommented and used to import specific ontologies only. Otherwise all ontologies from the FROM system will be imported.
** Save your edits and continue below.
* Run the script using this command: <code>sh /var/rails/BioPortal/current/util/import_ontologies/import_ontologies.rb</code>
* The script will take some time to complete, updating the console as it runs. If automatic parsing is enabled, the ontologies should get parsed when the process next runs.

'''Please Note:''' The import script will attempt to use category and group IDs assigned to ontologies on the FROM system if they exist on the TO system as well. Ontology artifacts, such as notes, views, and mappings, are not imported. Only the most recent version of ontologies are imported; there is no method to import multiple versions of the same ontology using a common virtual id.

= Ontology Parsing =
== When are new ontologies parsed? ==
The BioPortal Ontology Services application uses a scheduler to run a process that collects newly submitted ontologies and parses them, adds them to the search index, and calculates metrics. You can also parse ontologies manually, but you will need to index them for search and calculate metrics manually to have that information available.

The default schedule can be disabled by doing the following:
* Open /ncbo/sources/bioportal/tags/1030/build.properties
* Look for the section that starts with "# Ontology Parse Scheduler properties"
* Set <code>ontology.parse.scheduler.enabled</code> to 'false'
* From the /ncbo/sources/bioportal/tags/1030/ directory, run 'ant clean deploywar'

== How do I manually parse an ontology? ==
To manually parse an ontology, visit the admin interface at http://example:8080/bioportal_admin and select "Parse Ontologies" from the list at the right. You must enter the version id, or a comma-separated list of ids, and then click "Run". The process will return with errors if it encounters any.

== How do I manually add an ontology to the search index? ==
To manually add an ontology to the search index, go to the admin interface and select "Index Ontologies". You can provide a single version id for an ontology or a comma-separated list of ids. You can also choose to index all ontologies currently stored in the Appliance (this may take some time if you have many terms in the system).

== How do I know if an ontology has parsed? ==
Because the BioPortal Web UI uses aggressive caching, it may not immediately reflect the status of an ontology once it's been submitted. By default the ontology status on the Web UI is updated once every four or 12 hours (depending where you are viewing the information). You can change these default options by doing the following:
* Open /var/rails/BioPortal/current/app/models/data_access.rb
* Change the following in the getOntologyList method:
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, MEDIUM_CACHE_EXPIRE_TIME)</code>
** <code>return self.cache_pull("ont_list", "getOntologyList", nil, 60*15)</code>
* Change the following in the getOntology method:
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id })</code>
** <code>return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id }, 60*15)</code>
* This will change the Web UI so that it refreshed information about ontologies every 15 minutes
* You will need to run /sbin/service httpd restart to have the change take affect
* '''NOTE:''' You will need to make this change again if you update the Web UI code. In addition, if you have a large list of ontologies this could slow down the Web UI for users as it will be required to retrieve more information more often.

In addition, you can look at the REST service directly, which will always give you the most updated information. To do this, visit the following URL:
* http://example:8080/bioportal/ontologies/{ontology_version_id}
* You can look for the statusId element to get the status, the codes are as follows:
** 1 - Waiting
** 2 - Parsing
** 3 - Ready
** 4 - Error
** 5 - Not Applicable (for metadata-only ontologies)

== Is there a log file for parsing? ==
Parsing progress is logged in the BioPortal Ontology Services log files.

There is a separate log file for OBO ontologies that can be monitored:
<code>tail -f /var/log/tomcat6/lexgrid/LexBIG_load_log.txt</code>

OWL and Protege-based ontologies are logged into the general log file:
<code>tail -f /var/log/tomcat6/bioportal.log</code>

== How can I manually remove the hierarchy information from an ontology like NCI Metathesaurus? ==
* Find the database prefix of the ontology by looking up the ontology in the LexEVS registry.xml file.
* Connect to the database that stores the LexEVS tables.
* Find the set of tables that stores the ontology using the table prefix.
* The table called codingSchemeSupportedAttrib needs to be updated to disable the hierarchy. To do so, find the row that has the column supportedAttributeTab that has a value called Hierarchy. Update that column to value HierarchyDisabled so that the loaded hierarchy is ignored.
* Restart Tomcat so that the new values are read in and the cache gets cleared.

= Systems Administration =

== How do I increase the Java heap size that Tomcat uses? ==
* By default we use a 512MB initial heap with a 2GB maximum. You can change these values by editing this file:
** <code>/usr/local/tomcat6/conf/tomcat6.conf</code>
* Change the following line to match your requirements. -Xms is initial size, -Xmx is maximum size.
** <code>JAVA_OPTS="${DEBUG} -Xms512m -Xmx2G -Djava.awt.headless=true -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"</code>
* Restart Tomcat by running the following command:
** <code>/sbin/service tomcat6 restart</code>

[[Category:NCBO Virtual Appliance]]

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==

=== Working with Javascript-based widgets (Form Autocomplete, Quick Jump/Jump To) ===
In addition to the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions], you must define an additional Javascript variable in order to have the widgets communicate with your instance of the Virtual Appliance.
<code>
var BP_SEARCH_SERVER = "http://{your_appliance_ip_or_domain_name}";
</code>
Replace the '{your_appliance_ip_or_domain_name}' text with the IP address or domain name that's assigned to your Virtual Appliance.

=== Working with Flex/Flash-based widgets (FlexViz, Ontology Tree Widget) ===

When working with Flash widgets, you'll need to modify the [http://www.bioontology.org/wiki/index.php/NCBO_Widgets#How_to_use_NCBO_Widgets existing instructions] to change and add your ip address or domain name. See below and look for '{your_appliance_ip_or_domain_name}' and '{ontology_id}'. The '{ontology_id}' is the numerical id for the ontology you want to use with the widget, sometimes called a virtual id. You can find this via the REST service by looking for the <ontologyId> element, or looking in the Web UI on the Browse page. The links for ontologies contain a number that should be the virtual id.

This example is for the Tree Browser.

<pre>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="OntologyTree" width="300" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<param name="allowScriptAccess" value="always" />
<param name="flashVars" value="ontology=<%= @ontology.ontologyId%>&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal" />
<embed src="http://{your_appliance_ip_or_domain_name}/flex/OntologyTree.swf" quality="high" bgcolor="#ffffff"
width="300" height="100%" name="OntologyTree" align="middle"
play="true"
loop="false"
allowScriptAccess="always"
type="application/x-shockwave-flash"
flashVars="ontology={ontology_id}&alerterrors=false&canchangeontology=false&virtual=true&server=http://{your_appliance_ip_or_domain_name}:8080/bioportal"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>
</pre>

In addition, there is a bug in existing versions of the Virtual Appliance that is scheduled to be fixed for the .5 version release in March 2012. Until then, you will need to run the following SQL commands to insert records into the 'bioportal' database:

<pre>
INSERT INTO `ncbo_user` (`id`, `username`, `api_key`, `open_id`, `password`, `email`, `firstname`, `lastname`, `phone`, `date_created`)
VALUES
(39108, 'annotator_flex', X'32626535656235352D383665622D343164362D386238312D653238653532356163633063', NULL, '8qQ8v8cjUZBCs99voQ2+i4mR1VhyFuj70ZCQUV9caXrPQv4K9FuDIfsfrn+ICoXp\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:09:32'),
(39109, 'search_flex', X'39626437366335382D323230642D346337662D386164302D306135363731313634313939', NULL, '/jj4oWOmI1SXbfczyReBZI9z4DSzRoZP/iX9WJe9lb/7vm1owez/yAh6lIRpNOyj\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:10:18'),
(39110, 'recommender_flex', X'35636564383837322D646636342D343838372D613338652D376338653736333935633830', NULL, 'RBmX8e1X2oUEEcqdp73/X7P7JkrfA7lbK8+svGPEojYmcmxDoHui3gC011Pg1cRF\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:11:16'),
(39111, 'flexviz', X'34363832396130352D386331632D343232622D393530642D313836373633616530663763', NULL, 'uivHblEQJII216fGfG0No4RGELzBtY7Bo14IQulDsQOJY4cLUItYuTtU+TkPs1ln\r\n', 'example@domain.org', X'', X'', NULL, '2011-06-28 12:13:18');
</pre>

= How can I use the OVF image with my virtualization software? (VMWare, VirtualBox, KVM, Xen, etc) =

== VMWare ==
You can use [http://communities.vmware.com/community/vmtn/vsphere/automationtools/ovf VMWare's ovftool] to convert the appliance to work with your VMWare product. For example, to convert the appliance for use in WMWare Player or Workstation, you would run the command: <code>ovftool ncbo-appliance.ovf ncbo-appliance.vmx</code>

== VirtualBox ==
VirtualBox supports importing OVF images directly. Simply start your VirtualBox software, then select '''File->Import Appliance''' and select the OVF file included in the NCBO Virtual Appliance download.