NCBO Wiki - User contributions [en]

SKOSSupport

2020-09-18T10:17:37Z

Graybeal: added concrete example

[[File:Plos_thesaurus_class_tree.png|thumb|400px|PLOS Thesaurus concept tree in BioPortal]]

__TOC__

=== Support for SKOS vocabularies in BioPortal ===

BioPortal is a web-based portal for accessing and sharing ontologies. The application accepts ontology submissions in OWL and OBO format, and SKOS vocabularies that contain particular constructs.

This wiki page documents the minimum set of SKOS constructs that must be present in a SKOS vocabulary for BioPortal to accept and handle the submission properly.

Please note that the SKOS constructs described here are handled only for vocabularies that are identified as SKOS when they are submitted to BioPortal. Vocabularies submitted as OWL or OBO formats are not examined for SKOS constructs.

==== Required SKOS constructs ====

===== skos:Concept =====

''Concepts'' are the fundamental elements of SKOS vocabularies and are asserted using the skos:Concept class, e.g.:

<nowiki><http://www.example.com/animals></nowiki> rdf:type skos:Concept

In SKOS vocabularies, BioPortal only treats the SKOS concept assertions as concepts to be displayed. If the vocabulary contains other assertions about other types of concepts, BioPortal will not treat these as concepts in any of its displays or features.

See the W3C's SKOS System Primer and SKOS Reference for concept documentation and examples:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secconcept

https://www.w3.org/TR/skos-reference/#concepts

'''Note:''' Some OWL ontologies declare the SKOS namespace to facilitate minimal use of SKOS constructs for things like labels (e.g., skos:prefLabel, skos:altLabel) or mappings (e.g., skos:exactMatch, skos:broaderMatch). In these cases, the proper format for new ontology submissions is OWL, not SKOS.

===== skos:ConceptScheme & skos:hasTopConcept =====

For every ontology entry in BioPortal, the application provides a tabbed interface with various views of the ontology data, e.g., a "Classes" tab with a tree structure to graphically depict the hierarchical collection of ontology classes.

In the case of SKOS vocabularies, BioPortal determines which concepts to display as roots in the concept tree by querying vocabulary content for occurrences of skos:hasTopConcept property assertions. Top concepts are the most general concepts contained in SKOS concept schemes (an aggregation of one or more SKOS concepts).

The following example, taken from the SKOS System Primer, shows how to define a concept scheme and link it to the most general concepts it contains:

@prefix skos: <nowiki><http://www.w3.org/2004/02/skos/core#></nowiki> .
@prefix rdf: <nowiki><http://www.w3.org/1999/02/22-rdf-syntax-ns#></nowiki> .
@prefix ex: <nowiki><http://www.example.com/></nowiki> .

ex:animalThesaurus rdf:type skos:ConceptScheme;
skos:hasTopConcept ex:mammals;
skos:hasTopConcept ex:fish.

SKOS vocabularies submitted to BioPortal must contain a minimum of one concept scheme and top concept assertion. See the the SKOS System Primer and SKOS Reference for more documentation of concept schemes and top concepts:

https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secscheme

https://www.w3.org/TR/skos-reference/#schemes

If your vocabulary declares more than one concept scheme, all of the top concepts will be aggregated and displayed as root level concepts. BioPortal's user interface doesn't provide support for grouping top level concepts by concept scheme. It is recommended to declare a owl:Ontology, especially for metadata annotations.

==== Hierarchy in SKOS vocabularies ====

The only semantic relationship in SKOS vocabularies that BioPortal uses to construct and display concept hierarchies is the skos:broader property.

ex:mammals rdf:type skos:Concept;
skos:prefLabel "mammals"@en;
skos:broader ex:animals.

Other properties used to denote hierarchical relationships like skos:narrower, skos:broaderTransitive, and skos:narrowerTranstive, are ignored.

==== Metrics data for SKOS vocabularies ====

BioPortal uses the [https://owlcs.github.io/owlapi/ OWL API] for parsing all ontology and vocabulary submissions, as well as for the calculation of metrics data. The OWL API treats SKOS vocabularies as RDF files containing classes and instances. According to the SKOS Reference, concepts are [https://www.w3.org/TR/skos-reference/#L842 instances of owl:Class], and thus are counted as instances (a.k.a. "individuals").

When viewing metrics tables in the BioPortal user interface, the value for the "NUMBER OF INDIVIDUALS" corresponds to the number of concepts in any given SKOS vocabulary.

[[File:Metrics.png|none|frame|PLOS Thesaurus metrics in BioPortal]]

==== SKOS-XL ====

Currently BioPortal offers no support for the [https://www.w3.org/TR/skos-reference/#xl SKOS eXtension for Labels (SKOS-XL)]. A suggested workaround for SKOS vocabularies that make use of SKOS-XL, is to dump the value of labels (i.e., skosxl:literalForm of skosxl:*Label instances) into the corresponding skos:*Label property.

==== SKOS mapping properties ====

At this time, BioPortal doesn't use SKOS mapping properties, i.e., skos:*Match, to populate the mapping repository. One-to-one mappings between SKOS concepts need to be uploaded separately via the [http://data.bioontology.org/documentation BioPortal REST API].

=== Example of valid SKOS ===

This example provides a simple illustration of the composition of a SKOS file that complies with the above constraints.

==== Example header ====

The header shown here defines a few typical namespaces that may be useful.

The last namespace is the one that defines this SKOS vocabulary. Ideally, the IRI defining the myskosid namespace is the resolvable location of the SKOS ontology.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:dct="http://purl.org/dc/terms/"
xmlns:myskosid="https://example.org/ontologies/myskosontology/"
>

==== Example ontology description ====

In the rdf:type item, this namespace is declared as the ConceptScheme. The ConceptScheme does not have to be the same as the namespace of the ontology.

Other metadata is provided as an example of good practices in ontology metadata. The dct:creator does not have to be an ORCID ID, but a unique identifier is an ideal way of naming a creator (whether individual or organization).

This ontology has only 2 concepts (to be defined below), hence only 2 skos:hasTopConcept declarations.

<rdf:Description rdf:about="https://example.org/ontologies/myskosontology/">
<rdfs:label xml:lang="en">Example SKOS ontology for BioPortal</rdfs:label>
<rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#ConceptScheme"/>
<rdfs:comment xml:lang="en">Example created to simplify understanding and creation of a SKOS vocab for BioPortal</rdfs:comment>
<dct:created rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2020-09-16</dct:created>
<dct:modified rdf:datatype="http://www.w3.org/2001/XMLSchema#date">2020-09-16</dct:modified>
<dct:license rdf:resource="https://creativecommons.org/licenses/by/4.0/"/>
<dct:creator rdf:resource="https://orcid.org/0000-0001-6875-5360"/>
<skos:hasTopConcept rdf:resource="https://example.org/ontologies/myskosontology/fragmentid001"/>
<skos:hasTopConcept rdf:resource="https://example.org/ontologies/myskosontology/fragmentid002"/>
</rdf:Description>

==== Example term definitions ====

This section shows the two concepts and a few typical annotations about those concepts. The first rdf:Description line of each group names the concept that is being defined in the indented lines following.

The rdf:Type and skos:prefLabel are required annotation content for BioPortal to work effectively. Other items are optional.

The skos:topConceptOf is not strictly required for BioPortal SKOS ontologies, but provides useful contextualization if there is more than one topConcept.

<rdf:Description rdf:about="https://example.org/ontologies/myskosontology/fragmentid001">
<rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
<skos:prefLabel xml:lang="en">First concept</skos:prefLabel>
<skos:definition xml:lang="en">The very first example provided as part of this ontology.</skos:definition>
<skos:topConceptOf rdf:resource="https://example.org/ontologies/myskosontology/"/>
</rdf:Description>
<rdf:Description rdf:about="https://example.org/ontologies/myskosontology/fragmentid002">
<rdf:type rdf:resource="http://www.w3.org/2004/02/skos/core#Concept"/>
<skos:prefLabel xml:lang="en">Second Concept</skos:prefLabel>
<skos:definition xml:lang="en">The second example provided as part of this ontology.</skos:definition>
<skos:topConceptOf rdf:resource="https://example.org/ontologies/myskosontology/"/>
</rdf:Description>

==== Closing XML ====

Needed for a complete, parseable RDF file!

</rdf:RDF>

Virtual Appliance FAQ

2020-06-13T03:26:31Z

Graybeal: improving formatting emphasis

[[Category:NCBO Virtual Appliance]]
[[Category:Migrated to GitHub]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular '''this content''' is mostly at the '''[https://https://ontoportal.github.io/administration/general/faq/ Frequently Asked Questions (FAQ) page]'''.

= '''ARCHIVAL''' ONTOPORTAL VIRTUAL APPLIANCE v2.5 FAQ '''ARCHIVAL''' =

This page is the archival FAQ for the the Ontoportal Virtual Appliance v2.5.

The FAQ for v1.0 is available in the [http://www.bioontology.org/wiki/index.php?title=Virtual_Appliance_FAQ&oldid=12621 archive]

= General =
== How do I access Virtual Appliance? ==

Virtual Appliance Web UI can be accessed by going to http://{your_appliance_ip_or_domain_name} on your web browser. 
API can be accessed at http://{your_appliance_ip_or_domain_name}:8080

You can get IP address of the Appliance with the following methods:
* Local IP Address from terminal:
<code>ip address show eth0 | awk '/inet / {print $2}' | cut -d/ -f1'</code>
* External IP address from the terminal:
<code>curl http://ipecho.net/plain; echo</code>
* Vmware Appliance:
Check 'IP Addresses' on the summary page of the appliance. Please note that Virtual Appliance does not come with vmware tools installed so IP Address would not be displayed until vmware tools are installed.
* Amazon AWS:
use Public IP Addresses or Public DNS listed in your EC2 management console.

== How can I enable emails for lost passwords, notes, and ontology processing? ==

Emails are sent via the ontologies_api project on the Appliance. You need to provide a valid mail server (smtp) configuration. The configuration should be provided in the /srv/ncbo/ontologies_api/current/config/environments/production.rb file.

Here are the available settings:
<code>
config.enable_notifications = true # Set to 'true' to send emails
config.email_sender = "admin@example.org" # Default sender for emails
config.email_disable_override = true # If this is set to 'false', all emails will be sent to the email configured in the 'email_override' setting
config.email_override = "admin@example.org"
config.smtp_host = "smtp.example.org"
config.smtp_port = 25
config.smtp_auth_type = :none # :none, :plain, :login, :cram_md5
config.smtp_user = "username" # only used if auth_type is not :none
config.smtp_password = "password" # only used if auth_type is not :none
config.smtp_domain = "example.org"
</code>

Once you have changed your settings, you will need to restart the server by running the command <code>/sbin/service unicorn restart</code>

== Can I use the Annotator and Recommender on their own? ==

Because services like the Annotator and Recommender depend on the Ontologies API in BioPortal, you can not usefully install those services in a stand-alone way without also installing the core BioPortal software and ontologies.

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface. Categories and groups can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
category = LinkedData::Models::Category.new
category.name = "My Category"
category.acronym = "MY_CAT"
category.save
group = LinkedData::Models::Group.new
group.name = "My Group"
group.acronym = "MY_GRP"
group.save
</pre>

== How do I add or change slices? ==
There is currently no UI administrator interface. Slices can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ont1 = LinkedData::Models::Ontology.find("ONT1").first
ont2 = LinkedData::Models::Ontology.find("ONT2").first
slice = LinkedData::Models::Slice.new
slice.name = "My Slice",
slice.description = "This is my custom slice",
slice.acronym = "my_slice",
slice.ontologies = [ont1, ont2]
slice.save
</pre>

== How do I delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ONTOLOGY_ACRONYM").first
ontology.delete
</pre>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==

Programmatic migrations are not officially supported ("Ontologies can be manually downloaded and added using the Web UI") but we included a script for importing ontologies.

/srv/ncbo/virtual_appliance/deployment/utils/bioportal_ontologies_import.rb, you will need to modify SOURCE_API, SOURCE_APIKEY and ONTOLOGIES_TO_IMPORT variables.

== How can I restrict ontology downloads via the UI? ==

This line of code should be modified to include the acronyms of the ontologies for which you want to restrict downloads via the UI:

https://github.com/ncbo/bioportal_web_ui/blob/master/app/views/ontologies/_submissions.html.haml#L32

This will prevent the “Downloads” column in the Submissions table from appearing on ontology summary pages.

If you want to restrict download via the REST endpoint, you need to modify your environment configuration files (e.g., production.rb, staging.rb, etc.) in your ontologies_api project. The production.rb file should contain a “config.restrict_download” property -- there’s an example of what it should look like in the sample configuration file in GitHub:

https://github.com/ncbo/ontologies_api/blob/master/config/environments/config.rb.sample#L38

= Ontology Parsing =
== When are new ontologies parsed? ==
The ncbo_cron project uses a scheduler to run a process that collects new ontology submissions and parses them, adds them to the search index, calculates metrics, and processes them for use with the annotator. You can also parse ontologies manually.

== How do I manually parse an ontology? ==
To manually parse an ontology, you will need to interact with the code using the console after switching to ontoportal user:
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ACRONYM").first
submission = ontology.latest_submission(status: :any)
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_term_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== How can I process a UMLS ontology? ==

UMLS ontologies can be processed to work with our system by converting them to RDF. There is no automated way to do this and you must have your own UMLS MySQL installation and an OSX/Linux/Unix machine with 8GB+ of RAM in order for the conversion process to work. The scripts to convert UMLS to RDF are available on [https://github.com/ncbo/umls2rdf Github].

Once you have converted UMLS to RDF, you will get Turtle (.ttl) files that can be uploaded using the BioPortal Web UI. Please select UMLS as the format for these ontologies.

== How do I know if an ontology has parsed? ==
The BioPortal Web UI will cache information about ontologies for 60 seconds. After parsing is complete, just refresh the ontology summary page to see the status for the most recent submission listed under the "Submissions" table.

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://{your_appliance_ip_or_domain_name}:8080/ontologies/{ontology_acronym}/latest_submission?include=all
* You can look for the submissionStatus attribute to get the status

== Is there a log file for parsing? ==
Parsing progress is logged in the ontology submission repository folder:
/srv/ncbo/repository/{ontology acronym}/{submission id}

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://{your_appliance_ip_or_domain_name}/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? ==
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.

= Virtualization Environments =

== 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:

<pre>
ovftool ncbo-appliance.ovf ncbo-appliance.vmx
</pre>

=== 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 ===
First, convert the OVF to VMX format as mentioned in the VMware section above.

Next, ensure that the <code>kvm-qemu-img</code> RPM (or <code>qemu-kvm</code> DEB) is installed. Then, convert the [new] VMDKs (from the VMX conversion step) to raw disk images via the following command:

<pre>for disk in `ls -1 *.vmdk`; do diskbase=`basename $disk .vmdk`; qemu-img convert -O raw ${diskbase}.vmdk ${diskbase}.img; done</pre>

Create <code>/etc/libvirt/qemu/ncbo-appliance.xml</code> with the following contents:

<pre>
<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/ncbo-appliance-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/ncbo-appliance-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>
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
virsh start ncbo-appliance
</pre>

=== Xen ===
First, convert the VMDKs to raw disk images as mentioned in the KVM section above.

Create <code>/etc/xen/ncbo-appliance.cfg</code> with the following contents:

<pre>
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/ncbo-appliance-disk1.img,hda,w", "file:/var/lib/xen/images/ncbo-appliance/ncbo-appliance-disk2.img,hdb,w" ]
vif = [ "bridge=xenbr0,script=vif-bridge,vifname=vif41.0" ]
parallel = "none"
serial = "pty"
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
xm create ncbo-appliance
</pre>

== How can I use the Appliance on Amazon EC2? ==

Appliance is available on [https://aws.amazon.com/marketplace/pp/B00MX5YKVU Amazon Marketplace]

=== What is the admin password for the AWS Appliance? ===

The default application administrator is 'admin' and the initial password is the Instance ID (i-xxxxxxxx). Please change this as soon as you install the virtual appliance.

Virtual Appliance FAQ

2020-06-13T03:24:40Z

Graybeal: forwarded to new content

[[Category:NCBO Virtual Appliance]]
[[Category:Migrated to GitHub]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular '''this content''' is mostly at the '''[https://https://ontoportal.github.io/administration/general/faq/ Frequently Asked Questions (FAQ) page]'''.

= ARCHIVAL ONTOPORTAL VIRTUAL APPLIANCE v2.5 FAQ =

This FAQ now covers the Ontoportal Virtual Appliance v2.5 The FAQ for v1.0 is available in the [http://www.bioontology.org/wiki/index.php?title=Virtual_Appliance_FAQ&oldid=12621 archive]

= General =
== How do I access Virtual Appliance? ==

Virtual Appliance Web UI can be accessed by going to http://{your_appliance_ip_or_domain_name} on your web browser. 
API can be accessed at http://{your_appliance_ip_or_domain_name}:8080

You can get IP address of the Appliance with the following methods:
* Local IP Address from terminal:
<code>ip address show eth0 | awk '/inet / {print $2}' | cut -d/ -f1'</code>
* External IP address from the terminal:
<code>curl http://ipecho.net/plain; echo</code>
* Vmware Appliance:
Check 'IP Addresses' on the summary page of the appliance. Please note that Virtual Appliance does not come with vmware tools installed so IP Address would not be displayed until vmware tools are installed.
* Amazon AWS:
use Public IP Addresses or Public DNS listed in your EC2 management console.

== How can I enable emails for lost passwords, notes, and ontology processing? ==

Emails are sent via the ontologies_api project on the Appliance. You need to provide a valid mail server (smtp) configuration. The configuration should be provided in the /srv/ncbo/ontologies_api/current/config/environments/production.rb file.

Here are the available settings:
<code>
config.enable_notifications = true # Set to 'true' to send emails
config.email_sender = "admin@example.org" # Default sender for emails
config.email_disable_override = true # If this is set to 'false', all emails will be sent to the email configured in the 'email_override' setting
config.email_override = "admin@example.org"
config.smtp_host = "smtp.example.org"
config.smtp_port = 25
config.smtp_auth_type = :none # :none, :plain, :login, :cram_md5
config.smtp_user = "username" # only used if auth_type is not :none
config.smtp_password = "password" # only used if auth_type is not :none
config.smtp_domain = "example.org"
</code>

Once you have changed your settings, you will need to restart the server by running the command <code>/sbin/service unicorn restart</code>

== Can I use the Annotator and Recommender on their own? ==

Because services like the Annotator and Recommender depend on the Ontologies API in BioPortal, you can not usefully install those services in a stand-alone way without also installing the core BioPortal software and ontologies.

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface. Categories and groups can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
category = LinkedData::Models::Category.new
category.name = "My Category"
category.acronym = "MY_CAT"
category.save
group = LinkedData::Models::Group.new
group.name = "My Group"
group.acronym = "MY_GRP"
group.save
</pre>

== How do I add or change slices? ==
There is currently no UI administrator interface. Slices can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ont1 = LinkedData::Models::Ontology.find("ONT1").first
ont2 = LinkedData::Models::Ontology.find("ONT2").first
slice = LinkedData::Models::Slice.new
slice.name = "My Slice",
slice.description = "This is my custom slice",
slice.acronym = "my_slice",
slice.ontologies = [ont1, ont2]
slice.save
</pre>

== How do I delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ONTOLOGY_ACRONYM").first
ontology.delete
</pre>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==

Programmatic migrations are not officially supported ("Ontologies can be manually downloaded and added using the Web UI") but we included a script for importing ontologies.

/srv/ncbo/virtual_appliance/deployment/utils/bioportal_ontologies_import.rb, you will need to modify SOURCE_API, SOURCE_APIKEY and ONTOLOGIES_TO_IMPORT variables.

== How can I restrict ontology downloads via the UI? ==

This line of code should be modified to include the acronyms of the ontologies for which you want to restrict downloads via the UI:

https://github.com/ncbo/bioportal_web_ui/blob/master/app/views/ontologies/_submissions.html.haml#L32

This will prevent the “Downloads” column in the Submissions table from appearing on ontology summary pages.

If you want to restrict download via the REST endpoint, you need to modify your environment configuration files (e.g., production.rb, staging.rb, etc.) in your ontologies_api project. The production.rb file should contain a “config.restrict_download” property -- there’s an example of what it should look like in the sample configuration file in GitHub:

https://github.com/ncbo/ontologies_api/blob/master/config/environments/config.rb.sample#L38

= Ontology Parsing =
== When are new ontologies parsed? ==
The ncbo_cron project uses a scheduler to run a process that collects new ontology submissions and parses them, adds them to the search index, calculates metrics, and processes them for use with the annotator. You can also parse ontologies manually.

== How do I manually parse an ontology? ==
To manually parse an ontology, you will need to interact with the code using the console after switching to ontoportal user:
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ACRONYM").first
submission = ontology.latest_submission(status: :any)
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_term_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== How can I process a UMLS ontology? ==

UMLS ontologies can be processed to work with our system by converting them to RDF. There is no automated way to do this and you must have your own UMLS MySQL installation and an OSX/Linux/Unix machine with 8GB+ of RAM in order for the conversion process to work. The scripts to convert UMLS to RDF are available on [https://github.com/ncbo/umls2rdf Github].

Once you have converted UMLS to RDF, you will get Turtle (.ttl) files that can be uploaded using the BioPortal Web UI. Please select UMLS as the format for these ontologies.

== How do I know if an ontology has parsed? ==
The BioPortal Web UI will cache information about ontologies for 60 seconds. After parsing is complete, just refresh the ontology summary page to see the status for the most recent submission listed under the "Submissions" table.

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://{your_appliance_ip_or_domain_name}:8080/ontologies/{ontology_acronym}/latest_submission?include=all
* You can look for the submissionStatus attribute to get the status

== Is there a log file for parsing? ==
Parsing progress is logged in the ontology submission repository folder:
/srv/ncbo/repository/{ontology acronym}/{submission id}

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://{your_appliance_ip_or_domain_name}/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? ==
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.

= Virtualization Environments =

== 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:

<pre>
ovftool ncbo-appliance.ovf ncbo-appliance.vmx
</pre>

=== 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 ===
First, convert the OVF to VMX format as mentioned in the VMware section above.

Next, ensure that the <code>kvm-qemu-img</code> RPM (or <code>qemu-kvm</code> DEB) is installed. Then, convert the [new] VMDKs (from the VMX conversion step) to raw disk images via the following command:

<pre>for disk in `ls -1 *.vmdk`; do diskbase=`basename $disk .vmdk`; qemu-img convert -O raw ${diskbase}.vmdk ${diskbase}.img; done</pre>

Create <code>/etc/libvirt/qemu/ncbo-appliance.xml</code> with the following contents:

<pre>
<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/ncbo-appliance-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/ncbo-appliance-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>
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
virsh start ncbo-appliance
</pre>

=== Xen ===
First, convert the VMDKs to raw disk images as mentioned in the KVM section above.

Create <code>/etc/xen/ncbo-appliance.cfg</code> with the following contents:

<pre>
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/ncbo-appliance-disk1.img,hda,w", "file:/var/lib/xen/images/ncbo-appliance/ncbo-appliance-disk2.img,hdb,w" ]
vif = [ "bridge=xenbr0,script=vif-bridge,vifname=vif41.0" ]
parallel = "none"
serial = "pty"
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
xm create ncbo-appliance
</pre>

== How can I use the Appliance on Amazon EC2? ==

Appliance is available on [https://aws.amazon.com/marketplace/pp/B00MX5YKVU Amazon Marketplace]

=== What is the admin password for the AWS Appliance? ===

The default application administrator is 'admin' and the initial password is the Instance ID (i-xxxxxxxx). Please change this as soon as you install the virtual appliance.

Importing UMLS To Virtual Appliance

2020-06-13T01:26:43Z

Graybeal: added Migrated category

Google Analytics

2020-06-13T01:26:06Z

Graybeal: added Migrated category

Annotator Documentation

2020-06-13T01:24:53Z

Graybeal: formatting and added Migrated tag

Category:NCBO Virtual Appliance

2020-06-13T01:23:32Z

Graybeal: added Migrated category

[[Category:NCBO Virtual Appliance]]
[[Category:Migrated to GitHub]]

'''''Most of this content has been moved!''''' Please find the new content for the 3.0 version of the Virtual Appliance at our new '''[https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages]'''.

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== Virtual Appliance Administration Documentation: Moved to GitHub ==

Our Administration documentation for the OntoPortal Virtual Appliance has been moved to the GitHub pages document at https://ontoportal.github.io/administration/.

== Archival ==

=== OntoPortal Virtual Appliance v2.5 archive is available ===

For previous registered users of the v2.5 OntoPortal Virtual Appliance, we maintain an archival copy of this software on our site. While we do not actively support this version because its libraries are outdated, we still make it available to those users who were previously authorized to use it. All new users of the Virtual Appliance should use Version 3 or later of the Appliance.

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

=== Even older archive ===

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:Migrated to GitHub

2020-06-13T01:21:57Z

Graybeal: created this category page

These pages have been migrated to the GitHub documentation repository for the OntoPortal Virtual Appliance.

Advanced Administration

2020-06-13T01:21:20Z

Graybeal: tagged as Migrated

[[Category:NCBO Virtual Appliance]]
[[Category:Migrated to GitHub]]

This content has been moved! Please visit it at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

You can find Advanced content in each of the sections [https://ontoportal.github.io/administration/steps/ Installing OntoPortal], [https://ontoportal.github.io/administration/ontologies/ Managing Ontologies in OntoPortal], and [https://ontoportal.github.io/administration/management/ Managing Your System].

Category:To Be Migrated

2020-06-13T01:20:13Z

Graybeal: created this category page

The pages in this category are to be migrated to the GitHub pages content for the OntoPortal Appliance.

Modifying BioPortal Web UI

2020-06-13T01:19:03Z

Graybeal: added To Be Migrated category

[[Category:NCBO Virtual Appliance]]
[[Category:To Be Migrated]]

The BioPortal Web UI is primarily built using Ruby on Rails, which is an MVC framework built for the web. There are a variety of template types that are compatible with Rails, we use both ERB and HAML (and are trying to switch as we can to just HAML).

== Getting the Code ==

Code is available on GitHub: https://github.com/ncbo/bioportal_web_ui

== Translations ==

The BioPortal Web UI uses international localizations to handle much of the text that is seen, which means that you can change the text on many parts of your BioPortal install without actually modifying the template code. And since it's all in one file and that file isn't under version control, upgrading between versions should be a snap. In addition, this will allow us to support locale-based translations. While we don't have any translation yet -- and we don't have plans to create any -- we would gladly take contributions from the community.

There may be some areas of the site that haven't been split out into the translation file yet. If you have specific requests we can look at adding some more. This is another area where we would gladly take some community contribution.

=== Adding and Changing Text ===

The crux of the translation functionality can be found in a new folder: /config/locales

In here you will find a file, en.rb.sample, that contains sample code that you can use as a base. It's Ruby code so you can have access to variables that are assigned in the bioportal_config.rb file. To get started, do the following:

# Rename the en.rb.sample file to en.rb
# Modify the text in the file as you like
# In the Rails ERB templates, we do translation lookups like this:
# <%= t('home.intro') %>
# Each dot reflects a nested element in the Ruby hash
# To support things like the site and organization names, we've added some new options in the bioportal_config.rb file. If you're doing a new installation, use the provided bioportal_config.rb.sample file. Otherwise, see below.
# Once you start the BioPortal Rails app (using Mongrel, Passenger, or your favorite app server), the translation file will be read in and used in the template files.
# For more on Rails internationalization, see the [http://guides.rubyonrails.org/i18n.html i18n Guide]

== Tutorials ==

=== Adding a new section to BioPortal ===

We'll walk through a quick tutorial that will enable you to add your own sections of content on top of the existing Web UI. For our example, we'll add a section that will list tools that can be used to work with the ontologies in BioPortal. The Tools section will be a simple list that includes a tool's name, a web address, and a description. This list will be stored in a database and entries can be added, edited, and deleted.

For more guides on working with Rails, see http://guides.rubyonrails.org/v2.3.10.

This tutorial assumes that you have version .4 or higher of the [http://www.bioontology.org/wiki/index.php/Category:NCBO_Virtual_Appliance NCBO Virtual Appliance] running in your virtualization environment.

# Log into Virtual Appliance with the root user
# Run cd /srv/ncbo/rails/BioPortal/current
# Run script/generate scaffold Tool name:string website:string description:string
# For more information on scaffolding, see the [http://guides.rubyonrails.org/v2.3.10/getting_started.html#getting-up-and-running-quickly-with-scaffolding Ruby on Rails Guides]
# You will see some output that indicates that Rails is creating files for you. Rails scaffolding will create a default set of views templates, a controller, and a model. It will also create a migration for the corresponding database table. Our example will have three columns, 'name', 'website', and 'content', all of which have string values.
# To actually create the database table, you'll have to run the migration using rake db:migrate RAILS_ENV=production
# Now that we have setup our new content area, we can restart the server to get the changes to show up. To do that, run ncborestart
# Visiting http://yourappliance/tools will show an empty default page with options to create a new tool. However, it doesn't look like BioPortal and it's missing all of the links to other parts of the site. We'll need to change the layout that the section is using.
# If we open the newly-created 'tools_controller.rb' file under app/controllers we can change the layout used by adding layout "ontology" directly under the 'class ToolsController < ApplicationController' line. If you refresh the page you can see it now shows the usual BioPortal layout. You can also read [http://guides.rubyonrails.org/v2.3.10/getting_started.html#customizing-the-layout more about Rails layouts].
# Note: You may need to run ncborestart again for these changes to take effect. To avoid this, you can run Passenger in the [http://modrails.com/documentation/Users guide Apache.html#rails_env development environment], which will reload all controllers and templates on each request.
# The Tools section is fully functional at this point, you can add and remove tools using the generated code. The final piece is adding a link at the top of the page for your new section.
# You can add the code for the new navigation button in the 'app/views/layouts/_topnav.html.erb' file after the main project logo (line 5) as follows:
#* <code><%=top_tab("Tools", "/tools", "tools")%></code>
#* This code is calling the <code>top_tab</code> method. The first argument is the name to use for the button. The second is the URL. The third is the corresponding controller (or controllers). The controller names are used to indicate when the link should appear 'active'.
# Refreshing the page should show your changes, including the link in the top navigation

Importing UMLS To Virtual Appliance

2020-06-13T01:16:43Z

Graybeal: forwarded to new content

[[Category:NCBO Virtual Appliance]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular '''this content''' is mostly at the '''[https://ontoportal.github.io/administration/ontologies/handling_umls/ Submitting UMLS Content page]'''.

Category:NCBO Virtual Appliance

2020-06-13T01:13:11Z

Graybeal: /* OntoPortal Virtual Appliance v2.5 archive is available */

[[Category:NCBO Virtual Appliance]]

'''''Most of this content has been moved!''''' Please find the new content for the 3.0 version of the Virtual Appliance at our new '''[https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages]'''.

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== Virtual Appliance Administration Documentation: Moved to GitHub ==

Our Administration documentation for the OntoPortal Virtual Appliance has been moved to the GitHub pages document at https://ontoportal.github.io/administration/.

== Archival ==

=== OntoPortal Virtual Appliance v2.5 archive is available ===

For previous registered users of the v2.5 OntoPortal Virtual Appliance, we maintain an archival copy of this software on our site. While we do not actively support this version because its libraries are outdated, we still make it available to those users who were previously authorized to use it. All new users of the Virtual Appliance should use Version 3 or later of the Appliance.

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

=== Even older archive ===

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-13T01:12:46Z

Graybeal: inserted forwarding info

[[Category:NCBO Virtual Appliance]]

'''''Most of this content has been moved!''''' Please find the new content for the 3.0 version of the Virtual Appliance at our new '''[https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages]'''.

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== Virtual Appliance Administration Documentation: Moved to GitHub ==

Our Administration documentation for the OntoPortal Virtual Appliance has been moved to the GitHub pages document at https://ontoportal.github.io/administration/.

== Archival ==

=== OntoPortal Virtual Appliance v2.5 archive is available ===

For previous registered users of the v2.5 OntoPortal Virtual Appliance, we maintain an archival copy of this software on our site. While we do not actively support this version because its libraries are outdated, we still make it available to those users who were previously authorized to use it. All new users of the Virtual Appliance should use Version 3 or later of the Appliance.

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

=== Even older archive

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Google Analytics

2020-06-13T01:10:10Z

Graybeal: formatted

[[Category:NCBO Virtual Appliance]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular '''this content''' is mostly at the '''[https://ontoportal.github.io/administration/management/google_analytics_management/ Google Analytics Management page]'''.

Google Analytics

2020-06-13T01:09:27Z

Graybeal: forwarded to new content

[[Category:NCBO Virtual Appliance]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular this content is mostly at the [https://ontoportal.github.io/administration/management/google_analytics_management/ Google Analytics Management page].

Annotator Documentation

2020-06-13T01:07:12Z

Graybeal: pointed to new content

[[Category:NCBO Virtual Appliance]]

This content has been moved! Please find the new content for the 3.0 version of the Virtual Appliance at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

In particular this content is mostly at the [https://ontoportal.github.io/administration/management/annotator_management/ Annotator Management page].

Advanced Administration

2020-06-13T01:03:04Z

Graybeal: forwarded to new content

[[Category:NCBO Virtual Appliance]]

This content has been moved! Please visit it at our new [https://ontoportal.github.io/administration/ OntoPortal Virtual Appliance Administration pages].

You can find Advanced content in each of the sections [https://ontoportal.github.io/administration/steps/ Installing OntoPortal], [https://ontoportal.github.io/administration/ontologies/ Managing Ontologies in OntoPortal], and [https://ontoportal.github.io/administration/management/ Managing Your System].

Category:NCBO Virtual Appliance

2020-06-13T00:49:49Z

Graybeal: forwarded to the new documents

Category:NCBO Virtual Appliance

2020-06-12T20:54:02Z

Graybeal: /* Amazon AWS AMI */ updated for 3.0

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== OntoPortal Virtual Appliance v2.5 archive is available ==

For previous registered users of the v2.5 OntoPortal Virtual Appliance, we maintain an archival copy of this software on our site. While we do not actively support this version because its libraries are outdated, we still make it available to those users who were previously authorized to use it. All new users of the Virtual Appliance should use Version 3.0

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, you can obtain a copy as an Amazon Machine Instance (AMI). Instructions for accessing and starting up this software are at https://ontoportal.github.io/administration/steps/getting_started/.

Previous versions of the Virtual Appliance are no longer made available as AWS machine instances. All users are requested to use the 3.0 release of the Virtual Appliance.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-12T20:50:15Z

Graybeal: /* OntoPortal Virtual Appliance v2.5 is available */ made clear it is an archive, not the most recent

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== OntoPortal Virtual Appliance v2.5 archive is available ==

For previous registered users of the v2.5 OntoPortal Virtual Appliance, we maintain an archival copy of this software on our site. While we do not actively support this version because its libraries are outdated, we still make it available to those users who were previously authorized to use it. All new users of the Virtual Appliance should use Version 3.0

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-12T18:42:06Z

Graybeal: /* OntoPortal Virtual Appliance is here! */ with version

== OntoPortal Virtual Appliance Version 3.0 is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0 (3.0.1, to be precise).

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-12T18:35:38Z

Graybeal: /* OntoPortal Virtual Appliance is here! */ harder than it looks

== OntoPortal Virtual Appliance is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0.

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/ General Introduction], [https://ontoportal.github.io/administration/general/licensing/ Licensing], and [https://ontoportal.github.io/administration/steps/ Installation] sections.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-12T18:34:41Z

Graybeal: /* OntoPortal Virtual Appliance is here! */ fixing links

== OntoPortal Virtual Appliance is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0.

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [https://ontoportal.github.io/administration/steps/getting_started/ Getting Started] page.
You may also want to visit our [https://ontoportal.github.io/administration/ OntoPortal Administration Guide],
including the [https://ontoportal.github.io/administration/general/) General Introduction], [Licensing https://ontoportal.github.io/administration/general/licensing/], and [Installation](https://ontoportal.github.io/administration/steps/) sections.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-06-12T18:32:47Z

Graybeal: updated for latest install

== OntoPortal Virtual Appliance is here! ==

We are pleased to softly announce our soft release of the OntoPortal Virtual Appliance version 3.0.

This release includes lots of new capabilities, one of which involves licensing. The good news is that you can download and get started with your Virtual Appliance right away—no need to wait for us to give you access to the right page.

In order to do this, we had to implement licensing for BioPortal. Most users will find it trivial to obtain a free license, but for commercial users we are evaluating whether license fees could make BioPortal more sustainable.

To learn more about the new OntoPortal Virtual Appliance release, visit our [Getting Started](https://ontoportal.github.io/administration/steps/getting_started/) page.
You may also want to visit our [OntoPortal Administration Guide](https://ontoportal.github.io/administration/),
including the [General Introduction](https://ontoportal.github.io/administration/general/), [Licensing](https://ontoportal.github.io/administration/general/licensing/), and [Installation](https://ontoportal.github.io/administration/steps/) sections.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-04-09T21:40:45Z

Graybeal: /* OntoPortal Virtual Appliance version 3.0 coming very soon */ updated to add a very

== OntoPortal Virtual Appliance version 3.0 coming very, very soon ==

After briefly putting out a Release Candidate 1 for the v3.0 Virtual Appliance, we identified a few more features that we want to complete before making the Appliance available.

The release of the Virtual Appliance 3.0 is going to happen within weeks. Our licensing scheme is just about in place, and we hope to include another cool feature too. Watch this space for news.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-03-21T23:27:07Z

Graybeal: /* OntoPortal Virtual Appliance version 3.0 coming soon */

== OntoPortal Virtual Appliance version 3.0 coming very soon ==

After briefly putting out a Release Candidate 1 for the v3.0 Virtual Appliance, we have identified a few more features that we want to complete before making the Appliance available.

We intend to release a Virtual Appliance 3.0 later this winter; we have been implementing a licensing scheme as time allows, steady progress is being made. Watch this space for news.

Update: It is now the first day of spring, and we are very close to completing the 3.0 release, but it looks like just a few more weeks. Our apologies for the delay, we are all hands on deck to complete the release process. Please come back soon!

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2020-01-07T20:57:16Z

Graybeal: /* OntoPortal Virtual Appliance version 3.0 coming soon */

== OntoPortal Virtual Appliance version 3.0 coming soon ==

After briefly putting out a Release Candidate 1 for the v3.0 Virtual Appliance, we have identified a few more features that we want to complete before making the Appliance available.

We intend to release a Virtual Appliance 3.0 later this winter; we have been implementing a licensing scheme as time allows, steady progress is being made. Watch this space for news.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

OntoPortalVA

2019-10-18T05:10:15Z

Graybeal: needed an even shorter link

#REDIRECT [[Category:NCBO Virtual Appliance]]

OntoPortal Virtual Appliance

2019-10-18T04:46:52Z

Graybeal: created this as a redirect page to make a simpler URL

#REDIRECT [[Category:NCBO Virtual Appliance]]

Category:NCBO Virtual Appliance

2019-10-18T04:42:13Z

Graybeal: added a Version 3.0 section

== OntoPortal Virtual Appliance version 3.0 coming soon ==

After briefly putting out a Release Candidate 1 for the v3.0 Virtual Appliance, we have identified a few more features that we want to complete before making the Appliance available.

We intend to release a Virtual Appliance 3.0 later this fall; watch this space for news.

== OntoPortal Virtual Appliance v2.5 is available ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2019-10-18T03:48:13Z

Graybeal: reverted to pre-3.0 system description

== ONTOPORTAL VIRTUAL APPLIANCE v2.5 IS NOW AVAILABLE ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.5:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2019-10-18T03:42:55Z

Graybeal: deleted section /* ONTOPORTAL VIRTUAL APPLIANCE v3.0 RC1 IS NOW AVAILABLE */ ; it is not true

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v3.0 RC1:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator, Annotator+ and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services
* Annotator Plus Proxy

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: <code>Ontoportal</code>
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 7.6 64-bit running:
*Tomcat 7.0.x
*Solr 6.6
*Java 8
*MariaDB 5.5.x
*Rails 4.2.x
*Ruby 2.5.5
*memcached
*redis 3.2.12
*nginx 1.15.8
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>sudo oprestart</code>: manually restart services required for Ontoportal Stack.
** <code>sudo opstart</code>: manually start services.
** <code>sudo opstop</code>: manually stop services
* Start individual services:
** <code>sudo systemctl start httpd</code>
** <code>sudo systemctl start memcached</code>
** <code>sudo systemctl start tomcat</code>
** <code>sudo systemctl start mgrep</code>
** <code>sudo systemctl start 4s-httpd</code>
** <code>sudo systemctl start start</code>
* Stop individual services:
** <code>sudo systemctl stop httpd</code>
** <code>sudo systemctl stop memcached</code>
** <code>sudo systemctl stop tomcat</code>
** <code>sudo systemctl stop mgrep</code>
** <code>sudo systemctl stop 4s-httpd</code>
** <code>sudo systemctl stop unicorn</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Older Versions Documentation ==

For documentation of previous
(v2.5) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12987 archive].
(v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2019-06-30T21:33:47Z

Graybeal: /* Virtual Appliance Basics */

Category:NCBO Virtual Appliance

2019-06-30T21:33:21Z

Graybeal: /* ONTOPORTAL VIRTUAL APPLIANCE v2.5 IS NOW AVAILABLE */ deleted reference to v4.x

== ONTOPORTAL VIRTUAL APPLIANCE v2.5 IS NOW AVAILABLE ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v5.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.4:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Virtual Appliance FAQ

2019-06-04T23:06:40Z

Graybeal: removed predictions about UIs coming soon

[[Category:NCBO Virtual Appliance]]

= ONTOPORTAL VIRTUAL APPLIANCE v2.5 FAQ =
This FAQ now covers the Ontoportal Virtual Appliance v2.5 The FAQ for v1.0 is available in the [http://www.bioontology.org/wiki/index.php?title=Virtual_Appliance_FAQ&oldid=12621 archive]

= General =
== How do I access Virtual Appliance? ==

Virtual Appliance Web UI can be accessed by going to http://{your_appliance_ip_or_domain_name} on your web browser. 
API can be accessed at http://{your_appliance_ip_or_domain_name}:8080

You can get IP address of the Appliance with the following methods:
* Local IP Address from terminal:
<code>ip address show eth0 | awk '/inet / {print $2}' | cut -d/ -f1'</code>
* External IP address from the terminal:
<code>curl http://ipecho.net/plain; echo</code>
* Vmware Appliance:
Check 'IP Addresses' on the summary page of the appliance. Please note that Virtual Appliance does not come with vmware tools installed so IP Address would not be displayed until vmware tools are installed.
* Amazon AWS:
use Public IP Addresses or Public DNS listed in your EC2 management console.

== How can I enable emails for lost passwords, notes, and ontology processing? ==

Emails are sent via the ontologies_api project on the Appliance. You need to provide a valid mail server (smtp) configuration. The configuration should be provided in the /srv/ncbo/ontologies_api/current/config/environments/production.rb file.

Here are the available settings:
<code>
config.enable_notifications = true # Set to 'true' to send emails
config.email_sender = "admin@example.org" # Default sender for emails
config.email_disable_override = true # If this is set to 'false', all emails will be sent to the email configured in the 'email_override' setting
config.email_override = "admin@example.org"
config.smtp_host = "smtp.example.org"
config.smtp_port = 25
config.smtp_auth_type = :none # :none, :plain, :login, :cram_md5
config.smtp_user = "username" # only used if auth_type is not :none
config.smtp_password = "password" # only used if auth_type is not :none
config.smtp_domain = "example.org"
</code>

Once you have changed your settings, you will need to restart the server by running the command <code>/sbin/service unicorn restart</code>

== Can I use the Annotator and Recommender on their own? ==

Because services like the Annotator and Recommender depend on the Ontologies API in BioPortal, you can not usefully install those services in a stand-alone way without also installing the core BioPortal software and ontologies.

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface. Categories and groups can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
category = LinkedData::Models::Category.new
category.name = "My Category"
category.acronym = "MY_CAT"
category.save
group = LinkedData::Models::Group.new
group.name = "My Group"
group.acronym = "MY_GRP"
group.save
</pre>

== How do I add or change slices? ==
There is currently no UI administrator interface. Slices can be added using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ont1 = LinkedData::Models::Ontology.find("ONT1").first
ont2 = LinkedData::Models::Ontology.find("ONT2").first
slice = LinkedData::Models::Slice.new
slice.name = "My Slice",
slice.description = "This is my custom slice",
slice.acronym = "my_slice",
slice.ontologies = [ont1, ont2]
slice.save
</pre>

== How do I delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the ontoportal user.
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ONTOLOGY_ACRONYM").first
ontology.delete
</pre>

== How can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==

Programmatic migrations are not officially supported ("Ontologies can be manually downloaded and added using the Web UI") but we included a script for importing ontologies.

/srv/ncbo/virtual_appliance/deployment/utils/bioportal_ontologies_import.rb, you will need to modify SOURCE_API, SOURCE_APIKEY and ONTOLOGIES_TO_IMPORT variables.

== How can I restrict ontology downloads via the UI? ==

This line of code should be modified to include the acronyms of the ontologies for which you want to restrict downloads via the UI:

https://github.com/ncbo/bioportal_web_ui/blob/master/app/views/ontologies/_submissions.html.haml#L32

This will prevent the “Downloads” column in the Submissions table from appearing on ontology summary pages.

If you want to restrict download via the REST endpoint, you need to modify your environment configuration files (e.g., production.rb, staging.rb, etc.) in your ontologies_api project. The production.rb file should contain a “config.restrict_download” property -- there’s an example of what it should look like in the sample configuration file in GitHub:

https://github.com/ncbo/ontologies_api/blob/master/config/environments/config.rb.sample#L38

= Ontology Parsing =
== When are new ontologies parsed? ==
The ncbo_cron project uses a scheduler to run a process that collects new ontology submissions and parses them, adds them to the search index, calculates metrics, and processes them for use with the annotator. You can also parse ontologies manually.

== How do I manually parse an ontology? ==
To manually parse an ontology, you will need to interact with the code using the console after switching to ontoportal user:
<pre>
# from the bash shell:
cd /srv/ncbo/ncbo_cron
bin/ncbo_cron --console
# once in the ruby console:
ontology = LinkedData::Models::Ontology.find("MY_ACRONYM").first
submission = ontology.latest_submission(status: :any)
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_term_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== How can I process a UMLS ontology? ==

UMLS ontologies can be processed to work with our system by converting them to RDF. There is no automated way to do this and you must have your own UMLS MySQL installation and an OSX/Linux/Unix machine with 8GB+ of RAM in order for the conversion process to work. The scripts to convert UMLS to RDF are available on [https://github.com/ncbo/umls2rdf Github].

Once you have converted UMLS to RDF, you will get Turtle (.ttl) files that can be uploaded using the BioPortal Web UI. Please select UMLS as the format for these ontologies.

== How do I know if an ontology has parsed? ==
The BioPortal Web UI will cache information about ontologies for 60 seconds. After parsing is complete, just refresh the ontology summary page to see the status for the most recent submission listed under the "Submissions" table.

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://{your_appliance_ip_or_domain_name}:8080/ontologies/{ontology_acronym}/latest_submission?include=all
* You can look for the submissionStatus attribute to get the status

== Is there a log file for parsing? ==
Parsing progress is logged in the ontology submission repository folder:
/srv/ncbo/repository/{ontology acronym}/{submission id}

= Web User Interface =
== How can I clear the memcached-based UI cache? ==
* If you are logged in as the admin user, simply visit http://{your_appliance_ip_or_domain_name}/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? ==
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.

= Virtualization Environments =

== 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:

<pre>
ovftool ncbo-appliance.ovf ncbo-appliance.vmx
</pre>

=== 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 ===
First, convert the OVF to VMX format as mentioned in the VMware section above.

Next, ensure that the <code>kvm-qemu-img</code> RPM (or <code>qemu-kvm</code> DEB) is installed. Then, convert the [new] VMDKs (from the VMX conversion step) to raw disk images via the following command:

<pre>for disk in `ls -1 *.vmdk`; do diskbase=`basename $disk .vmdk`; qemu-img convert -O raw ${diskbase}.vmdk ${diskbase}.img; done</pre>

Create <code>/etc/libvirt/qemu/ncbo-appliance.xml</code> with the following contents:

<pre>
<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/ncbo-appliance-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/ncbo-appliance-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>
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
virsh start ncbo-appliance
</pre>

=== Xen ===
First, convert the VMDKs to raw disk images as mentioned in the KVM section above.

Create <code>/etc/xen/ncbo-appliance.cfg</code> with the following contents:

<pre>
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/ncbo-appliance-disk1.img,hda,w", "file:/var/lib/xen/images/ncbo-appliance/ncbo-appliance-disk2.img,hdb,w" ]
vif = [ "bridge=xenbr0,script=vif-bridge,vifname=vif41.0" ]
parallel = "none"
serial = "pty"
</pre>

Finally, make any necessary edits to the above file, and run:

<pre>
xm create ncbo-appliance
</pre>

== How can I use the Appliance on Amazon EC2? ==

Appliance is available on [https://aws.amazon.com/marketplace/pp/B00MX5YKVU Amazon Marketplace]

=== What is the admin password for the AWS Appliance? ===

The default application administrator is 'admin' and the initial password is the Instance ID (i-xxxxxxxx). Please change this as soon as you install the virtual appliance.

Category:NCBO Virtual Appliance

2019-06-04T22:57:23Z

Graybeal: another OntoPortal, deleted "much has changed" line

== ONTOPORTAL VIRTUAL APPLIANCE v2.5 IS NOW AVAILABLE ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on BioPortal's v4.x (now v5.x) software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.4:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

Category:NCBO Virtual Appliance

2019-06-04T22:56:10Z

Graybeal: made more OntoPortal, removed v1.0 reference to bottom

== ONTOPORTAL VIRTUAL APPLIANCE v2.5 IS NOW AVAILABLE ==

The OntoPortal Virtual Appliance is the (rebranded) update of the BioPortal Virtual Appliance originally developed by the National Center for Biomedical Ontologies (NCBO). Our current Virtual Appliance software is based on NCBO's v4.x software infrastructure, including the use of an RDF triplestore as the primary data storage mechanism. Please read below as much of the Appliance workflow has changed.

== Virtual Appliance Basics ==

The OntoPortal Virtual Appliance is a copy of the BioPortal software that you can run on your own Linux system. You have to install it following the instructions below, and upload your own ontologies (and/or copies of ours, if they are public).

The OntoPortal Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source software running on a Linux operating system.

It is available as a VMWare Virtual Appliance OVF, as well as an Amazon Web Service AMI, and can be obtained by contacting us following the instructions under '''Getting Started''' below.

The following software is included on the image as of v2.4:
* Ontologies API (REST service)
* Annotator
* Recommender
* OntoPortal Web User Interface (including UIs for ontology browse, Annotator and Recommender, ontology tree visualization, graph visualization with BioMixer, and widgets)
* API services

Please see below for how-to documentation for managing the software and running data population for Annotator and Recommender.

You may also want to visit the [[Virtual Appliance FAQ]] for additional information on the Virtual Appliance, as well as the other pages in this category (bottom of the page).

== Getting Started ==
=== VMWare Virtual Appliance ===

To obtain the VMWare Virtual Appliance, contact [mailto:support@bioontology.org OntoPortal Support] to initiate your request. You'll then be asked privately for your BioPortal account username, project goals, and reason for preferring the local installation.
* If you don't have a BioPortal account, you can create one at: http://bit.ly/bioportal-account.
* If your email doesn't include your organization or other means of identifying you, we will ask for that as well.
* The overall transaction can take a few working days, depending on resource availability.

The download is provided as a zip archive containing several files. One of these is an Open Virtualization Format (OVF) file that may need to be [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#How_can_I_use_the_OVF_image_with_my_virtualization_software.3F_.28VMWare.2C_VirtualBox.2C_KVM.2C_Xen.2C_etc.29 converted to work in your virtualization environment].

* You can supply the hostname (machine name) for the virtual machine during the deployment process. Documentation will refer to this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** OntoPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>

=== Amazon AWS AMI ===
For users who want to run their OntoPortal instance on Amazon Web Services, an Amazon Machine Instance (AMI) is available on the [https://aws.amazon.com/marketplace/seller-profile/ref=dtl_pcp_sold_by?ie=UTF8&id=76948a46-8f8a-4a68-9a5c-3e3ff6b82d10 BioOntology AWS Market Place]. Please contact [mailto:support@bioontology.org OntoPortal Support] for more information.

Once the instance is running, enter the public DNS provided by Amazon into your browser to access BioPortal web interface. The default application administrator is 'admin' and the initial password is the Instance ID. You can also SSH to the machine using the username 'ec2-user' and your Amazon private key.

=== General Instruction ===
Virtual Appliance Web UI can be accessed at http://{ip_address_of_appliance}. You can get IP address of the Appliance by using the following command in the terminal 'ip addr show eth0'
* Add an ontology using the OntoPortal Admin User here: http://{ip_address_of_appliance}/ontologies/new
** The ncbo_cron project is configured to automatically process new ontologies every 5 minutes (see [http://www.bioontology.org/wiki/index.php/Virtual_Appliance_FAQ#When_are_new_ontologies_parsed.3F documentation for enabling the scheduler]). This processing includes:
*** Parsing any new, unparsed ontologies
*** Calculating a set of metrics for these ontologies
*** Indexing these ontologies for use with search
*** Processing the ontology for use with the annotator
* REST services are available at the following location:
** http://{ip_address_of_appliance}:8080
** http://{ip_address_of_appliance}:8080/documentation

== System Requirements ==
The following requirements are for the resources that you devote to your Appliance instance, not for the machine running your host environment. For example, if you are using a system with 4GB of RAM, then you will need to devote all of that RAM to your guest Appliance.

'''Note: these requirements are for basic usage'''. System requirements will vary greatly depending on the size of the ontologies you work with, the number of ontologies in the system, and the number of concurrent requests that the system needs to respond to. It can also vary depending on how the ontologies are used. For example, the search index can be RAM-intensive but parsing ontologies can be CPU-intensive. You will need to experiment with your Appliance resource settings to find what works for your scenario.

* Minimum
** 2 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 20GB

* Recommended for heavier usage
** 4 CPU (3 GHz)
** 8GB RAM (or more depending on the size/number of ontologies)
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The OntoPortal Virtual Appliance image was created using the [http://www.vmware.com/appliances/getting-started/learn/ovf.html Open Virtualization Format], which should allow the machine to be used in a variety of environments.

The operating system is CentOS 6.9 64-bit running:
*Tomcat 6.0.26
*Solr 6.6
*Java 8
*MySQL 5.1.x
*Rails 4.2.x
*Ruby 2.3.6
*memcached
*redis 2.3.11
*nginx 1.12.1
*4store
*Passenger/Apache

The following applications use these services/runtime environments:
* Sinatra, Ruby, 4store, redis
** Ontologies API
** Annotator
** Recommender
* Rails, Ruby, memcached, mysql
** BioPortal Web User Interface (including ontology visualization, Flex widgets, biomixer, Annotator)
* Tomcat, Solr
** Search index

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* We assume familiarity with basic CentOS Linux administration
* 2 text editors are originally installed: nano and vim
* All services required for OntoPortal Stack are automatically started on boot. For troubleshooting purposes you can manually stop/start services:
** <code>bprestart</code>: manually restart services required for Ontoportal Stack.
** <code>bpstart</code>: manually start services.
** <code>bpstop</code>: manually stop services
* Start individual services:
** <code>/sbin/service httpd start</code>
** <code>/sbin/service memcached start</code>
** <code>/sbin/service tomcat6 start</code>
** <code>/sbin/service mgrep start</code>
** <code>/sbin/service 4s-httpd-ontologies_api start</code>
** <code>/sbin/service unicorn start</code>
* Stop individual services:
** <code>/sbin/service httpd stop</code>
** <code>/sbin/service memcached stop</code>
** <code>/sbin/service tomcat6 stop</code>
** <code>/sbin/service mgrep stop</code>
** <code>/sbin/service 4s-httpd-ontologies_api stop</code>
** <code>/sbin/service unicorn stop</code>

== License ==

The Virtual Appliance software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

== Archival ==

For documentation of previous (v1.0) Virtual Appliances, please see our [http://www.bioontology.org/wiki/index.php?title=Category:NCBO_Virtual_Appliance&oldid=12610 archive].

BioPortal FAQ

2019-02-27T02:15:54Z

Graybeal: fixed metadata section

'''Frequently Asked Questions (FAQ)'''

=General=

==What is an ontology?==
An ontology is a formal representation of a set of concepts/nodes within a domain and the relationships between those concepts. It is used to reason about the properties of that domain, and may be used to define the domain.

==Where are the ontologies?==

Ontologies are available from BioPortal at http://bioportal.bioontology.org.

===How do I submit an ontology?===

The current protocol is:

1) Go to BioPortal at http://bioportal.bioontology.org

2) If you haven't already, click on the "Register" link in the top right hand corner.

3) After you have registered as a user, "Sign In" as that user.

4) Click on the "Browse" tab (or click on the following link: http://bioportal.bioontology.org/browse)

5) Click on the "Submit Ontology" button and follow the instructions.

===How do I cite BioPortal?===
Noy NF, Shah NH, Whetzel PL, Dai B, Dorf M, Griffith N, Jonquet C, Rubin DL,
Storey MA, Chute CG, Musen MA. BioPortal: ontologies and integrated data
resources at the click of a mouse. Nucleic Acids Res. 2009 Jul 1;37(Web Server
issue):W170-3. Epub 2009 May 29. PubMed PMID: 19483092; PubMed Central PMCID:
PMC2703982.

=Ontology Content=

==Building Ontologies==

===How do I go about building an ontology?===

There are a plethora of tools for building ontologies. Below are two preferred tools for building OWL and OBO ontologies:

1) Protege (http://protege.stanford.edu/) - OWL ontologies

2) OBOEdit (http://oboedit.org/) - OBO ontologies

===What is the OBO Foundry?===

A collaborative project, involving a group of OBO ontology developers who have agreed in advance to the adoption of a set of principles specifying best practices in ontology development. These principles are designed to foster interoperability of ontologies within the broader OBO framework, and also to ensure a gradual improvement of quality and formal rigor in ontologies, in ways designed to meet the increasing needs of data and information integration in the biomedical domain. See http://obofoundry.org/

=BioPortal Products=

==What is BioPortal?==
A Web-based application for searching, sharing, visualizing, and analyzing a large repository of biomedical ontologies, terminologies, and ontology-based annotations. BioPortal is available at: http://bioportal.bioontology.org/. All content of BioPortal is also accessible via RESTful web services. To learn more about how to use BioPortal technology in your software see the page [[Using_BioPortal_Technology_In_Your_Project|Using BioPortal Technology In Your Project]]

BioPortal allows for mappings between terms, bulk export of mappings, visualization of terms and relationships within ontologies, notes, and navigation of multiple ontologies through tabbed browsing. To see a demo of BioPortal, please visit http://www.bioontology.org/BioPortal.

==What is the Resource Index?==
A set of ontology-based annotations of biomedical data. These annotations have been generated automatically via the Resource Index workflow. The annotations can be accessed from BioPortal, either from from the All Resources tab to search for term annotations or from the Resource Index tab to browse annotations for an individual term. This tool enables researchers to search for biomedical resources associated (or annotated) with specific ontology terms.

==What is the Annotator?==
The Annotator is a text annotation tool that uses mgrep, developed by the University of Michigan, as the entity recognizer and the entire library of BioPortal ontologies as the dictionary of terms. This tool can be accessed from BioPortal and also via programmatic access directly to the Web service.

==I have a lot of data to analyze. How can I use the API to access BioPortal products efficiently?==
This [https://www.bioontology.org/wiki/Annotator_Optimizing_and_Troublehooting Annotator Optimizing and Troubleshooting page] has many tips that apply to many API requests, not just the NCBO Annotator.

=Details=

==Ontology Metadata==
Ontology metadata represented in BioPortal uses the Ontology Metadata Vocabulary (OMV) format to store all ontology meta data. Please see the following web site for more information on the format (http://omv.ontoware.org/).

To read more about how OMV is used in BioPortal see [[BioPortal_Metadata|BioPortal Metadata Requirements]].

An earlier version of BioPortal's metadata ontology is at [http://bioportal.bioontology.org/virtual/1148].

==OBO Format==

Questions about the OBO ontology format

===What is OBO Format?===

A format often used in the OBO Foundry to define ontologies. OWL is now being recommended by the OBO Foundry community for creating ontologies because of the greater tooling available, but some ontologies are still maintained in OBO format.

===Can I convert Obo-format to OWL?===

Yes. There are multiple ways to convert ontologies between OWL and OBO format.

* Using [https://protege.stanford.edu Protege] (uses the owl-api which is able to open both OWL and OBO format ontologies)

* Using BioPortal to load the OBO file (imports using the owl-api; current ontology then available as RDF)

* Using the owl-api directly

===Can I convert Obo-format files to Protege-classic?===

Not yet. In theory it should not be hard to provide an XSL for this. The reverse transformation may be more difficult.

=Historical and Deprecated FAQs=

==NCBO==

===What is NCBO?===

The National Center for Biomedical Ontology (http://www.bioontology.org) is a consortium of leading biologists, clinicians, informaticians, and ontologists who develop innovative technology and methods that allow scientists to create, disseminate, and manage biomedical information and knowledge in machine-processable form. Our vision is that all biomedical knowledge and data are disseminated on the Internet using ontologies, such that the knowledge and data are semantically interoperable and useful for furthering biomedical science and clinical care. The Center’s software and technologies include [http://bioportal.bioontology.org BioPortal], Phenote+, the [[Resource_Index|NCBO Resource Index]], and the [[Annotator_Web_service|NCBO Annotator]]. Partner technologies include LexGrid, Protege, and Jambalaya. The Center collaborates with biomedical researchers conducting Driving Biological Projects (DBPs) to enable their research and to stimulate technology development in the Center. The Center is undertaking outreach and educational activities to train the future generation of researchers in using biomedical ontologies and the Center’s sfotware to enhance scientific discovery.

==What is Phenote?==
A Java client application for manual creation and storage of biomedical annotations (starting with phenotype annotations) using terms from multiple ontologies.

==What is Open Biomedical Data?==
A database of manually generated biomedical annotations (starting with phenotype annotations) summarizing key attributes such as anatomy, phenotype, and genetic features. The annotations are currently loaded directly from a Phenote file, which contains the manually created annotations.

==incomplete is-a paths==

Many OBO ontologies are currently incomplete with respect to all classes/terms having an is-a parent. Many tools (including OBO-Edit and AmiGO) deliberately allow the conflation of relations when presenting the ontology as a DAG or a tree to the user. However, other tools (including Protege and SWOOP) do not. This means that some OBO ontologies can look unusual when viewed with these other tools (lots of classes appear at the root level).

This is currently being addressed by the maintainers of OBO ontologies. An effort is underway to complete the is-a parentage in the GO cellular component ontology (biological process will be more difficult). The Plant Ontology Consortium are completing the is-a parentage in the plant anatomical structure ontology.

Until this work is complete, some OBO ontologies may look unusual when viewed in conventional ontology browsing and editing tools. With some of these tools, there may be some configurations which allow other relations to be conflated with the is-a relation when presenting the ontology as a DAG or tree view.

One option is to automatically create an is-a parent to the ontology root for every non-root class/term which lacks any is-a parents. Note that this may create inconsistencies in the ontology if the genuine is-a parent is somewhere deeper in the ontology hierarchy; nevertheless this step may be necessary before presenting some OBO ontologies to tools such as reasoners.

===Is OBO Format different from the old GO format?===

Yes. The old dag-edit format (i.e. the one in which indentation was used to denote the GO hierarchy) is STRONGLY deprecated.

===Where can I find the spec?===

You can find details on the 1.0 spec on the GO home page
http://www.geneontology.org/GO.format.shtml#oboflat

This spec is somewhat underspecified

The 1.2 spec is in preparation, and will be released to coincide with the first production OBO-Edit release sometime early in 2006

You can find a preliminary version of the spec here:
HTML -- http://www.godatabase.org/dev/doc/obo_format_spec.html
PDF -- http://www.godatabase.org/dev/doc/obo_format_spec.pdf
Ascii text -- http://www.godatabase.org/dev/doc/obo_format_spec.txt

===Why not use XML?===

There is also an obo-xml format. See

http://www.godatabase.org/dev/xml

Currently only available as DTD. Relax-NG and XSD coming soon.

===Is there a UML model?===

Yes, there is a UML translation of the obo format in progress, produced by Harold Solbrig of Mayo clinic; see:

http://informatics.mayo.edu/schema/OBO/UMLModel/HTML/

===What tools support Obo-Format?===

The following are *ontology* tools that support the OBO format. There are many other tools for the analysis of gene ontology data which also happen to read the OBO format - see http://www.geneontology.org/GO.tools.shtml for a list

; OBO-Edit
: (naturally!). You should use this rather than DAG-Edit (DAG-Edit still supports obo-1.0 format), as DAG-Edit is deprecated as of 2006.

; COBRA
: developed by Stuart Aitken as part of http://www.xspan.org. COBRA is a java ontology editor/viewer for aligning ontologies

; go-perl
: http://search.cpan.org/~cmungall/go-perl

==Using Protege with OBO ontologies==

You have two options here - use the Protege OBO plugin, or convert to a format which Protege understands.

The OBO plugin was developed at the University of Washington, and is no longer supported.

You can convert any obo-format file to OWL and use Protege-OWL (but not Protege-classic); see the next entry.

Note that when you look at many of the OBO ontologies in Protege (classic or Protege-OWL) you will see that there are large amounts of classes apparently at the root level. This is because OBO ontologies have historically not been complete with respect to all classes having a superclass (is-a parent). This is currently being addressed. See the FAQ entry on this subject.

===Can I convert OBO format to OWL===

*Using the xslts included in go-perl.
**Download and install: http://search.cpan.org/~cmungall/go-perl/
**Then run the script
**go2owl myontology.obo. This functionality will soon be available from oboedit
**For more details on the mapping, see: http://www.fruitfly.org/~cjm/obol/doc/mapping-obo-to-owl.html

BioPortal FAQ

2019-02-27T02:13:00Z

Graybeal: total reorg to remove NCBO and bring up to date

'''Frequently Asked Questions (FAQ)'''

=General=

==What is an ontology?==
An ontology is a formal representation of a set of concepts/nodes within a domain and the relationships between those concepts. It is used to reason about the properties of that domain, and may be used to define the domain.

==Where are the ontologies?==

Ontologies are available from BioPortal at http://bioportal.bioontology.org.

===How do I submit an ontology?===

The current protocol is:

1) Go to BioPortal at http://bioportal.bioontology.org

2) If you haven't already, click on the "Register" link in the top right hand corner.

3) After you have registered as a user, "Sign In" as that user.

4) Click on the "Browse" tab (or click on the following link: http://bioportal.bioontology.org/browse)

5) Click on the "Submit Ontology" button and follow the instructions.

===How do I cite BioPortal?===
Noy NF, Shah NH, Whetzel PL, Dai B, Dorf M, Griffith N, Jonquet C, Rubin DL,
Storey MA, Chute CG, Musen MA. BioPortal: ontologies and integrated data
resources at the click of a mouse. Nucleic Acids Res. 2009 Jul 1;37(Web Server
issue):W170-3. Epub 2009 May 29. PubMed PMID: 19483092; PubMed Central PMCID:
PMC2703982.

=Ontology Content=

==Building Ontologies==

===How do I go about building an ontology?===

There are a plethora of tools for building ontologies. Below are two preferred tools for building OWL and OBO ontologies:

1) Protege (http://protege.stanford.edu/) - OWL ontologies

2) OBOEdit (http://oboedit.org/) - OBO ontologies

===What is the OBO Foundry?===

A collaborative project, involving a group of OBO ontology developers who have agreed in advance to the adoption of a set of principles specifying best practices in ontology development. These principles are designed to foster interoperability of ontologies within the broader OBO framework, and also to ensure a gradual improvement of quality and formal rigor in ontologies, in ways designed to meet the increasing needs of data and information integration in the biomedical domain. See http://obofoundry.org/

=BioPortal Products=

==What is BioPortal?==
A Web-based application for searching, sharing, visualizing, and analyzing a large repository of biomedical ontologies, terminologies, and ontology-based annotations. BioPortal is available at: http://bioportal.bioontology.org/. All content of BioPortal is also accessible via RESTful web services. To learn more about how to use BioPortal technology in your software see the page [[Using_BioPortal_Technology_In_Your_Project|Using BioPortal Technology In Your Project]]

BioPortal allows for mappings between terms, bulk export of mappings, visualization of terms and relationships within ontologies, notes, and navigation of multiple ontologies through tabbed browsing. To see a demo of BioPortal, please visit http://www.bioontology.org/BioPortal.

==What is the Resource Index?==
A set of ontology-based annotations of biomedical data. These annotations have been generated automatically via the Resource Index workflow. The annotations can be accessed from BioPortal, either from from the All Resources tab to search for term annotations or from the Resource Index tab to browse annotations for an individual term. This tool enables researchers to search for biomedical resources associated (or annotated) with specific ontology terms.

==What is the Annotator?==
The Annotator is a text annotation tool that uses mgrep, developed by the University of Michigan, as the entity recognizer and the entire library of BioPortal ontologies as the dictionary of terms. This tool can be accessed from BioPortal and also via programmatic access directly to the Web service.

==I have a lot of data to analyze. How can I use the API to access BioPortal products efficiently?==
This [https://www.bioontology.org/wiki/Annotator_Optimizing_and_Troublehooting Annotator Optimizing and Troubleshooting page] has many tips that apply to many API requests, not just the NCBO Annotator.

=Details=

==Ontology Metadata==
Ontology metadata represented in BioPortal uses the Ontology Metadata Vocabulary (OMV) format to store all ontology meta data. Please see the following web site for more information on the format (http://omv.ontoware.org/). To view in BioPortal, see [http://bioportal.bioontology.org/virtual/1148 BioPortal Metadata] and to read more about how OMV is used in BioPortal see [[BioPortal_Metadata|BioPortal Metadata Requirements]]

==OBO Format==

Questions about the OBO ontology format

===What is OBO Format?===

A format often used in the OBO Foundry to define ontologies. OWL is now being recommended by the OBO Foundry community for creating ontologies because of the greater tooling available, but some ontologies are still maintained in OBO format.

===Can I convert Obo-format to OWL?===

Yes. There are multiple ways to convert ontologies between OWL and OBO format.

* Using [https://protege.stanford.edu Protege] (uses the owl-api which is able to open both OWL and OBO format ontologies)

* Using BioPortal to load the OBO file (imports using the owl-api; current ontology then available as RDF)

* Using the owl-api directly

===Can I convert Obo-format files to Protege-classic?===

Not yet. In theory it should not be hard to provide an XSL for this. The reverse transformation may be more difficult.

=Historical and Deprecated FAQs=

==NCBO==

===What is NCBO?===

The National Center for Biomedical Ontology (http://www.bioontology.org) is a consortium of leading biologists, clinicians, informaticians, and ontologists who develop innovative technology and methods that allow scientists to create, disseminate, and manage biomedical information and knowledge in machine-processable form. Our vision is that all biomedical knowledge and data are disseminated on the Internet using ontologies, such that the knowledge and data are semantically interoperable and useful for furthering biomedical science and clinical care. The Center’s software and technologies include [http://bioportal.bioontology.org BioPortal], Phenote+, the [[Resource_Index|NCBO Resource Index]], and the [[Annotator_Web_service|NCBO Annotator]]. Partner technologies include LexGrid, Protege, and Jambalaya. The Center collaborates with biomedical researchers conducting Driving Biological Projects (DBPs) to enable their research and to stimulate technology development in the Center. The Center is undertaking outreach and educational activities to train the future generation of researchers in using biomedical ontologies and the Center’s sfotware to enhance scientific discovery.

==What is Phenote?==
A Java client application for manual creation and storage of biomedical annotations (starting with phenotype annotations) using terms from multiple ontologies.

==What is Open Biomedical Data?==
A database of manually generated biomedical annotations (starting with phenotype annotations) summarizing key attributes such as anatomy, phenotype, and genetic features. The annotations are currently loaded directly from a Phenote file, which contains the manually created annotations.

==incomplete is-a paths==

Many OBO ontologies are currently incomplete with respect to all classes/terms having an is-a parent. Many tools (including OBO-Edit and AmiGO) deliberately allow the conflation of relations when presenting the ontology as a DAG or a tree to the user. However, other tools (including Protege and SWOOP) do not. This means that some OBO ontologies can look unusual when viewed with these other tools (lots of classes appear at the root level).

This is currently being addressed by the maintainers of OBO ontologies. An effort is underway to complete the is-a parentage in the GO cellular component ontology (biological process will be more difficult). The Plant Ontology Consortium are completing the is-a parentage in the plant anatomical structure ontology.

Until this work is complete, some OBO ontologies may look unusual when viewed in conventional ontology browsing and editing tools. With some of these tools, there may be some configurations which allow other relations to be conflated with the is-a relation when presenting the ontology as a DAG or tree view.

One option is to automatically create an is-a parent to the ontology root for every non-root class/term which lacks any is-a parents. Note that this may create inconsistencies in the ontology if the genuine is-a parent is somewhere deeper in the ontology hierarchy; nevertheless this step may be necessary before presenting some OBO ontologies to tools such as reasoners.

===Is OBO Format different from the old GO format?===

Yes. The old dag-edit format (i.e. the one in which indentation was used to denote the GO hierarchy) is STRONGLY deprecated.

===Where can I find the spec?===

You can find details on the 1.0 spec on the GO home page
http://www.geneontology.org/GO.format.shtml#oboflat

This spec is somewhat underspecified

The 1.2 spec is in preparation, and will be released to coincide with the first production OBO-Edit release sometime early in 2006

You can find a preliminary version of the spec here:
HTML -- http://www.godatabase.org/dev/doc/obo_format_spec.html
PDF -- http://www.godatabase.org/dev/doc/obo_format_spec.pdf
Ascii text -- http://www.godatabase.org/dev/doc/obo_format_spec.txt

===Why not use XML?===

There is also an obo-xml format. See

http://www.godatabase.org/dev/xml

Currently only available as DTD. Relax-NG and XSD coming soon.

===Is there a UML model?===

Yes, there is a UML translation of the obo format in progress, produced by Harold Solbrig of Mayo clinic; see:

http://informatics.mayo.edu/schema/OBO/UMLModel/HTML/

===What tools support Obo-Format?===

The following are *ontology* tools that support the OBO format. There are many other tools for the analysis of gene ontology data which also happen to read the OBO format - see http://www.geneontology.org/GO.tools.shtml for a list

; OBO-Edit
: (naturally!). You should use this rather than DAG-Edit (DAG-Edit still supports obo-1.0 format), as DAG-Edit is deprecated as of 2006.

; COBRA
: developed by Stuart Aitken as part of http://www.xspan.org. COBRA is a java ontology editor/viewer for aligning ontologies

; go-perl
: http://search.cpan.org/~cmungall/go-perl

==Using Protege with OBO ontologies==

You have two options here - use the Protege OBO plugin, or convert to a format which Protege understands.

The OBO plugin was developed at the University of Washington, and is no longer supported.

You can convert any obo-format file to OWL and use Protege-OWL (but not Protege-classic); see the next entry.

Note that when you look at many of the OBO ontologies in Protege (classic or Protege-OWL) you will see that there are large amounts of classes apparently at the root level. This is because OBO ontologies have historically not been complete with respect to all classes having a superclass (is-a parent). This is currently being addressed. See the FAQ entry on this subject.

===Can I convert OBO format to OWL===

*Using the xslts included in go-perl.
**Download and install: http://search.cpan.org/~cmungall/go-perl/
**Then run the script
**go2owl myontology.obo. This functionality will soon be available from oboedit
**For more details on the mapping, see: http://www.fruitfly.org/~cjm/obol/doc/mapping-obo-to-owl.html

NCBO FAQ

2019-02-27T01:59:58Z

Graybeal: Graybeal moved page NCBO FAQ to BioPortal FAQ: want it to be about BioPortal now

#REDIRECT [[BioPortal FAQ]]

BioPortal FAQ

2019-02-27T01:59:57Z

Graybeal: Graybeal moved page NCBO FAQ to BioPortal FAQ: want it to be about BioPortal now

'''Frequently Asked Questions (FAQ)'''

=General=

==NCBO==

Advancing biology and medicine with tools and methodologies for the structured organization of knowledge.

===What is NCBO?===

The National Center for Biomedical Ontology (http://www.bioontology.org) is a consortium of leading biologists, clinicians, informaticians, and ontologists who develop innovative technology and methods that allow scientists to create, disseminate, and manage biomedical information and knowledge in machine-processable form. Our vision is that all biomedical knowledge and data are disseminated on the Internet using ontologies, such that the knowledge and data are semantically interoperable and useful for furthering biomedical science and clinical care. The Center’s software and technologies include [http://bioportal.bioontology.org BioPortal], Phenote+, the [[Resource_Index|NCBO Resource Index]], and the [[Annotator_Web_service|NCBO Annotator]]. Partner technologies include LexGrid, Protege, and Jambalaya. The Center collaborates with biomedical researchers conducting Driving Biological Projects (DBPs) to enable their research and to stimulate technology development in the Center. The Center is undertaking outreach and educational activities to train the future generation of researchers in using biomedical ontologies and the Center’s sfotware to enhance scientific discovery.

==What is an ontology?==
An ontology is a formal representation of a set of concepts/nodes within a domain and the relationships between those concepts. It is used to reason about the properties of that domain, and may be used to define the domain.

==Where are the ontologies?==

Ontologies are available from BioPortal at http://bioportal.bioontology.org.

===How do I submit an ontology?===

The current protocol is:

1) Go to BioPortal at http://bioportal.bioontology.org

2) If you haven't already, click on the "Register" link in the top right hand corner.

3) After you have registered as a user, "Sign In" as that user.

4) Click on the "Browse" tab (or click on the following link: http://bioportal.bioontology.org)

5) Click on the "Submit Ontology" button and follow the instructions.

===How do I cite BioPortal?===
Noy NF, Shah NH, Whetzel PL, Dai B, Dorf M, Griffith N, Jonquet C, Rubin DL,
Storey MA, Chute CG, Musen MA. BioPortal: ontologies and integrated data
resources at the click of a mouse. Nucleic Acids Res. 2009 Jul 1;37(Web Server
issue):W170-3. Epub 2009 May 29. PubMed PMID: 19483092; PubMed Central PMCID:
PMC2703982.

=Ontology Content=

==Building Ontologies==

===How do I go about building an ontology?===

There are a plethora of tools for building ontologies. Below are two preferred tools for building OWL and OBO ontologies:

1) Protege (http://protege.stanford.edu/) - OWL ontologies

2) OBOEdit (http://oboedit.org/) - OBO ontologies

===What is the OBO Foundry?===

A collaborative experiment, involving a group of OBO ontology developers who have agreed in advance to the adoption of a growing set of principles specifying best practices in ontology development. These principles are designed to foster interoperability of ontologies within the broader OBO framework, and also to ensure a gradual improvement of quality and formal rigor in ontologies, in ways designed to meet the increasing needs of data and information integration in the biomedical domain. See http://obofoundry.org/

=NCBO Products=

==What is BioPortal?==
A Web-based application for searching, sharing, visualizing, and analyzing a large repository of biomedical ontologies, terminologies, and ontology-based annotations. BioPortal is available at: http://bioportal.bioontology.org/. All content of BioPortal is also accessible via RESTful web services. To learn more about how to use NCBO technology in your software see the page [[Using_NCBO_Technology_In_Your_Project|Using NCBO Technology In Your Project]]

BioPortal allows for mappings between terms, bulk export of mappings, visualization of terms and relationships within ontologies, notes, and navigation of multiple ontologies through tabbed browsing. To see a demo of BioPortal, please visit http://www.bioontology.org/BioPortal.

==What is the NCBO Resource Index?==
A set of ontology-based annotations of biomedical data. These annotations have been generated automatically via the NCBO Resource Index workflow. The annotations can be accessed from BioPortal, either from from the All Resources tab to search for term annotations or from the Resource Index tab to browse annotations for an individual term. This tool enables researchers to search for biomedical resources associated (or annotated) with specific ontology terms.

==What is the NCBO Annotator?==
The NCBO Annotator is a text annotation tool that uses mgrep, developed by the University of Michigan, as the entity recognizer and the entire library of BioPortal ontologies as the dictionary of terms. This tool can be accessed from BioPortal and also via programmatic access directly to the Web service.

==I have a lot of data to analyze. How can I use the API to access BioPortal products efficiently?==
This [https://www.bioontology.org/wiki/Annotator_Optimizing_and_Troublehooting Annotator Optimizing and Troubleshooting page] has many tips that apply to many API requests, not just the NCBO Annotator.

==What is Phenote?==
A Java client application for manual creation and storage of biomedical annotations (starting with phenotype annotations) using terms from multiple ontologies.

==What is Open Biomedical Data?==
A database of manually generated biomedical annotations (starting with phenotype annotations) summarizing key attributes such as anatomy, phenotype, and genetic features. The annotations are currently loaded directly from a Phenote file, which contains the manually created annotations.

==incomplete is-a paths==

Many OBO ontologies are currently incomplete with respect to all classes/terms having an is-a parent. Many tools (including OBO-Edit and AmiGO) deliberately allow the conflation of relations when presenting the ontology as a DAG or a tree to the user. However, other tools (including Protege and SWOOP) do not. This means that some OBO ontologies can look unusual when viewed with these other tools (lots of classes appear at the root level).

This is currently being addressed by the maintainers of OBO ontologies. An effort is underway to complete the is-a parentage in the GO cellular component ontology (biological process will be more difficult). The Plant Ontology Consortium are completing the is-a parentage in the plant anatomical structure ontology.

Until this work is complete, some OBO ontologies may look unusual when viewed in conventional ontology browsing and editing tools. With some of these tools, there may be some configurations which allow other relations to be conflated with the is-a relation when presenting the ontology as a DAG or tree view.

One option is to automatically create an is-a parent to the ontology root for every non-root class/term which lacks any is-a parents. Note that this may create inconsistencies in the ontology if the genuine is-a parent is somewhere deeper in the ontology hierarchy; nevertheless this step may be necessary before presenting some OBO ontologies to tools such as reasoners.

=Details=

==Ontology Metadata==
Ontology metadata represented in BioPortal uses the Ontology Metadata Vocabulary (OMV) format to store all ontology meta data. Please see the following web site for more information on the format (http://omv.ontoware.org/). To view in BioPortal, see [http://bioportal.bioontology.org/virtual/1148 BioPortal Metadata] and to read more about how OMV is used in BioPortal see [[BioPortal_Metadata|BioPortal Metadata Requirements]]

==OBO Format==

Questions about the OBO text and xml formats

===What is OBO Format?===

===Is OBO Format different from the old GO format?===

Yes. The old dag-edit format (i.e. the one in which indentation was used to denote the GO hierarchy) is STRONGLY deprecated.

===Where can I find the spec?===

You can find details on the 1.0 spec on the GO home page
http://www.geneontology.org/GO.format.shtml#oboflat

This spec is somewhat underspecified

The 1.2 spec is in preparation, and will be released to coincide with the first production OBO-Edit release sometime early in 2006

You can find a preliminary version of the spec here:
HTML -- http://www.godatabase.org/dev/doc/obo_format_spec.html
PDF -- http://www.godatabase.org/dev/doc/obo_format_spec.pdf
Ascii text -- http://www.godatabase.org/dev/doc/obo_format_spec.txt

===Why not use XML?===

There is also an obo-xml format. See

http://www.godatabase.org/dev/xml

Currently only available as DTD. Relax-NG and XSD coming soon.

===Is there a UML model?===

Yes, there is a UML translation of the obo format in progress, produced by Harold Solbrig of Mayo clinic; see:

http://informatics.mayo.edu/schema/OBO/UMLModel/HTML/

===What tools support Obo-Format?===

The following are *ontology* tools that support the OBO format. There are many other tools for the analysis of gene ontology data which also happen to read the OBO format - see http://www.geneontology.org/GO.tools.shtml for a list

; OBO-Edit
: (naturally!). You should use this rather than DAG-Edit (DAG-Edit still supports obo-1.0 format), as DAG-Edit is deprecated as of 2006.

; COBRA
: developed by Stuart Aitken as part of http://www.xspan.org. COBRA is a java ontology editor/viewer for aligning ontologies

; go-perl
: http://search.cpan.org/~cmungall/go-perl

==Using Protege with OBO ontologies==

You have two options here - use the Protege OBO plugin, or convert to a format which Protege understands.

The OBO plugin was developed at the University of Washington, and is no longer supported.

You can convert any obo-format file to OWL and use Protege-OWL (but not Protege-classic); see the next entry.

Note that when you look at many of the OBO ontologies in Protege (classic or Protege-OWL) you will see that there are large amounts of classes apparently at the root level. This is because OBO ontologies have historically not been complete with respect to all classes having a superclass (is-a parent). This is currently being addressed. See the FAQ entry on this subject.

===Can I convert Obo-format to OWL?===

Yes. There are multiple ways to convert ontologies between OWL and OBO format.

*Using the owl-api

*Using Protege 4
**[http://protege.stanford.edu/ Protege 4] uses the owl-api which is able to open both OWL and OBO format ontologies.

*Using the xslts included in go-perl.
**Download and install: http://search.cpan.org/~cmungall/go-perl/
**Then run the script
**go2owl myontology.obo. This functionality will soon be available from oboedit
**For more details on the mapping, see: http://www.fruitfly.org/~cjm/obol/doc/mapping-obo-to-owl.html

===OK, but can I just download OBO ontologies as OWL without doing the conversion myself?===

You can, at least for some OBO ontologies. This is an experimental service, and will eventually be subsumed into the services provided by NCBO:

http://www.fruitfly.org/~cjm/obo-download

===Can I convert Obo-format files to Protege-classic?===

Not yet. In theory it should not be hard to provide an XSL for this. The reverse transformation may be more difficult.

==OBD==

===What is OBD?===

OBD is a database for storing data typed using OBO ontologies

===Where is it?===

In development!

===Is there a demo?===

See http://www.fruitfly.org/~cjm/obd

===Datasets===

See the above URL for now

BioPortal Help

2019-02-27T01:56:23Z

Graybeal: added link to FAQ

== User Interface ==
=== Home Page ===

BioPortal provides access to commonly used biomedical ontologies and to tools for working with them. BioPortal allows you to
* [[#Browse Tab|browse the library]] of ontologies
* [[#Search Tab|search for a term]] across multiple ontologies
* [[#Mappings Tab|browse mappings]] between terms in different ontologies
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
* [[#Annotator Tab|annotate text]] with terms from ontologies
* [[#Resource Index Tab|search biomedical resources]] for a term
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources

All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://data.bioontology.org/documentation REST API documentation] for more information.

=== Browse Tab ===

Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.

To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field. You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.

Some submitters want to control who can browse the terms in their ontology. These ontologies are marked with visibility “Private” or “Licensed”. To browse the terms in these ontologies you must be both
* logged in to BioPortal
* granted access to the ontology
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.

To '''access ontologies programmatically''', see our [http://data.bioontology.org/documentation#nav_resource_endpoints Resources REST API documentation] (then look under Media Types).

=== Search Tab ===

Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.

To '''find a term in any ontology''' enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.

Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.

To '''search programmatically''' see our [http://data.bioontology.org/documentation#nav_search Search REST API documentation].

=== Mappings Tab ===

Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings Mapping Documentation]).

To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.

To '''access mappings programmatically''', please see our [http://data.bioontology.org/documentation#Mapping Mappings REST API documentation].

=== Recommender Tab ===

The Recommender takes as input a text or a list of keywords and '''suggests appropriate ontologies''' for it.

The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:
* '''Coverage''': At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
* '''Acceptance''': How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
* '''Detail of knowledge''': What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
* '''Specialization''': How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.

For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.

Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.

To '''retrieve ontology recommendations programmatically''', please see our [http://data.bioontology.org/documentation#nav_recommender Ontology Recommender REST API documentation].

To '''cite the NCBO Ontology Recommender''', please use:

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== Annotator Tab ===

To '''generate annotations for text''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.

In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship. You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.

To '''generate annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_User_Guide REST API documentation].

Further information about the workings of the Annotator is available at [http://www.ncbi.nlm.nih.gov/pubmed/19761568 Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14]

=== Resource Index Tab ===

The resource index is a pre-calculated set of annotations of selected biomedical resources. We have used the Annotator web service to annotate these resources with all terms in all ontologies in BioPortal. To retrieve records annotated with a specific ontology term, select the term in the search box and press the "Search" button.

To '''access annotations for resources programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide Resource Index REST API documentation].

Further information on ontology-based search and mining of biomedical resources is available in [http://www.ncbi.nlm.nih.gov/pubmed/21918645 Jonquet et al Web Semant. 2011 Sep 1;9(3):316-324], [http://www.ncbi.nlm.nih.gov/pubmed/21550421 LePendu et al J Biomed Inform. 2011 Dec;44 Suppl 1:S31-8] and [http://www.ncbi.nlm.nih.gov/pubmed/22494789 Liu et al J Am Med Inform Assoc. 2012 Apr 11]

If you know of a publicly available biomedical resource that you would like to see in the Resource Index please send a request to include it to support@bioontology.org.

=== Projects Tab ===

This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.

== Common Tasks ==

=== Submitting an ontology ===
If you haven’t already signed up for an account at the BioPortal website, you’ll need to do that first:

http://bioportal.bioontology.org/accounts/new

Once you have an account and are logged in, navigate to the Browse page:

http://bioportal.bioontology.org/ontologies

… and click the "Submit New Ontology" button.

In the resulting form, you’ll be asked to fill out some metadata about your ontology, e.g., name, acronym, etc. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.

Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology. Note that so far you are only describing the ontology in general terms, not submitting a specific file.

Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.

Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.

==== Updating an existing ontology submission ====
If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.

If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.

If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).

To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).

==== Updating metadata for your submission ====
If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.

==== Update ontology settings ====
To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).

Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.

=== Viewing and editing mappings ===
To view all mappings for an ontology, chose the ontology from the Browse page and then select "Mappings" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.

=== Viewing and editing notes ===
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.

=== Viewing and editing reviews ===
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.

=== Visualizing concepts and mappings ===
With the BioPortal user interface, you can [http://www.bioontology.org/wiki/index.php/Visualizing_Concepts_and_Mappings visualize ontology concepts and their mappings with other ontologies].

== Programming with the BioPortal API ==
Documentation about how to use the BioPortal REST API to access information is available here:

http://data.bioontology.org/documentation

=== Getting an API key ===
Use of the BioPortal REST API requires an API key.

To retrieve your API key, log into your account on the [http://bioportal.bioontology.org BioPortal website]. If you don't have an account, you'll need to [http://bioportal.bioontology.org/accounts/new create one].

Your API key will be listed in plain text on your account page.

== Glossary ==
; class: A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
; concept: (from SKOS documentation) A concept is an idea or notion; a unit of thought.
; CUI: Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
; deprecated term: synonym for "obsolete term" in some ontologies.
; group: a collection of ontologies that are typically associated with some outside group or organization.
; obsolete term: A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
; mapping: Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
; property: Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).
; resource: Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
; slice: An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
; synonym: Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
; term: Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
; term mappings: Set of mappings for a given term to terms other ontologies.
; term resources: Set of resources that contain annotations for a given term.

== BioPortal Frequently Asked Questions (FAQ) ==

Many specific questions are addressed at our [https://www.bioontology.org/wiki/BioPortal_FAQ FAQ for the BioPortal system].

== How to cite NCBO and BioPortal ==
=== NCBO ===
Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.

===NCBO Ontology Recommender===
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== BioPortal ===
Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.

=== SPARQL Endpoint ===
Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

BioPortal Help

2018-10-01T19:26:42Z

Graybeal: /* Common Tasks */ edited for level 4 headers

== User Interface ==
=== Home Page ===

BioPortal provides access to commonly used biomedical ontologies and to tools for working with them. BioPortal allows you to
* [[#Browse Tab|browse the library]] of ontologies
* [[#Search Tab|search for a term]] across multiple ontologies
* [[#Mappings Tab|browse mappings]] between terms in different ontologies
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
* [[#Annotator Tab|annotate text]] with terms from ontologies
* [[#Resource Index Tab|search biomedical resources]] for a term
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources

All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://data.bioontology.org/documentation REST API documentation] for more information.

=== Browse Tab ===

Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.

To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field. You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.

Some submitters want to control who can browse the terms in their ontology. These ontologies are marked with visibility “Private” or “Licensed”. To browse the terms in these ontologies you must be both
* logged in to BioPortal
* granted access to the ontology
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.

To '''access ontologies programmatically''', see our [http://data.bioontology.org/documentation#nav_resource_endpoints Resources REST API documentation] (then look under Media Types).

=== Search Tab ===

Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.

To '''find a term in any ontology''' enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.

Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.

To '''search programmatically''' see our [http://data.bioontology.org/documentation#nav_search Search REST API documentation].

=== Mappings Tab ===

Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings Mapping Documentation]).

To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.

To '''access mappings programmatically''', please see our [http://data.bioontology.org/documentation#Mapping Mappings REST API documentation].

=== Recommender Tab ===

The Recommender takes as input a text or a list of keywords and '''suggests appropriate ontologies''' for it.

The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:
* '''Coverage''': At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
* '''Acceptance''': How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
* '''Detail of knowledge''': What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
* '''Specialization''': How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.

For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.

Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.

To '''retrieve ontology recommendations programmatically''', please see our [http://data.bioontology.org/documentation#nav_recommender Ontology Recommender REST API documentation].

To '''cite the NCBO Ontology Recommender''', please use:

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== Annotator Tab ===

To '''generate annotations for text''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.

In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship. You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.

To '''generate annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_User_Guide REST API documentation].

Further information about the workings of the Annotator is available at [http://www.ncbi.nlm.nih.gov/pubmed/19761568 Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14]

=== Resource Index Tab ===

The resource index is a pre-calculated set of annotations of selected biomedical resources. We have used the Annotator web service to annotate these resources with all terms in all ontologies in BioPortal. To retrieve records annotated with a specific ontology term, select the term in the search box and press the "Search" button.

To '''access annotations for resources programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide Resource Index REST API documentation].

Further information on ontology-based search and mining of biomedical resources is available in [http://www.ncbi.nlm.nih.gov/pubmed/21918645 Jonquet et al Web Semant. 2011 Sep 1;9(3):316-324], [http://www.ncbi.nlm.nih.gov/pubmed/21550421 LePendu et al J Biomed Inform. 2011 Dec;44 Suppl 1:S31-8] and [http://www.ncbi.nlm.nih.gov/pubmed/22494789 Liu et al J Am Med Inform Assoc. 2012 Apr 11]

If you know of a publicly available biomedical resource that you would like to see in the Resource Index please send a request to include it to support@bioontology.org.

=== Projects Tab ===

This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.

== Common Tasks ==

=== Submitting an ontology ===
If you haven’t already signed up for an account at the BioPortal website, you’ll need to do that first:

http://bioportal.bioontology.org/accounts/new

Once you have an account and are logged in, navigate to the Browse page:

http://bioportal.bioontology.org/ontologies

… and click the "Submit New Ontology" button.

In the resulting form, you’ll be asked to fill out some metadata about your ontology, e.g., name, acronym, etc. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.

Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology. Note that so far you are only describing the ontology in general terms, not submitting a specific file.

Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.

Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.

==== Updating an existing ontology submission ====
If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.

If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.

If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).

To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).

==== Updating metadata for your submission ====
If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.

==== Update ontology settings ====
To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).

Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.

=== Viewing and editing mappings ===
To view all mappings for an ontology, chose the ontology from the Browse page and then select "Mappings" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.

=== Viewing and editing notes ===
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.

=== Viewing and editing reviews ===
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.

=== Visualizing concepts and mappings ===
With the BioPortal user interface, you can [http://www.bioontology.org/wiki/index.php/Visualizing_Concepts_and_Mappings visualize ontology concepts and their mappings with other ontologies].

== Programming with the BioPortal API ==
Documentation about how to use the BioPortal REST API to access information is available here:

http://data.bioontology.org/documentation

=== Getting an API key ===
Use of the BioPortal REST API requires an API key.

To retrieve your API key, log into your account on the [http://bioportal.bioontology.org BioPortal website]. If you don't have an account, you'll need to [http://bioportal.bioontology.org/accounts/new create one].

Your API key will be listed in plain text on your account page.

== Glossary ==
; class: A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
; concept: (from SKOS documentation) A concept is an idea or notion; a unit of thought.
; CUI: Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
; deprecated term: synonym for "obsolete term" in some ontologies.
; group: a collection of ontologies that are typically associated with some outside group or organization.
; obsolete term: A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
; mapping: Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
; property: Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).
; resource: Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
; slice: An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
; synonym: Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
; term: Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
; term mappings: Set of mappings for a given term to terms other ontologies.
; term resources: Set of resources that contain annotations for a given term.

== How to cite NCBO and BioPortal ==
=== NCBO ===
Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.

===NCBO Ontology Recommender===
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== BioPortal ===
Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.

=== SPARQL Endpoint ===
Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

BioPortal Help

2018-10-01T19:26:07Z

Graybeal: /* Updating an existing ontology submission */

== User Interface ==
=== Home Page ===

BioPortal provides access to commonly used biomedical ontologies and to tools for working with them. BioPortal allows you to
* [[#Browse Tab|browse the library]] of ontologies
* [[#Search Tab|search for a term]] across multiple ontologies
* [[#Mappings Tab|browse mappings]] between terms in different ontologies
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
* [[#Annotator Tab|annotate text]] with terms from ontologies
* [[#Resource Index Tab|search biomedical resources]] for a term
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources

All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://data.bioontology.org/documentation REST API documentation] for more information.

=== Browse Tab ===

Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.

To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field. You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.

Some submitters want to control who can browse the terms in their ontology. These ontologies are marked with visibility “Private” or “Licensed”. To browse the terms in these ontologies you must be both
* logged in to BioPortal
* granted access to the ontology
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.

To '''access ontologies programmatically''', see our [http://data.bioontology.org/documentation#nav_resource_endpoints Resources REST API documentation] (then look under Media Types).

=== Search Tab ===

Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.

To '''find a term in any ontology''' enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.

Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.

To '''search programmatically''' see our [http://data.bioontology.org/documentation#nav_search Search REST API documentation].

=== Mappings Tab ===

Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings Mapping Documentation]).

To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.

To '''access mappings programmatically''', please see our [http://data.bioontology.org/documentation#Mapping Mappings REST API documentation].

=== Recommender Tab ===

The Recommender takes as input a text or a list of keywords and '''suggests appropriate ontologies''' for it.

The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:
* '''Coverage''': At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
* '''Acceptance''': How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
* '''Detail of knowledge''': What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
* '''Specialization''': How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.

For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.

Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.

To '''retrieve ontology recommendations programmatically''', please see our [http://data.bioontology.org/documentation#nav_recommender Ontology Recommender REST API documentation].

To '''cite the NCBO Ontology Recommender''', please use:

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== Annotator Tab ===

To '''generate annotations for text''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.

In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship. You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.

To '''generate annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_User_Guide REST API documentation].

Further information about the workings of the Annotator is available at [http://www.ncbi.nlm.nih.gov/pubmed/19761568 Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14]

=== Resource Index Tab ===

The resource index is a pre-calculated set of annotations of selected biomedical resources. We have used the Annotator web service to annotate these resources with all terms in all ontologies in BioPortal. To retrieve records annotated with a specific ontology term, select the term in the search box and press the "Search" button.

To '''access annotations for resources programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide Resource Index REST API documentation].

Further information on ontology-based search and mining of biomedical resources is available in [http://www.ncbi.nlm.nih.gov/pubmed/21918645 Jonquet et al Web Semant. 2011 Sep 1;9(3):316-324], [http://www.ncbi.nlm.nih.gov/pubmed/21550421 LePendu et al J Biomed Inform. 2011 Dec;44 Suppl 1:S31-8] and [http://www.ncbi.nlm.nih.gov/pubmed/22494789 Liu et al J Am Med Inform Assoc. 2012 Apr 11]

If you know of a publicly available biomedical resource that you would like to see in the Resource Index please send a request to include it to support@bioontology.org.

=== Projects Tab ===

This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.

== Common Tasks ==

=== Submitting an ontology ===
If you haven’t already signed up for an account at the BioPortal website, you’ll need to do that first:

http://bioportal.bioontology.org/accounts/new

Once you have an account and are logged in, navigate to the Browse page:

http://bioportal.bioontology.org/ontologies

… and click the "Submit New Ontology" button.

In the resulting form, you’ll be asked to fill out some metadata about your ontology, e.g., name, acronym, etc. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.

Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology. Note that so far you are only describing the ontology in general terms, not submitting a specific file.

Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.

Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.

==== Updating an existing ontology submission ====
If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.

If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.

If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).

To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).

=== Updating metadata for your submission ===
If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.

=== Update ontology settings ===
To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).

Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.

=== Viewing and editing mappings ===
To view all mappings for an ontology, chose the ontology from the Browse page and then select "Mappings" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.

=== Viewing and editing notes ===
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.

=== Viewing and editing reviews ===
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.

=== Visualizing concepts and mappings ===
With the BioPortal user interface, you can [http://www.bioontology.org/wiki/index.php/Visualizing_Concepts_and_Mappings visualize ontology concepts and their mappings with other ontologies].

== Programming with the BioPortal API ==
Documentation about how to use the BioPortal REST API to access information is available here:

http://data.bioontology.org/documentation

=== Getting an API key ===
Use of the BioPortal REST API requires an API key.

To retrieve your API key, log into your account on the [http://bioportal.bioontology.org BioPortal website]. If you don't have an account, you'll need to [http://bioportal.bioontology.org/accounts/new create one].

Your API key will be listed in plain text on your account page.

== Glossary ==
; class: A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
; concept: (from SKOS documentation) A concept is an idea or notion; a unit of thought.
; CUI: Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
; deprecated term: synonym for "obsolete term" in some ontologies.
; group: a collection of ontologies that are typically associated with some outside group or organization.
; obsolete term: A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
; mapping: Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
; property: Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).
; resource: Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
; slice: An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
; synonym: Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
; term: Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
; term mappings: Set of mappings for a given term to terms other ontologies.
; term resources: Set of resources that contain annotations for a given term.

== How to cite NCBO and BioPortal ==
=== NCBO ===
Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.

===NCBO Ontology Recommender===
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== BioPortal ===
Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.

=== SPARQL Endpoint ===
Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

BioPortal Help

2018-10-01T19:22:09Z

Graybeal: /* Submitting an ontology */ added some updating information

== User Interface ==
=== Home Page ===

BioPortal provides access to commonly used biomedical ontologies and to tools for working with them. BioPortal allows you to
* [[#Browse Tab|browse the library]] of ontologies
* [[#Search Tab|search for a term]] across multiple ontologies
* [[#Mappings Tab|browse mappings]] between terms in different ontologies
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
* [[#Annotator Tab|annotate text]] with terms from ontologies
* [[#Resource Index Tab|search biomedical resources]] for a term
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources

All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://data.bioontology.org/documentation REST API documentation] for more information.

=== Browse Tab ===

Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.

To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field. You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.

Some submitters want to control who can browse the terms in their ontology. These ontologies are marked with visibility “Private” or “Licensed”. To browse the terms in these ontologies you must be both
* logged in to BioPortal
* granted access to the ontology
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.

To '''access ontologies programmatically''', see our [http://data.bioontology.org/documentation#nav_resource_endpoints Resources REST API documentation] (then look under Media Types).

=== Search Tab ===

Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.

To '''find a term in any ontology''' enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.

Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.

To '''search programmatically''' see our [http://data.bioontology.org/documentation#nav_search Search REST API documentation].

=== Mappings Tab ===

Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings Mapping Documentation]).

To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.

To '''access mappings programmatically''', please see our [http://data.bioontology.org/documentation#Mapping Mappings REST API documentation].

=== Recommender Tab ===

The Recommender takes as input a text or a list of keywords and '''suggests appropriate ontologies''' for it.

The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:
* '''Coverage''': At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
* '''Acceptance''': How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
* '''Detail of knowledge''': What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
* '''Specialization''': How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.

For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.

Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.

To '''retrieve ontology recommendations programmatically''', please see our [http://data.bioontology.org/documentation#nav_recommender Ontology Recommender REST API documentation].

To '''cite the NCBO Ontology Recommender''', please use:

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== Annotator Tab ===

To '''generate annotations for text''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.

In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship. You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.

To '''generate annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_User_Guide REST API documentation].

Further information about the workings of the Annotator is available at [http://www.ncbi.nlm.nih.gov/pubmed/19761568 Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14]

=== Resource Index Tab ===

The resource index is a pre-calculated set of annotations of selected biomedical resources. We have used the Annotator web service to annotate these resources with all terms in all ontologies in BioPortal. To retrieve records annotated with a specific ontology term, select the term in the search box and press the "Search" button.

To '''access annotations for resources programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide Resource Index REST API documentation].

Further information on ontology-based search and mining of biomedical resources is available in [http://www.ncbi.nlm.nih.gov/pubmed/21918645 Jonquet et al Web Semant. 2011 Sep 1;9(3):316-324], [http://www.ncbi.nlm.nih.gov/pubmed/21550421 LePendu et al J Biomed Inform. 2011 Dec;44 Suppl 1:S31-8] and [http://www.ncbi.nlm.nih.gov/pubmed/22494789 Liu et al J Am Med Inform Assoc. 2012 Apr 11]

If you know of a publicly available biomedical resource that you would like to see in the Resource Index please send a request to include it to support@bioontology.org.

=== Projects Tab ===

This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.

== Common Tasks ==

=== Submitting an ontology ===
If you haven’t already signed up for an account at the BioPortal website, you’ll need to do that first:

http://bioportal.bioontology.org/accounts/new

Once you have an account and are logged in, navigate to the Browse page:

http://bioportal.bioontology.org/ontologies

… and click the "Submit New Ontology" button.

In the resulting form, you’ll be asked to fill out some metadata about your ontology, e.g., name, acronym, etc. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.

Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology. Note that so far you are only describing the ontology in general terms, not submitting a specific file.

Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.

Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.

=== Updating an existing ontology submission ===
If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.

If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.

If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).

To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).

=== Updating metadata for your submission ===
If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.

=== Update ontology settings ===
To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).

Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.

=== Viewing and editing mappings ===
To view all mappings for an ontology, chose the ontology from the Browse page and then select "Mappings" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.

=== Viewing and editing notes ===
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.

=== Viewing and editing reviews ===
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.

=== Visualizing concepts and mappings ===
With the BioPortal user interface, you can [http://www.bioontology.org/wiki/index.php/Visualizing_Concepts_and_Mappings visualize ontology concepts and their mappings with other ontologies].

== Programming with the BioPortal API ==
Documentation about how to use the BioPortal REST API to access information is available here:

http://data.bioontology.org/documentation

=== Getting an API key ===
Use of the BioPortal REST API requires an API key.

To retrieve your API key, log into your account on the [http://bioportal.bioontology.org BioPortal website]. If you don't have an account, you'll need to [http://bioportal.bioontology.org/accounts/new create one].

Your API key will be listed in plain text on your account page.

== Glossary ==
; class: A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
; concept: (from SKOS documentation) A concept is an idea or notion; a unit of thought.
; CUI: Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
; deprecated term: synonym for "obsolete term" in some ontologies.
; group: a collection of ontologies that are typically associated with some outside group or organization.
; obsolete term: A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
; mapping: Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
; property: Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).
; resource: Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
; slice: An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
; synonym: Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
; term: Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
; term mappings: Set of mappings for a given term to terms other ontologies.
; term resources: Set of resources that contain annotations for a given term.

== How to cite NCBO and BioPortal ==
=== NCBO ===
Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.

===NCBO Ontology Recommender===
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

=== BioPortal ===
Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.

=== SPARQL Endpoint ===
Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

BioPortal Virtual Appliance Release Notes

2018-09-21T00:49:18Z

Graybeal: /* OntoPortal Appliance 2.5 (2018-Feb) */ added info re packaging

''This page contains software release notes for the [http://www.bioontology.org/wiki/index.php/Category:NCBO_Virtual_Appliance BioPortal Virtual Appliance].''

Please see the [[BioPortal_Release_Notes|main release notes page]] to access release notes for the Stanford-hosted [http://bioportal.bioontology.org/ BioPortal application].

== OntoPortal Appliance 2.5 (2018-Feb) ==

There is '''important news''' with this release of the Virtual Appliance, please read [https://www.bioontology.org/bioportal_virtual_appliance_25_released our blog post] for details before using it.

* ruby version is upgraded to 2.3.6
* Web UI is updated to v5.4.4
* API has been updated to v5.6.3

This Virtual Appliance has not been released in Amazon Machine Instance format yet; it is only available as an OVF package.

== OntoPortal Appliance 2.5 RC3 (2017-Oct) ==
==== Changes ====
* Web UI is updated to 5.2.0 which incorporates appliance specific UI layout.
* NCBO BioPortal Appliance is rebranded as OntoPortal appliance.

== BioPortal Virtual Appliance 2.5 RC2 (2017-Aug) ==
====Changes ====
* Solr has been updated to v6.6 which now runs as a stand alone service instead of running as a tomcat container.
* Web UI is updated to v5.1.2
* API has been updated to v5.4.1
Please refer to the [[BioPortal_Release_Notes|main release notes page]] for more detailed information on the new features and bug fixes introduced in various Bioportal components.
==== Known issues ====
Web UI layout is not customized for the Appliance. It contains original bioportal.bioontology.org footer and header tool menu has a link to non-functioning resource index tool.

== BioPortal Virtual Appliance 2.5 RC1 (2017-Aug) ==

==== Changes ====
* Web UI is updated to V5.1.1 which is a major overhaul of the user interface. It has been refactored for rails 4.x support and adopted bootstrap UI framework.
* Bundled-in UMLS Semantic Network (STY) ontology was updated to version 2016AA
* Appliance includes scripts for facilitating minor in-place updates of the appliance components such as bioportal_web_up, ontologies_api and ncbo_cron. This is an experimental feature and not guaranteed to work for major appliance upgrades.

Please refer to the [[BioPortal_Release_Notes|main release notes page]] for more detailed information on the new features and bug fixes introduced in various Bioportal components.

==== Known issues ====
* Web UI layout is not customized for the Appliance. It contains original bioportal.bioontology.org footer and header tool menu has a link to non-functioning resource index tool.

==== Components ====
* bioportal_web_ui v5.1.1
* ontologies_api v5.4.0
* ncbo_cron v5.4.0

==== Application Stack ====
* CentOS 6.9
* Apache httpd 2.2.15
* Apache Tomcat 6
* Solr 4.10.4
* MySQL 5.1
* Ruby 2.3.3
* Passenger 5.1.6
* Redis 3.2.9
* Memcached 1.4.4
* 4store v1.1.5-122-g1788d29
* nginx 1.12.1

== BioPortal Virtual Appliance 2.4 (2015-Apr) ==

==== Components ====

* Ontologies API (REST service) v4.15.3
* Annotator
* Recommender
* BioPortal Web User Interface (including ontology visualization, widgets, and Annotator UI) v4.15.5
* BioMixer

Note that release 4.15 was a silent release, implying that it contained bug fixes and other non-visible changes, and the third release number (.3, .5) indicates a patch number.

==== Application server stack ====

* CentOS 6.6
* Apache httpd 2.2.15
* Apache Tomcat 6.0.24
* Solr 4.10.4
* MySQL 5.1.73
* Ruby 2.1.5
* Passenger 4.0.57
* Redis 2.8.18
* Memcached 1.4.4
* 4store v1.1.5-122-g1788d29
* nginx 1.6.3

BioPortal FAQ

2018-06-24T01:04:00Z

Graybeal: fixed the bad link, I hope

BioPortal Virtual Appliance Release Notes

2018-03-10T02:39:47Z

Graybeal: /* OntoPortal Appliance 2.5 (2018-Feb) */

''This page contains software release notes for the [http://www.bioontology.org/wiki/index.php/Category:NCBO_Virtual_Appliance BioPortal Virtual Appliance].''

Please see the [[BioPortal_Release_Notes|main release notes page]] to access release notes for the Stanford-hosted [http://bioportal.bioontology.org/ BioPortal application].

== OntoPortal Appliance 2.5 (2018-Feb) ==

There is '''important news''' with this release of the Virtual Appliance, please read [https://www.bioontology.org/bioportal_virtual_appliance_25_released our blog post] for details before using it.

* ruby version is upgraded to 2.3.6
* Web UI is updated to v5.4.4
* API has been updated to v5.6.3

== OntoPortal Appliance 2.5 RC3 (2017-Oct) ==
==== Changes ====
* Web UI is updated to 5.2.0 which incorporates appliance specific UI layout.
* NCBO BioPortal Appliance is rebranded as OntoPortal appliance.

== BioPortal Virtual Appliance 2.5 RC2 (2017-Aug) ==
====Changes ====
* Solr has been updated to v6.6 which now runs as a stand alone service instead of running as a tomcat container.
* Web UI is updated to v5.1.2
* API has been updated to v5.4.1
Please refer to the [[BioPortal_Release_Notes|main release notes page]] for more detailed information on the new features and bug fixes introduced in various Bioportal components.
==== Known issues ====
Web UI layout is not customized for the Appliance. It contains original bioportal.bioontology.org footer and header tool menu has a link to non-functioning resource index tool.

== BioPortal Virtual Appliance 2.5 RC1 (2017-Aug) ==

==== Changes ====
* Web UI is updated to V5.1.1 which is a major overhaul of the user interface. It has been refactored for rails 4.x support and adopted bootstrap UI framework.
* Bundled-in UMLS Semantic Network (STY) ontology was updated to version 2016AA
* Appliance includes scripts for facilitating minor in-place updates of the appliance components such as bioportal_web_up, ontologies_api and ncbo_cron. This is an experimental feature and not guaranteed to work for major appliance upgrades.

Please refer to the [[BioPortal_Release_Notes|main release notes page]] for more detailed information on the new features and bug fixes introduced in various Bioportal components.

==== Known issues ====
* Web UI layout is not customized for the Appliance. It contains original bioportal.bioontology.org footer and header tool menu has a link to non-functioning resource index tool.

==== Components ====
* bioportal_web_ui v5.1.1
* ontologies_api v5.4.0
* ncbo_cron v5.4.0

==== Application Stack ====
* CentOS 6.9
* Apache httpd 2.2.15
* Apache Tomcat 6
* Solr 4.10.4
* MySQL 5.1
* Ruby 2.3.3
* Passenger 5.1.6
* Redis 3.2.9
* Memcached 1.4.4
* 4store v1.1.5-122-g1788d29
* nginx 1.12.1

== BioPortal Virtual Appliance 2.4 (2015-Apr) ==

==== Components ====

* Ontologies API (REST service) v4.15.3
* Annotator
* Recommender
* BioPortal Web User Interface (including ontology visualization, widgets, and Annotator UI) v4.15.5
* BioMixer

Note that release 4.15 was a silent release, implying that it contained bug fixes and other non-visible changes, and the third release number (.3, .5) indicates a patch number.

==== Application server stack ====

* CentOS 6.6
* Apache httpd 2.2.15
* Apache Tomcat 6.0.24
* Solr 4.10.4
* MySQL 5.1.73
* Ruby 2.1.5
* Passenger 4.0.57
* Redis 2.8.18
* Memcached 1.4.4
* 4store v1.1.5-122-g1788d29
* nginx 1.6.3

Main Page

2018-01-03T19:58:55Z

Graybeal: /* Documentation */ tweak

Welcome to the '''National Center for Biomedical Ontology (NCBO) public wiki'''. This wiki provides user guides and technical documentation for software developed by NCBO.

Note that as the NCBO project funding has ended, documentation for some projects or project details (n.b., NCBO BioPortal details) may be out of date. Pease send email to the BioPortal Support List

Please visit our [http://www.bioontology.org main site] for more information about NCBO.

__TOC__

== Software ==
To follow is a list of software developed and maintained by NCBO:

* [https://bioportal.bioontology.org BioPortal] - A web-based application for accessing and sharing biomedical ontologies
* [https://data.bioontology.org/ BioPortal REST API] - A RESTful API to access BioPortal content
* [[:Category:NCBO_Virtual_Appliance|BioPortal Virtual Appliance]] - Contains BioPortal and the BioPortal REST API, runs on Linux
* [http://sparql.bioontology.org/ BioPortal SPARQL Endpoint] - Access BioPortal content via SPARQL queries ''(obsolete)''

Please refer to our [[BioPortal_Release_Notes|release notes]] page for change logs.

== Documentation ==

* [[BioPortal Help|BioPortal]] - get help with the user interface and instructions for commonly performed tasks
* [http://data.bioontology.org/documentation BioPortal REST API] - see a list of available endpoints with usage instructions
* [[:Category:NCBO_Virtual_Appliance|BioPortal Virtual Appliance]] - read a getting started guide and installation instructions
* [[Using_NCBO_Technology_In_Your_Project|Using NCBO technologies in your project]] - get ideas for how to employ NCBO technologies in your website or application
* [[SKOSSupport|SKOS support]] - view the specifics of BioPortal's support for SKOS vocabularies
* [[SPARQL_BioPortal|BioPortal SPARQL Endpoint]] - read about programmatic submission of SPARQL queries and the named graph structure
* [[NCBO_Developer_Documentation|Developer documentation]]

=== Mail Support ===

* [https://mailman.stanford.edu/mailman/listinfo/bioontology-support BioPortal Support List] - sign up to see and request community support for BioPortal
* [https://mailman.stanford.edu/pipermail/bioontology-support/ BioPortal mailman email archives] - the usual mailman archive format for BioPortal support list
* [http://ncbo-support.2288202.n4.nabble.com/ BioPortal nabble email archives] - BioPortal support email list archives in easier format to search and navigate

== Ontology Development Projects ==

These are some of the ontology development projects that NCBO participated in:

* [http://bioportal.bioontology.org/ontologies/BRO Biomedical Resource Ontology]
* [http://bioportal.bioontology.org/ontologies/TMO Translational Medicine Ontology]
* [[NPO:Main_Page|NanoParticle Ontology]]
* [http://bioportal.bioontology.org/ontologies/PATO Phenotypic Quality Ontology]
* [[RO:Main_Page|OBO Relations Ontology]]
* [[CARO:Main_Page|Common Anatomy Reference Ontology]]
* [[CL:Main_Page|Cell Ontology]]
* [[SO:Main_Page|Sequence Types and Features Ontology]]
* [[Disease:Main_Page|Disease Ontology]], and other ontologies pertaining to diseases and disorders
* [[OCI:Main_Page|Ontology of Clinical Investigation]]