Difference between revisions of "Virtual Appliance FAQ"

From NCBO Wiki
Jump to navigation Jump to search
Line 32: Line 32:
 
   </ol>
 
   </ol>
 
</ol>
 
</ol>
 +
 +
== Migrating ontologies from BioPortal or previous NCBO Virtual Appliance versions ==
 +
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></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 </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 =
 
= Ontology Parsing =

Revision as of 15:09, 1 August 2011

Ontology Management

How do I identify version numbers for ontologies stored in the system?

BioPortal Ontology Services uses two version numbers to identify ontologies. The first is referred to as the ontology id or sometimes the virtual id. This id is used to identify and ontology and all of its versions. The second id is referred to as the version id, which identifies a single instance of an ontology that is part of a virtual id. The following screenshot shows how to identify the versions using the BioPortal Web UI.
x

How do I add or change categories?

  1. Download the Protégé client (Version Protégé 3.4.4)
    1. http://protege.stanford.edu/download/download.html
  2. Download a copy of the BioPortal Metadata Protégé project file and modify as follows
    1. Line 639: make sure this matches your BioPortal Ontology Services database (ip address or domain of the virtual appliance)
    2. Line 649: this should be your MySQL username (bp_protege)
    3. Line 654: this should be your MySQL password (bioportalprotege)
    4. 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.
  3. Open the project file using Protégé
  4. Go to the "Individuals" tab
  5. Look for OMV:OntologyDomain and click it
  6. A list of "Asserted Instances" should show up, these are the defaults
  7. You can create or delete instances by clicking on the buttons
  8. Instances should have the following properties:
    1. id = unique integer value
    2. omv:name = display name for the category
    3. omv:isSubDomainOf = you can create hierarchies by making categories subDomains of one another

Migrating ontologies from BioPortal or previous NCBO Virtual Appliance versions

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: -- 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: sh - 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 ontology.parse.scheduler.enabled 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 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:
    • return self.cache_pull("ont_list", "getOntologyList", nil, MEDIUM_CACHE_EXPIRE_TIME)
    • return self.cache_pull("ont_list", "getOntologyList", nil, 60*15)
  • Change the following in the getOntology method:
    • return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id })
    • return self.cache_pull("#{ontology_id}::_details", "getOntology", { :ontology_id => ontology_id }, 60*15)
  • 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:

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: tail -f /var/log/tomcat6/lexgrid/LexBIG_load_log.txt

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

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:
    • /usr/local/tomcat6/conf/tomcat6.conf
  • Change the following line to match your requirements. -Xms is initial size, -Xmx is maximum size.
    • JAVA_OPTS="${DEBUG} -Xms512m -Xmx2G -Djava.awt.headless=true -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"
  • Restart Tomcat by running the following command:
    • /sbin/service tomcat6 restart