NCBO Wiki - User contributions [en]

Virtual Appliance FAQ

2015-10-01T16:31:22Z

Palexand: /* How do I add or change slices? */

[[Category:NCBO Virtual Appliance]]

= NCBO VIRTUAL APPLIANCE v2.0 FAQ =
This FAQ now covers the NCBO Virtual Appliance v2.0. 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 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>

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the ncbobp 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 (though this will likely be added in future versions). Slices can be added using a console after logging into the Appliance as the ncbobp 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 ncbobp 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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 ncbobp 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 a 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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).

Virtual Appliance FAQ

2015-09-30T18:35:06Z

Palexand: /* How do I add or change categories or groups? */

[[Category:NCBO Virtual Appliance]]

= NCBO VIRTUAL APPLIANCE v2.0 FAQ =
This FAQ now covers the NCBO Virtual Appliance v2.0. 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 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>

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the ncbobp 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 (though this will likely be added in future versions). Slices can be added using a console after logging into the Appliance as the ncbobp 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")
ont2 = LinkedData::Models::Ontology.find("ONT2")
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 ncbobp 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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 ncbobp 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 a 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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).

NCBO Widgets

2015-02-04T01:05:37Z

Palexand: /* Methods */

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#NCBO Ontology Tree Widget|NCBO Ontology Tree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_acronym_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-NCIT-uri</code> will use NCI Thesaurus (ontology acronym is NCIT) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-NCIT,BIRNLEX-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-NCIT-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{class_id}"</code>
(replace {class_id} with the class id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-NCIT-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "FB-DV";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "NCIT,BIRNLEX";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "NCIT";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<pre>var BP_search_branch = "{class_id}";</pre>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<pre>var BP_include_definitions = true;</pre>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

===Description===
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

===Location===
Add the following files to use the widget:
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree.css
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree-2.0.0.js
Or the minified versions:
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.min.css
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.-2.0.0.min.js

===Setup===
* You will need to use jQuery to utilize the Tree Widget. If you aren't using jQuery already, you can add it as follows: <pre><script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script></pre>
* Create a div element to store the tree: <pre><div id="tree"></div></pre>
* Initialize the tree:<pre>var tree = $("#tree").NCBOTree({
 apikey: "YOUR_API_KEY",
 ontology: "NCIT"
});
</pre>
* The div you created should now contain a tree showing the roots of the NCIT ontology
* Additional setup options:
** '''autoclose''': Close other branches of the tree when expanding a new one
** '''treeClass''': Class to identify the tree with
** '''autocompleteClass''': Class to identify the autocomplete (search) input with
** '''width''': Set the width of the tree and autocomplete input
** '''startingClass''': Start with this class selected (and expanded to) in the tree
** '''startingRoot''': Start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing.
** '''ncboAPIURL''': Use a different NCBO REST instance (not normally used)
** '''ncboUIURL''': Use a different NCBO UI instance (not normally used)

===Callbacks and Event Triggers===
You can interact programmatically with the tree using JavaScript and jQuery. Callbacks can be passed when setting up the tree:
<pre>
var tree = $("#tree").NCBOTree({
apikey: "YOUR_API_KEY",
ontology: "NCIT",
afterSelect: function(event, classId, prefLabel, selectedNode){
console.log(classId);
}
});
</pre>
The following are the available callbacks with their arguments:
* '''beforeExpand''', ''arg'': expandedNode
* '''afterExpand''', ''arg'': expandedNode
* '''afterExpandError''', ''arg'': expandedNode
* '''afterSelect''', ''arg'': classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': classId

You can also listen to these as jQuery events:
<pre>
tree.on("afterSelect", function(event, classId, prefLabel, selectedNode) {
console.log(classId);
}
</pre>

Here are the events with their arguments:
* '''beforeExpand''', ''arg'': event, expandedNode
* '''afterExpand''', ''arg'': event, expandedNode
* '''afterExpandError''', ''arg'': event, expandedNode
* '''afterSelect''', ''arg'': event, classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': event, classId

=== Public Methods ===
There are a variety of methods you can call on the object returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

<pre>
var tree = $("#tree").data("NCBOTree");
// OR
var tree = $("#tree")[0].NCBOTree;
// OR
var tree = document.getElementById("tree").NCBOTree;
</pre>

Once you have the tree instance, you can call the following methods:
* '''tree.selectedClass()''': Returns an object that represents the currently-selected class. The object includes attributes for `id`, `prefLabel`, and `URL`. URL is the REST location of the class, and performing and HTTP GET on that URL will provide a JSON representation of the class.
* '''tree.selectClass(classId)''': Activates the class in the tree with the matching URI (classId). This will only work if the class is already visible.
* '''tree.jumpToClass(classId)''': Replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns.
* '''tree.changeOntology(ontologyAcronym)''': Replaces the current tree with the roots from the given ontology.

NCBO Widgets

2015-02-04T01:05:08Z

Palexand: /* Methods */

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#NCBO Ontology Tree Widget|NCBO Ontology Tree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_acronym_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-NCIT-uri</code> will use NCI Thesaurus (ontology acronym is NCIT) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-NCIT,BIRNLEX-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-NCIT-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{class_id}"</code>
(replace {class_id} with the class id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-NCIT-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "FB-DV";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "NCIT,BIRNLEX";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "NCIT";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<pre>var BP_search_branch = "{class_id}";</pre>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<pre>var BP_include_definitions = true;</pre>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

===Description===
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

===Location===
Add the following files to use the widget:
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree.css
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree-2.0.0.js
Or the minified versions:
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.min.css
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.-2.0.0.min.js

===Setup===
* You will need to use jQuery to utilize the Tree Widget. If you aren't using jQuery already, you can add it as follows: <pre><script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script></pre>
* Create a div element to store the tree: <pre><div id="tree"></div></pre>
* Initialize the tree:<pre>var tree = $("#tree").NCBOTree({
 apikey: "YOUR_API_KEY",
 ontology: "NCIT"
});
</pre>
* The div you created should now contain a tree showing the roots of the NCIT ontology
* Additional setup options:
** '''autoclose''': Close other branches of the tree when expanding a new one
** '''treeClass''': Class to identify the tree with
** '''autocompleteClass''': Class to identify the autocomplete (search) input with
** '''width''': Set the width of the tree and autocomplete input
** '''startingClass''': Start with this class selected (and expanded to) in the tree
** '''startingRoot''': Start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing.
** '''ncboAPIURL''': Use a different NCBO REST instance (not normally used)
** '''ncboUIURL''': Use a different NCBO UI instance (not normally used)

===Callbacks and Event Triggers===
You can interact programmatically with the tree using JavaScript and jQuery. Callbacks can be passed when setting up the tree:
<pre>
var tree = $("#tree").NCBOTree({
apikey: "YOUR_API_KEY",
ontology: "NCIT",
afterSelect: function(event, classId, prefLabel, selectedNode){
console.log(classId);
}
});
</pre>
The following are the available callbacks with their arguments:
* '''beforeExpand''', ''arg'': expandedNode
* '''afterExpand''', ''arg'': expandedNode
* '''afterExpandError''', ''arg'': expandedNode
* '''afterSelect''', ''arg'': classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': classId

You can also listen to these as jQuery events:
<pre>
tree.on("afterSelect", function(event, classId, prefLabel, selectedNode) {
console.log(classId);
}
</pre>

Here are the events with their arguments:
* '''beforeExpand''', ''arg'': event, expandedNode
* '''afterExpand''', ''arg'': event, expandedNode
* '''afterExpandError''', ''arg'': event, expandedNode
* '''afterSelect''', ''arg'': event, classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': event, classId

=== Methods ===
There are a variety of methods you can call on the object returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

<pre>
var tree = $("#tree").data("NCBOTree");
// OR
var tree = $("#tree")[0].NCBOTree;
// OR
var tree = document.getElementById("tree").NCBOTree;
</pre>

Once you have the tree instance, you can call the following methods:
* '''tree.selectedClass()''': Returns an object that represents the currently-selected class. The object includes attributes for `id`, `prefLabel`, and `URL`. URL is the REST location of the class, and performing and HTTP GET on that URL will provide a JSON representation of the class.
* '''tree.selectClass(classId)''': Activates the class in the tree with the matching URI (classId). This will only work if the class is already visible.
* '''tree.jumpToClass(classId)''': Replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns.
* '''tree.changeOntology(ontologyAcronym)''': Replaces the current tree with the roots from the given ontology.

NCBO Widgets

2015-02-04T01:02:02Z

Palexand: /* Location */

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#NCBO Ontology Tree Widget|NCBO Ontology Tree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_acronym_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-NCIT-uri</code> will use NCI Thesaurus (ontology acronym is NCIT) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-NCIT,BIRNLEX-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-NCIT-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{class_id}"</code>
(replace {class_id} with the class id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-NCIT-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "FB-DV";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "NCIT,BIRNLEX";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "NCIT";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<pre>var BP_search_branch = "{class_id}";</pre>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<pre>var BP_include_definitions = true;</pre>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

===Description===
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

===Location===
Add the following files to use the widget:
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree.css
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree-2.0.0.js
Or the minified versions:
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.min.css
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.-2.0.0.min.js

===Setup===
* You will need to use jQuery to utilize the Tree Widget. If you aren't using jQuery already, you can add it as follows: <pre><script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script></pre>
* Create a div element to store the tree: <pre><div id="tree"></div></pre>
* Initialize the tree:<pre>var tree = $("#tree").NCBOTree({
 apikey: "YOUR_API_KEY",
 ontology: "NCIT"
});
</pre>
* The div you created should now contain a tree showing the roots of the NCIT ontology
* Additional setup options:
** '''autoclose''': Close other branches of the tree when expanding a new one
** '''treeClass''': Class to identify the tree with
** '''autocompleteClass''': Class to identify the autocomplete (search) input with
** '''width''': Set the width of the tree and autocomplete input
** '''startingClass''': Start with this class selected (and expanded to) in the tree
** '''startingRoot''': Start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing.
** '''ncboAPIURL''': Use a different NCBO REST instance (not normally used)
** '''ncboUIURL''': Use a different NCBO UI instance (not normally used)

===Callbacks and Event Triggers===
You can interact programmatically with the tree using JavaScript and jQuery. Callbacks can be passed when setting up the tree:
<pre>
var tree = $("#tree").NCBOTree({
apikey: "YOUR_API_KEY",
ontology: "NCIT",
afterSelect: function(event, classId, prefLabel, selectedNode){
console.log(classId);
}
});
</pre>
The following are the available callbacks with their arguments:
* '''beforeExpand''', ''arg'': expandedNode
* '''afterExpand''', ''arg'': expandedNode
* '''afterExpandError''', ''arg'': expandedNode
* '''afterSelect''', ''arg'': classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': classId

You can also listen to these as jQuery events:
<pre>
tree.on("afterSelect", function(event, classId, prefLabel, selectedNode) {
console.log(classId);
}
</pre>

Here are the events with their arguments:
* '''beforeExpand''', ''arg'': event, expandedNode
* '''afterExpand''', ''arg'': event, expandedNode
* '''afterExpandError''', ''arg'': event, expandedNode
* '''afterSelect''', ''arg'': event, classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': event, classId

=== Methods ===
There are a variety of methods you can call on the object returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

* '''tree.selectedClass()''': Returns an object that represents the currently-selected class. The object includes attributes for `id`, `prefLabel`, and `URL`. URL is the REST location of the class, and performing and HTTP GET on that URL will provide a JSON representation of the class.
* '''tree.selectClass(classId)''': Activates the class in the tree with the matching URI (classId). This will only work if the class is already visible.
* '''tree.jumpToClass(classId)''': Replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns.
* '''tree.changeOntology(ontologyAcronym)''': Replaces the current tree with the roots from the given ontology.

Resource Index Dataset Workflow Howto

2015-01-15T00:07:48Z

Palexand: Replaced content with "As of Virtual Appliance v2.2, populating the Resource Index Dataset is no longer supported. A separate Resource Index Virtual Appliance may be released at some point."

As of Virtual Appliance v2.2, populating the Resource Index Dataset is no longer supported. A separate Resource Index Virtual Appliance may be released at some point.

Annotator Dataset Workflow Howto

2015-01-15T00:06:53Z

Palexand: Replaced content with "As of Virtual Appliance v2.2, populating the Annotator Dataset is done automatically when an ontology is processed."

As of Virtual Appliance v2.2, populating the Annotator Dataset is done automatically when an ontology is processed.

Virtual Appliance FAQ

2014-09-17T17:49:11Z

Palexand: /* How can I enable emails for lost passwords, notes, and ontology processing? */

[[Category:NCBO Virtual Appliance]]

= NCBO VIRTUAL APPLIANCE v2.0 FAQ =
This FAQ now covers the NCBO Virtual Appliance v2.0. 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 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>

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the root 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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 a 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-09-16T19:38:56Z

Palexand: /* NCBO VIRTUAL APPLIANCE v2.0 FAQ */

[[Category:NCBO Virtual Appliance]]

= NCBO VIRTUAL APPLIANCE v2.0 FAQ =
This FAQ now covers the NCBO Virtual Appliance v2.0. 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 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_domain = "example.org"
</code>

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the root 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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 a 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

BioPortal Release Notes

2014-09-12T00:19:58Z

Palexand: /* BioPortal Release 4.6 (May 2014) */

== BioPortal Release 4.10 (September 2014) ==

We are happy to announce the release of BioPortal 4.10. We have had a number of “silent releases” since the 4.6 release in late April. We are pleased to announce the latest BioPortal release and fill you in on features that have been released silently in the interim:

* Reengineered the entire Resource Index to achieve better and more consistent performance and to align the Resource Index with the new BioPortal backend (released last year). In addition to allowing us to support additional resources, this revision removes a number of inconsistencies that resulted from the Resource Index using the old BioPortal backend.
* Upgraded the OWL and OBO parser to the latest version and reparsed all OBO and OWL ontologies. This reprocessing fixed a large number of problems with ontologies that either did not parse or that failed search indexing or metrics calculations.
* We now create and make available for download a comma-separated value (CSV) file for most ontologies. These files have one row/class and a standard set of properties in the columns. We cannot make these files available for ontologies if the license for the ontology does not permit it (e.g. SNOMED-CT and MedDRA).
* Fixed PURLS for all ontologies. There were a large number of ontologies for which the PURLs we created, in the old system or the new one, no longer worked correctly.
* Reworked the entire mappings system so that mappings will be always up-to-date with the latest version of the ontologies.
* Created a web page (http://bioportal.bioontology.org/validate_ontology_file) so that users can validate that their ontologies parse correctly with the latest version of the OWL/OBO parser.
* Removed a number of bogus ontologies and spam notes.
* Fixed implementation of “longest only” parameter in Annotator.
* We now reparse and reindex an ontology if the administrator of the ontology changes the metadata for the ontology. The reparse is necessary because the metadata contains information, such as the properties that contain synonyms or definitions, that influence the parsing and indexing.
* Recalculated metrics for all ontologies. This process filled in metrics for many ontologies that lacked them, and corrected the calculations of some metrics in other ontologies.
* We now allow the download of RDF (Turtle) files for UMLS ontologies whose license allows users to download them.
* Reindexing ontologies for search no longer interferes with the use of search on those ontologies. Previously search for an ontology was either broken or incomplete for an ontology that was being indexed.
* Added an ontology properties endpoint to the REST API. This endpoint allows a user to query for the properties used by an ontology.

As previously noted, we have permanently retired the old NCBO BioPortal API. New API documentation is available at
http://data.bioontology.org/documentation.

== BioPortal Release 4.6 (May 2014) ==

* Improved Search Result Display – Many ontologies contain classes that are references to a canonical ontology that “owns” the class. The system now automatically tries to identify the “owning” ontology and emphasize it in the results while displaying the ontologies that contain references to that ontology as subordinate (for that class). This feature is easier to try out than to explain. Type in “cancer” into the search box on the Search Tab and scan through the results to see what it is all about. This sort of display has been requested by a number of users for quite a while and we are happy to finally provide it.
* Implemented Search for ID (URI), UMLS CUI, UMLS TUI, and skos:notation – The search system now will use the input search to find a class URI, a class skos:notation field (“short id” in the old system) or a UMLS “concept unique identifier” or semantic type. All of these fields are available through the default search mechanism. There is still an optional “all properties” parameter to search these property values along with all other property values.
* Released New Version of BioMixer visualization system – The BioMixer system has been updated to improve performance and be more robust. (Work performed by our University of Victoria collaborators.)
* Implemented New Mapping Visualization – Mappings system now allows a user to visualize the strength of mappings relationships between ontologies. Go to the mappings tab, select an ontology, and hit the visualization radio button to try this out. (Work performed by our University of Victoria collaborators.)
* Implemented Configurable REST API calls – The Annotator and Search REST calls now allow a user specify which fields of a class the system should return. The user can also specify “all” to get everything.
* Updated UMLS Ontologies – All UMLS ontologies have been updated to the latest (2013 AB) version.
* Improved Autocomplete – The autocomplete in the ontology “Jump To” box, and in the widgets, now works more reliably with results that are more intuitive than previously.
* Provide Access Control for Mappings – We have implemented access control to prevent people other than the author from deleting a mapping.
* Reimplemented Annotator “Longest Only” Parameter – We have reimplemented the annotator “longest only” parameter to work in all situations. This parameter allows the user to limit the returned results to only those matches which are longer than other matches for a given ontology. In the old system this parameter did not work correctly.
* Reimplemented Widgets to not use Flash – We have reimplemented the widgets to not use the Adobe Flash technology. Requiring the use of this technology was unpopular among our user community.
* Enabled Upload and Download Large Ontologies – We have fixed various timeout problems which prevented users from uploading or downloading large ontologies.
* Fixed Bugs! – Fixed a very large number of bugs, some new with the new system, and some carried forward from the old system.

We have today shut down access to the old BioPortal REST API and will be turning off the old system entirely in the near future. We have provided 7 months for application developers to move to the new system and the vast majority have already done so. The overwhelming response from developers has been the that new system is now (after a few post release glitches!) much easier to use and much more reliable than the old system. Documentation for the new API is available at:
http://data.bioontology.org/documentation

== BioPortal Release 4.0 (September 2013) ==

The primary distinguishing feature of this release is the replacement of several backend storage and caching mechanisms with a single triple-store based backend built with on the open source 4store platform. In addition we are simultaneously releasing a new version of the BioPortal REST API. This API is also built on top of the triple store. It provides a much more uniform and REST-full interface to the underlying BioPortal data than our previous REST API.

The old API will continue to function through the end of 2013. This API will only be able to access “old content” (that is, ontologies submitted or updated before today). We encourage API users to transition as quickly as possible to the new API. The new API is the only way to access both new content (submitted after today) and old content. The reports from beta users of the new API have been uniformly positive. Draft documentation for the new API is available at
http://data.bioontology.org/documentation

BioPortal users will note a few changes from the previous version. Some of these changes are temporary (we didn’t quite get everything done…) while others are permanent. There are also a number of minor and cosmetic changes. The list of the more important changes is available below.

With a release of this size, it is inevitable that some bugs have crept in. Please report any that you run across to the support@bioontology.org mailing list. Have confidence that we will be working diligently to prioritize and fix the problems that arise.

Temporary Changes
* All handling of obsolete classes in UI and API is not supported yet. Obsolete classes are currently indistinguishable from normal classes.
* “Slices” and ontology sets (user defined lists of ontologies of interest) are not supported yet
* The tree browse UI does not yet distinguish between is-a and part-of relations for OBO ontologies. Previously (and probably in the future) icons next to the class name indicated the relationship type.
* We do not yet have a VM version for this release. We expect to produce a new VM version by the end of the year. This VM will include the triple-store based storage mechanism. In addition VM users will be able to query the VM triple-store directly with SPARQL.
* Parsing of new ontologies and new versions remains disabled for the next few days. We will re-enable parsing by early next week.

Permanent Additions
* New ontologies and new versions of ontologies will be typically available for text annotation the next day after submission. Previously the process took several weeks to several months.
* We now have the latest versions UMLS ontologies. Previously we updated UMLS ontologies on request only, which left us with some very old versions. Going forward we will try to update our set of UMLS ontologies within a month of the UMLS release.

Permanent Subtractions
* Programmatic and browse access to classes in non-current versions of ontologies is removed. We still retain metadata about older versions of ontologies and we still allow you to download the source files for old versions.
* We no longer support Protégé Frames format ontologies. Owners of these ontologies will need to convert them to OWL or OBO to load them.
* We now use the owlAPI (http://owlapi.sourceforge.net/) to load OWL and OBO ontologies. This API supports OWL version 2.0. For almost all features, OWL 2.0 is a superset of OWL 1.0. There are some edge cases though where ontologies that marginally parsed with an OWL 1.0 parser will not parse at all with the OWL 2.0 parser. We leave it to OWL ontology owners to provide valid OWL 2.0 ontologies.

== BioPortal Release 3.12 ==
* Implemented the display of the OBO part-of relationship in the term neighborhood visualization.
* Improved some default layouts in the visualization system.
* Updated automated mappings for all ontologies.
* Regenerated the annotator hierarchy database. The versions of ontologies in this database are now much more current.
* Implemented support for federated queries in the [http://sparql.bioontology.org BioPortal SPARQL endpoint].
* Moved the mappings from the BioPortal endpoint into a separate public endpoint. This change allows us to update automated mappings more cleanly.
* Added the following resources to the Resource Index. All of these resources are the results of our collaboration with the [http://www.neuinfo.org/ Neuroscience Information Framework] (NIF) group.
** NIF PubMed Health: Tests
** NIF Drug Related Gene Database
** NIF Gemma
** NIF Integrated Disease View
* Fixed “Maximum Depth” metric for a number of ontologies. Was incorrectly displaying “1” in some cases.
* Fixed web service failure when attempting to retrieve all concepts from several ontologies.
* Fixed annotator to return all ancestor terms. Was missing some ancestors for some ontologies.
* Fixed Search to work correctly in MeSH.
* Fixed problem with SPARQL query to BioPortal endpoint on queries that include ORDER and LIMIT clauses

(Release February 2013)

== BioPortal Release 3.10 ==
* Revised UI for the Resource Index. This new UI supports the BioPortal slice mechanism. The new UI is also much faster than the previous one.
* Updated ontologies available for use with the Annotator which includes newer ontologies and more recent versions of existing ontologies.
* Fixed a longstanding bug in the Annotator that caused paths from a term to root nodes to occasionally be truncated.
* Allow submission of Notes on ontology terms by anonymous users. Previously a user had to be logged in to submit a note.

(Release July 2012)

== BioPortal Release 3.9 ==
* We have revised the search interface, both for specifying a search and in the format of the returned results. The new “advanced search” capability allows users to specify more clearly exactly what terms they would like to find. This capability also allows us to choose better (more commonly desired) defaults for the “basic search”. The returned search results are now grouped by ontology and the results are ranked so that terms from “better” ontologies are returned first. We also show definitions for terms that have them. In general this response format was inspired by the Google search response interface so we hope that it looks familiar. We are specifically soliciting feedback from users on this revision. Please send any comments to support@bioontology.org. *

* We include the first version of the BioMixer visualization software (available through the “Visualize” links). This software replaces the older FlexViz system. There are a number of technology improvements (i.e. the removal of Flash technology) over the older system and the newer system is more powerful as well (i.e. you can now navigate mappings from the basic interface). More complete versions of BioMixer will be introduced in subsequent releases. Please provide any feedback you can on this new system. *

* We have regenerated all automatically generated mappings in the system. These include lexical mappings, UMLS CUI mappings, identical identifier mappings, and OBO-xref mappings. We have also loaded mappings between selected UMLS ontologies as specified in the UMLS database (MRMAP).

<nowiki>*</nowiki> This item was requested via the User Support mailing list. Thank you for your comments and suggestions!

(Release June 2012)

== BioPortal Release 3.8 ==
* We have regenerated all mappings based on UMLS CUIs. Thus terms in different UMLS ontologies which share the same CUI are now mapped to each other. The mapping created is of type skos:closeMatch. There are now 3,000,000 of these UMLS CUI mappings in the system.*

* We have regenerated all mappings based on xrefs (OBO cross-reference) in OBO ontologies. A mapping is now generated when a term in an OBO ontology has an xref to a term in another ontology. The mapping created is of type skos:relatedMatch. There are 35,000 of these xref mappings in the system.*

* We have regenerated all mappings based on terms which have identical unique identifiers (IRIs). A mapping is now generated when term in an ontology has a unique identifier that is identical to the identifier of a term in another ontology. The mapping created is of type skos:exactMatch. There are 700,000 of these identical IRI mappings in the system.*

We also fixed a number of bugs which were causing performance, stability, and ontology upload problems.

<nowiki>*</nowiki>This item was requested via the User Support mailing list and the NCBO User Group. Thank you for your comments and suggestions!

(Release May 2012)

== BioPortal Release 3.7 ==
* Updated term mappings generated by LOOM
* Added boolean functionality to Search Web service and UI
* Updated ontology content for the Resource Index
* BioPortal SPARQL endpoint beta release, http://sparql.bioontology.org
* Modified response of Annotator UI to not fail if input text contains returns or results do not have any term matches*
* Bug fix for Term Autocomplete widget to remove namespace collision with jQuery widgets*

<nowiki>*</nowiki> This item was requested via the User Support mailing list and the NCBO User Group. Thank you for your comments and suggestions!

(Release April 2012)

== BioPortal Release 3.6 ==
* Created “alternate entry points” for BioPortal. These URL’s limit the ontologies that are visible in BioPortal, allowing users to focus on a shared, smaller set of ontologies. The entry points which are currently available are:
** OBO-Foundry: http://obo-foundry.bioportal.bioontology.org
** Unified Medical Language Systems: http://umls.bioportal.bioontology.org
** Cancer Biomedical Informatics Grid: http://cabig.bioportal.bioontology.org
** Clinical and Translational Science Awards: http://ctsa.bioportal.bioontology.org
** CTSA Health Ontology Mapper: http://ctsa-hom.bioportal.bioontology.org
** Proteomics Standards Initiative: http://psi.bioportal.bioontology.org
** WHO Family of International Classifications: http://who-fic.bioportal.bioontology.org
** Consultative Group on Intl Agricultural Research: http://cgiar.bioportal.bioontology.org
** Please contact us on the support mailing list if you would like us to configure an entry point for another set of ontologies.
* Major Updates and Fixes
** Updated the ontologies used by the Annotator Web Services*
** Improved the reliability and robustness of the parsing of OWL 2 ontologies*

<nowiki>*</nowiki> This item was requested via the User Support mailing list and the NCBO User Group. Thank you for your comments and suggestions!

(Release January 2012)

== BioPortal Release 3.5 ==
* Added ability for logged-in users to filter which ontologies appear in their BioPortal display
* Updated Annotator page to simplify the selection of options, to clarify the annotation results, and to remove Flash from the implementation
* Improved Annotator Web service response performance by 5-10x*
* Added ability for the ontology Web services API to optionally return JSON (rather than XML)*
* Updated Ontology Recommender algorithm to provide better recommendations*
* Added display of matched terms for Ontology Recommender*
* Added Web service to get all namespaces for an ontology*
* Bug Fixes
** Display user-friendly names for RxNorm ontology properties

<nowiki>*</nowiki> This item was requested via the User Support mailing list and the NCBO User Group. Thank you for your comments and suggestions!

(Release December 2011)

== BioPortal Release 3.4 ==
* Revised the Term Mappings tab to ease the creation of term-to-term mappings*
* Limited access to “Private” ontologies via the Browse and Search pages
* Added backend support to allow multiple administrators for a single ontology*
* Added ability to copy to the clipboard a permanent link to any BioPortal term*
* Bug Fixes
** Resolved issue causing search to not display all matching terms*
** Fixed Term Mappings tab display for IE 7 & 8*
** Fixed RDF Ontology Download Web service
** Fixed link to the list of resources included in the Resource Index*

<nowiki>*</nowiki> This item was requested via the User Support mailing list and the NCBO User Group. Thank you for your comments and suggestions!

(Release October 2011)

== BioPortal Release 3.3 ==
New features include updates to the Web interface and Web services:
* Added Get Properties Web service, http://www.bioontology.org/wiki/index.php/NCBO_REST_services#Property_Services
* Updated Search page to remove Flash
* Handling of obsolete terms, part 2 – term name is grayed out and <is_obsolete> element is returned in Web service response for obsolete terms from OWL ontologies.
* Added Help documentation
* Implemented a feature to allow ontology submitters to flag their ontology as “licensed”. This feature allows the ontology submitter to require users to provide license information before they are allowed to access the ontology.
* Bug Fix
** Fixed the Filter by Account on the Mappings tab

(Release date September 2011)

== BioPortal Release 3.2 ==
New features include updates to the Web interface and Web services:
* Added Ontology Recommender feature, http://bioportal.bioontology.org/recommender
** Web service documentation: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service
** Sample client information: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Client_Examples
* Added support for access control for viewing ontologies
* Added link to subscribe to BioPortal Notes emails
* Synchronized “Jump To” feature with ontology parsing and display
* Added documentation on Ontology Groups
* Annotator Web service – disabled use of “longest only” parameter when also selecting “ontologies to expand” parameter
* Removed the metric "Number of classes without an author"
* Handling of obsolete terms, part 1 – term name is grayed out and <is_obsolete> element is returned in Web service response for obsolete terms from OBO and RRF ontologies. This feature will be extended to cover OWL ontologies in a subsequent release.
* Bug Fix
** Fixed calculation of “Classes with no definition” metric
** Added re-direct from old BioPortal URL format to new URL format to provide working links from archived search results

'''''Firefox Extension for NCBO API Key''''':
To make it easier to test Web service calls from your browser, we have released the NCBO API Key Firefox Extension. This extension will automatically add your API Key to NCBO REST URLs any time you visit them in Firefox. The extension is available at Mozilla's Add-On site. To use the extension, follow the installation directions, restart Firefox, and add your API Key into the “Options” dialog menu on the Add-Ons management screen. After that, the extension will automatically append your stored API Key any time you visit http://rest.bioontology.org.

'''''Upcoming software license change''''':
The next release of NCBO software will be under the two-clause BSD license rather than under the currently used three-clause BSD license. This change should not affect anyone’s use of NCBO software and this change is to a less restrictive license. More information about these licenses is available at the site: http://www.opensource.org/licenses. Please contact support@bioontology.org with any questions concerning this change.

== BioPortal Release 3.1 ==
New features include updates to the Web interface and Web services:
* Support for loading OWL 2 ontologies
* Security Framework, part 2 - The apikey parameter is now required for all Web services. Login to BioPortal to get your API Key.
* Browsing of ontologies that contain large numbers of sibling terms
* Icons for is_a and part_of are displayed for OBO format ontologies
* Display of the “occurs_in” relationship used in the Extended version of the Gene Ontology
Bug Fix
* Added informative error message when incompatible parameter values are used in the Annotator Web service and updated Perl client to capture this error response

(Release date July 8, 2011)

== BioPortal Release 3.0 ==
New features include updates to the Web interface and Web services:
* Web interface updates
* Browse page now displays ontology features, e.g. size of the ontology, number of notes added to the ontology, number of projects that use the ontology, and number of reviews of the ontology
* New ontology summary details page highlights the ontology metrics, reviews, projects, and derived views of the ontology
* Security Framework, part 1 - Added apikey parameter to all Web services. The apikey parameter is optional until June 15, 2011, after this time the apikey parameter will be required for usage of the Web services. Login to BioPortal to get your API key.
* Provisional Term Web service - New term proposals now receive a provisional term id. Additional Web services are now available for submitting provisional terms. For more details, see: http://www.bioontology.org/wiki/index.php/BioPortal_Provisional_Terms
* Form auto-complete Widget - Option to include term definition in display
* Resource Index
** Data indexed with new ontologies from BioPortal
** PubMed data now available for abstracts published in 2010

(Release date May 19, 2011)

== BioPortal Release 2.6.4 ==
New features include additional Web services and Web interface enhancements:
* Mapping Web services - Access to ontology term mappings, including UMLS, OBO DbXref, and LOOM mappings ( http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service ) ''Please note, the prototype Mapping Web service will be removed March 23''
* RDF Download Web service - Access any BioPortal ontology in RDF ( http://www.bioontology.org/wiki/index.php/NCBO_REST_services#RDF_Term_Service and http://www.bioontology.org/wiki/index.php/NCBO_REST_services#RDF_Download_Service )
* Notes - Ability to archive Notes, e.g. accepted term proposals, and filter from display
* Annotator
** Updated ontology content
** Offsets corrected for non-ASCII characters
** Link to Annotator Web interface using parameters
** Web interface enhancements
* Display of ontology development status
* Hyperlinks on term details page
* Ability to add comments on Mappings

(Release date February 2011)

== BioPortal Release 2.5 ==
New features in this release include the following:
* Support for structured notes and term requests: Users can now use BioPortal to request that content developers add new terms or update other ontology content. BioPortal provides a structured template for making such requests, allowing users to suggest preferred names, synonyms, and definitions for the requested terms. BioPortal stores the requests as structured notes that are attached to the ontology and that other ontology tools, such as Protégé, will be able to use.

* Support for email notifications to interested parties whenever a BioPortal user creates new notes for an ontology of interest. (If you would like to subscribe to notifications about a particular ontology, please send email to support at bioontology.org. We will have an interactive form to sign-up for notifications shortly.)

* Prototype Web services to generate RDF representation for terms in ontologies in BioPortal (see documentation [1] for details).

* Prototype end-point for SPARQL access to all ontologies in BioPortal: http://sparql.bioontology.org

* Web services for retrieving instance information for OWL ontologies [1]. We are planning to release a user interface for viewing instances shortly.

* New ontology widgets that developers can embed on their Web sites, including an ontology tree widget that allows Web-site authors to present a display of an ontology or an ontology subtree for any BioPortal ontology in any Web page.

* Preview release of Bio-Mixer, a mashup tool that provides extremely flexible browsing and exploration of ontologies and their mappings

[1] http://www.bioontology.org/wiki/index.php/NCBO_REST_services

(Release date June 9, 2010)

Virtual Appliance FAQ

2014-07-07T17:50:07Z

Palexand: /* How can I process a UMLS ontology? */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the root 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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 a 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-06-27T18:46:07Z

Palexand:

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the root 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
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 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-05-10T00:04:23Z

Palexand:

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 delete an ontology? ==
Deleting can be done using a console after logging into the Appliance as the root 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 currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-03-11T22:43:11Z

Palexand: /* How can I use the Appliance on Amazon EC2? */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

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

* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Importing UMLS To Virtual Appliance

2014-03-05T19:05:22Z

Palexand: Created page with "Category:NCBO Virtual Appliance <p>The NCBO Virtual Appliance supports [http://www.geneontology.org/GO.format.obo-1_2.shtml OBO] and [http://www.w3.org/TR/owl-features/ O..."

[[Category:NCBO Virtual Appliance]]

<p>The NCBO Virtual Appliance supports [http://www.geneontology.org/GO.format.obo-1_2.shtml OBO] and [http://www.w3.org/TR/owl-features/ OWL] ontology formats but not UMLS in its native form. To bridge this gap, we have developed a project called [https://github.com/ncbo/umls2rdf/ UMLS2RDF] that transforms UMLS ontologies into OWL/RDF.</p>

<p>UMLS2RDF is a Python script that connects to a UMLS MySQL installation and extracts the UMLS ontologies in a format that the Appliance can work with.</p>

<h3>Install UMLS MySQL</h3>

<p>To import UMLS ontologies, a local installation of the [http://www.nlm.nih.gov/research/umls/implementation_resources/scripts/index.html UMLS MySQL release] needs to be available. Please refer to the [http://www.nlm.nih.gov/research/umls/new_users/index.html UMLS documentation] for instructions on how to install the UMLS MySQL distribution.</p>

<h3>Install UMLS2RDF</h3>

<ol>
<li>First clone the github project:<br/><code>git clone https://github.com/ncbo/umls2rdf/</code></li>
<li>Install the MySQL Python driver. We recommend to use <code>pip</code> for this:<br/><code>pip install MySQL-python</code></li>
</ol>

<h3>Configure UMLS2RDF</h3>

<p>UMLS2RDF has two configuration files:</p>

<ol>
<li><strong>conf.py</strong> where the database configuration (host,name,user and password) needs to be specified. Also the output folder.</li>
<li><strong>umls.conf</strong> where one can specified the UMLS ontologies to be extracted. This is a comma separated file with the following 4 fields:
<ol type="a">
<li>SAB</li>
<li>This is legacy. Any value works.</li>
<li>Output file name.</li>
<li>Conversion strategy. Accepted values (load_on_codes, load_on_cuis).</li>
</ol>
</li>
</ol>

<p>With <em>load_on_codes</em> the original source of the ontology will be used as strategy. The Class IDs will be constructed with the MRCONSO.CODE field. If <em>load_on_cuis</em> is selected then the strategy to transform the ontology will use CUIs to construct the Class IDs.</p>

<p>In our [https://github.com/ncbo/umls2rdf/blob/master/umls.conf configuration file], you can see the settings used by our production system. These are all the UMLS ontologies that are publicly available in BioPortal.</p>

<h3>Run UMLS2RDF</h3>

<p>Once the configuration files have the settings run the command:</p>

<p><code>python umls2rdf.py</code></p>

<p>Depending on how many ontologies are extracted the run time can range from a few minutes to four hours. This process is memory intensive and to transform the largest UMLS ontologies (i.e: SNOMED) one needs at least 16G RAM available.</p>

<h3>Upload files to the NCBO Virtual Appliance</h3>

<p>The output files will be located in the folder specified in <strong>conf.py</strong>. Use the BioPortal Web form available in your appliance to submit the extracted ontologies. <strong>IMPORTANT:</strong> The ontology format in the submission form should be UMLS.</p>

<h3>Hardware Considerations</h3>

<p>NCBO dedicates a fair amount of resources (powerful servers) to handle a good portion of UMLS ontologies. Some of the UMLS ontologies contain millions of classes. To import the largest UMLS ontologies (i.e: RXNORM or SNOMEDCT) Users will have to run the Appliance in a powerful dedicated environment with 8GB RAM and 5GB hard disk space available.</p>

NCBO Widgets

2014-03-05T01:53:55Z

Palexand: /* NCBO Ontology Tree Widget */

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#NCBO Ontology Tree Widget|NCBO Ontology Tree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_acronym_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-NCIT-uri</code> will use NCI Thesaurus (ontology acronym is NCIT) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-NCIT,BIRNLEX-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-NCIT-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{class_id}"</code>
(replace {class_id} with the class id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-NCIT-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "FB-DV";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "NCIT,BIRNLEX";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "NCIT";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<pre>var BP_search_branch = "{class_id}";</pre>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<pre>var BP_include_definitions = true;</pre>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

===Description===
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

===Location===
Add the following files to use the widget:
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree.css
* http://bioportal.bioontology.org/widgets/jquery.ncbo.tree.js
Or the minified versions:
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.min.css
* http://bioportal.bioontology.org/widgets/minified/jquery.ncbo.tree.min.js

===Setup===
* You will need to use jQuery to utilize the Tree Widget. If you aren't using jQuery already, you can add it as follows: <pre><script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script></pre>
* Create a div element to store the tree: <pre><div id="tree"></div></pre>
* Initialize the tree:<pre>var tree = $("#tree").NCBOTree({
 apikey: "YOUR_API_KEY",
 ontology: "NCIT"
});
</pre>
* The div you created should now contain a tree showing the roots of the NCIT ontology
* Additional setup options:
** '''autoclose''': Close other branches of the tree when expanding a new one
** '''treeClass''': Class to identify the tree with
** '''autocompleteClass''': Class to identify the autocomplete (search) input with
** '''width''': Set the width of the tree and autocomplete input
** '''startingClass''': Start with this class selected (and expanded to) in the tree
** '''startingRoot''': Start with this class as the only root displayed in the tree. This allows you to display a sub-tree or branch of your choosing.
** '''ncboAPIURL''': Use a different NCBO REST instance (not normally used)
** '''ncboUIURL''': Use a different NCBO UI instance (not normally used)

===Callbacks and Event Triggers===
You can interact programmatically with the tree using JavaScript and jQuery. Callbacks can be passed when setting up the tree:
<pre>
var tree = $("#tree").NCBOTree({
apikey: "YOUR_API_KEY",
ontology: "NCIT",
afterSelect: function(event, classId, prefLabel, selectedNode){
console.log(classId);
}
});
</pre>
The following are the available callbacks with their arguments:
* '''beforeExpand''', ''arg'': expandedNode
* '''afterExpand''', ''arg'': expandedNode
* '''afterExpandError''', ''arg'': expandedNode
* '''afterSelect''', ''arg'': classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': classId

You can also listen to these as jQuery events:
<pre>
tree.on("afterSelect", function(event, classId, prefLabel, selectedNode) {
console.log(classId);
}
</pre>

Here are the events with their arguments:
* '''beforeExpand''', ''arg'': event, expandedNode
* '''afterExpand''', ''arg'': event, expandedNode
* '''afterExpandError''', ''arg'': event, expandedNode
* '''afterSelect''', ''arg'': event, classId, prefLabel, selectedNode
* '''afterJumpToClass''', ''arg'': event, classId

=== Methods ===
There are a variety of methods you can call on the object returned when calling NCBOTree(). They can be used to get information about the state of the tree or to programmatically interact with it.

* '''tree.selectedClass()''': Returns an object that represents the currently-selected class. The object includes attributes for `id`, `prefLabel`, and `URL`. URL is the REST location of the class, and performing and HTTP GET on that URL will provide a JSON representation of the class.
* '''tree.selectClass(classId)''': Activates the class in the tree with the matching URI (classId). This will only work if the class is already visible.
* '''tree.jumpToClass(classId)''': Replaces the current tree with a version that is expanded with a path from the root to the given class. This method is triggered when selecting a class from the search field. The provided class will be selected in the tree when the tree returns.
* '''tree.changeOntology(ontologyAcronym)''': Replaces the current tree with the roots from the given ontology.

Category:NCBO Virtual Appliance

2014-02-06T19:02:53Z

Palexand: /* Basic System Administration */

== NCBO VIRTUAL APPLIANCE v2.0 IS NOW AVAILABLE ==
The NCBO Virtual Appliance has been updated to use NCBO's new v4.0 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.

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

== Virtual Appliance Basics ==

The NCBO Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source NCBO software running on a Linux operating system. The image was created using VMWare and is available for download by contacting support@bioontology.org.

The following software is included on the image as of v2:
* Ontologies API (REST service)
* Annotator
* Recommender
* BioPortal Web User Interface (including ontology visualization, widgets, and Annotator UI)

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

== Getting Started ==
* To obtain the Virtual Appliance, contact [mailto:support@bioontology.org NCBO Support] and include your BioPortal account username. You can create a BioPortal account at: http://bit.ly/bioportal-account
* The download is provided as a tar 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
** BioPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>
* Add an ontology using the BioPortal Admin User here: http://{YourDomainName}/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://example:8082
** http://example:8082/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
** Hard disk space: 20GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The NCBO 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.5 64-bit running:
*Tomcat 6.0.26
*Solr 4.5.1
*Java 6
*MySQL 5.1.x
*Rails 2.3.x
*Ruby 2.0.0p247
*memcached
*redis 2.6.14
*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, Annotator and Resource Index UIs)
* 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.
* Helper commands:
** <code>bpstart</code>: the required services are started on boot automatically, but if they need to be started automatically
** <code>bpstop</code>: manually stop services
** <code>bprestart</code>: manually start/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 ==
All NCBO software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

Virtual Appliance FAQ

2014-01-29T21:41:00Z

Palexand: /* Ontology Parsing */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_cache_for_submission(logger, submission)
annotator.generate_dictionary_file()
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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? ==
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-f7e8c7b2''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2013.03
* https://aws.amazon.com/amis/ncbo-bioportal-appliance-v1-1
=== Installation Instructions ===
* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-01-29T21:39:07Z

Palexand: /* Ontology Parsing */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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_cache_for_submission(logger, sub)
annotator.generate_dictionary_file()
</pre>

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
logger = Logger.new(STDOUT)
submission.process_submission(logger)
# make available in annotator
annotator = Annotator::Models::NcboAnnotator.new
annotator.create_cache_for_submission(logger, sub)
annotator.generate_dictionary_file()
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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? ==
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-f7e8c7b2''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2013.03
* https://aws.amazon.com/amis/ncbo-bioportal-appliance-v1-1
=== Installation Instructions ===
* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2014-01-28T18:29:08Z

Palexand: /* How do I manually parse an ontology? */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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)
</pre>

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

The BioPortal UI currently lacks the ability to select UMLS as a format. To get around this, add the ontology as OWL, then do the following from the command line after logging into the Appliance:
<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)
submission.bring_remaining
umls = LinkedData::Models::OntologyFormat.find("UMLS").first
submission.hasOntologyLanguage = umls
submission.save
logger = Logger.new(STDOUT)
submission.process_submission(logger)
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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? ==
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-f7e8c7b2''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2013.03
* https://aws.amazon.com/amis/ncbo-bioportal-appliance-v1-1
=== Installation Instructions ===
* Login to AWS Console, go to EC2 and select US West (Oregon) region from the top right corner: https://console.aws.amazon.com/ec2/home?region=us-west-2

* Click on Launch Instances which will bring up Launch Instance Wizard with multiple tabs.

* 1. Choose AMI:
** Select Community AMIs and search of “NCBO Appliance” and choose the latest version
* 2. Choose Instance Type Tab
** Instance Type = General Purpose m1.xlarge (or any other type with at least 4 vCPUs and ~8 GB of RAM)
* 3. Configure Instance Tab
** Availability Zone = No preference
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
* 5. Instance Tags:
** Name = Name this instance something meaningful
* 6. Configure Security Group
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8082 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
Click "Launch"
You will have to create or choose an existing Key Pairs or Create a Key Pair.

* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

NCBO Widgets

2014-01-17T18:19:55Z

Palexand: /* Methods */

NCBO Widgets

2014-01-17T18:17:50Z

Palexand: /* Location */

NCBO Widgets

2014-01-17T17:53:23Z

Palexand: /* NCBO Ontology Tree Widget */

NCBO Widgets

2014-01-15T00:52:01Z

Palexand: /* Term-selection field on a form */

NCBO Widgets

2014-01-15T00:49:23Z

Palexand: /* Ontology search widget */

NCBO Widgets

2014-01-15T00:48:49Z

Palexand: /* Ontology search widget */

NCBO Widgets

2014-01-15T00:47:15Z

Palexand: /* Referencing your ontology of interest in the widgets */

NCBO Widgets

2014-01-15T00:42:14Z

Palexand: /* NCBO Ontology Tree Widget */

NCBO Widgets

2014-01-15T00:11:24Z

Palexand:

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#NCBO Ontology Tree Widget|NCBO Ontology Tree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_id_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-1032-uri</code> will use NCI Thesaurus (ontology id is 1032) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-1032,1089-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-1032-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{conceptid}"</code>
(replace {conceptid} with the term id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-1032-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-1580-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "1016";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "1032,1089";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "1032";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<code>var BP_search_branch = "{conceptid}";</code>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<code>var BP_include_definitions = true;</code>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

'''Description'''<br>
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

'''Location'''<br>
http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf

'''Parameters'''
* '''ontology''' = The id of the ontology to use, by default it assumes this value is the ontology version id
* '''virtual''' [true|false] - If true then the above ontology parameter is assumed to be a virtual ontology id
* '''canchangeontology''' [true|false] = If false then users can't change the current ontology
* '''canchangeroot''' [true|false] = If true the the user can specify a root concept (using the context menu)
* '''rootconceptid''' = The id of the root concept to show in the tree, leave out to show the ontology roots
* '''server''' = The rest server to use. Defaults to "http://rest.bioontology.org/bioportal/".
* '''redirecturl''' = The url to redirect to for terms and ontologies (in BioPortal). Defaults to "http://bioportal.bioontology.org/".
* '''alerterrors''' [true|false] = If true then errors will be displayed in an annoying popup box.
* '''title''' = The title for the browser window

'''Embed Example'''<br>
Using Javascript (preferred):
<pre>
<script src="http://keg.cs.uvic.ca/ncbo/ontologytree/AC_OETags.js" language="javascript"></script>


// Version check for the Flash Player that has the ability to start Player Product Install (6.0r65)
var hasProductInstall = DetectFlashVer(6, 0, 65);

// Version check based upon the values defined in globals
var hasRequestedVersion = DetectFlashVer(requiredMajorVersion, requiredMinorVersion, requiredRevision);

if (hasProductInstall && !hasRequestedVersion) {
// DO NOT MODIFY THE FOLLOWING FOUR LINES
// Location visited after installation is complete if installation is required
var MMPlayerType = (isIE == true) ? "ActiveX": "PlugIn";
var MMredirectURL = window.location;
document.title = document.title.slice(0, 47) + " - Flash Player Installation";
var MMdoctitle = document.title;

AC_FL_RunContent(
"src", "playerProductInstall",
"FlashVars", "MMredirectURL=" + MMredirectURL + '&MMplayerType=' + MMPlayerType + '&MMdoctitle=' + MMdoctitle + "",
"width", "300",
"height", "100%",
"align", "middle",
"id", "OntologyTree",
"quality", "high",
"bgcolor", "#ffffff",
"name", "OntologyTree",
"allowScriptAccess", "always",
"type", "application/x-shockwave-flash",
"pluginspage", "http://www.adobe.com/go/getflashplayer"
);
} else if (hasRequestedVersion) {
// if we've detected an acceptable version
// embed the Flash Content SWF when all tests are passed
AC_FL_RunContent(
"src", "http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf",
"width", "300",
"height", "100%",
"align", "middle",
"id", "OntologyTree",
"quality", "high",
"bgcolor", "#ffffff",
"name", "OntologyTree",
"allowScriptAccess", "always",
"flashVars", "ontology=&virtual=false&alerterrors=false&canchangeontology=true&rootconceptid=",
"type", "application/x-shockwave-flash",
"pluginspage", "http://www.adobe.com/go/getflashplayer"
);
} else {
// flash is too old or we can't detect the plugin
var alternateContent = 'Alternate HTML content should be placed here. '
+ 'This content requires the Adobe Flash Player. '
+ '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>';
document.write(alternateContent);
// insert non-flash content
}
</pre>

Using HTML:
<pre>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="OntologyTree" width="300" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<param name="allowScriptAccess" value="always" />
<param name="flashVars" value="ontology=&alerterrors=false&canchangeontology=true" />
<embed src="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" quality="high" bgcolor="#ffffff"
width="300" height="100%" name="OntologyTree" align="middle"
play="true"
loop="false"
allowScriptAccess="always"
type="application/x-shockwave-flash"
flashVars="ontology=&alerterrors=false&canchangeontology=true"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>
</pre>

Using GWT:
* See http://code.google.com/p/gwt2swf/ for information on how to embed SWF in GWT.

'''Javascript API Calls'''<br>
You will need to copy/paste this code to a Javascript file or embed directly in the HTML for usage in your page.<br>
<pre>
/*
* The following JavaScript functions allow you to interact with the Flash BioPortal Ontology Tree.
* You can load an ontology by id, and get the current ontology id or name.
* Once an ontology is loaded then you can get the currently selected concept by id or name,
* and you can also select a concept by id or name.
* You can also listen for one of these events by implementing the following functions (see the stubs below):
* appComplete, treeSelectionChanged, treeNodeDoubleClicked, or errorLoadingOntology
*
* These are the parameters that you can pass into the application using the "flashVars" parameter:
* (see the examples below):
* - ontology: the id of the ontology (version or virtual)
* - virtual: if false (default) then the ontology id above is the version id
* if true then the above ontology id is assumed to be the virtual id
* - alerterrors: (true/false) determines whether the application will display errors (default is false)
* - server: defines the URL of the rest server (null by default)
* - title: changes the default title for the page
* - canchangeontology: if true then the ontology can be changed
* - rootconceptid: sets the optional root node of the tree
* - canchangeroot: if false then the root of the tree cannot be changed by the user (using context menu items)
*/

// get a handle for the flash application
function getApp() {
if (navigator.appName.indexOf ("Microsoft") != -1) {
app = window["OntologyTree"];
} else {
app = document["OntologyTree"];
}
if (app == null) {
app = document.getElementById("OntologyTree");
}
if (app == null) {
alert("Could not get Flash object, JavaScript/Flex communication failed.");
}
return app;
}

// these are the available functions that you can call ONCE the
// flash SWF has finished loading

/** Loads a new ontology by id. */
function loadOntology(ontologyID) {
var app = getApp();
if (app && app.loadOntology) {
app.loadOntology(ontologyID);
}
}

/** Gets the id of the current ontology, will be null if no ontology is loaded. */
function getOntologyID() {
var ontologyID = null;
var app = getApp();
if (app && app.getOntologyID) {
ontologyID = app.getOntologyID();
}
return ontologyID;
}

/** Gets the name of the current ontology, will be null if no ontology is loaded. */
function getOntologyName() {
var ontologyName = null;
var app = getApp();
if (app && app.getOntologyName) {
ontologyName = app.getOntologyName();
}
return ontologyName;
}

/** Gets the id of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptID() {
var conceptID = null;
var app = getApp();
if (app && app.getSelectedConceptID) {
conceptID = app.getSelectedConceptID();
}
return conceptID;
}

/**
* Gets the full id (not all ontologies support this) of the currently selected concept.
* Will be null if nothing is selected, will be the same as the conceptID if no fullID exists.
*/
function getSelectedConceptFullID() {
var conceptID = null;
var app = getApp();
if (app && app.getSelectedConceptFullID) {
conceptID = app.getSelectedConceptFullID();
}
return conceptID;
}

/** Gets the name of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptName() {
var conceptName = null;
var app = getApp();
if (app && app.getSelectedConceptName) {
conceptName = app.getSelectedConceptName();
}
return conceptName;
}

/** Loads and selects a concept (by id) in the current ontology. */
function loadConceptByID(conceptID) {
var app = getApp();
if (app && app.loadConceptByID) {
app.loadConceptByID(conceptID);
}
}

/** Attempts to load and select a concept (by name) in the current ontology. */
function loadConceptByName(conceptName) {
var app = getApp();
if (app && app.loadConceptByName) {
app.loadConceptByName(conceptName);
}
}

/** This function gets call by flash when the swf has finished loading. */
function appComplete(swfID) {
// alert("flash app finished loading: " + swfID);
}

/** Implement this function to listen for tree selection changes */
function treeSelectionChanged(nodeID, nodeName, swfID) {
// alert("tree selection: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for tree double click events */
function treeNodeDoubleClicked(nodeID, nodeName, swfID) {
alert("tree node double clicked: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for error messages when loading an ontology */
function errorLoadingOntology(errorMsg, swfID) {
// alert("Error: " + errorMsg);
}
</pre>

= Referencing your ontology of interest in the widgets =

Most of the time you would want your widget to use the latest version of your ontology of interest that is available in BioPortal. Thus, you would want to use the ontology id and not the version is in your widget. To find the ontology id, go to the "Ontology Details" page for your ontology of interest in BioPortal (e.g., the page for [http://bioportal.bioontology.org/ontologies/39478 NCI Thesaurus]). You will find the ontology id on the Metadata tab there (e.g., the ontology id for NCI Thesaurus is 1032).

NCBO Widgets

2014-01-15T00:10:12Z

Palexand: Modify visualization widget instructions

NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use BioPortal functionality there. Using NCBO Widgets is just one of [[Using_NCBO_Technology_In_Your_Project|the ways in which you can use the NCBO technology directly on your Web site or in your application]].

= Types of NCBO Widgets and use cases =
* '''[[#Term-selection field on a form|Term-selection field on a form]]''': You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single ontology)
** ''Example use case'': Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "cutaneous me", the term "cutaneous melanoma" pops up.
** ''What does the term-selection field get you'':
*** Look-ahead so that you don't need to type the whole term
*** Controlled vocabulary provides consistency of the way different users use the term (If you want to put "Malignant melanoma", it will always be the same term from NCIT, regardless of how a user started typing it
*** When a new version of your controlled vocabulary becomes available in BioPortal, the widget will automatically use that new version.
*'''[[#Ontology search widget|Ontology search widget]]''': You can add to your Web site a search box that searches a specific BioPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the BioPortal page for the corresponding concept in BioPortal.
*'''[[#Ontology visualization widget|Ontology visualization widget]]''': You can put a widget on your Web site that visualizes your entire ontology of interest, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].
*'''[[#OntologyTree Widget|OntologyTree Widget]]''': You can put a widget on your Web site that displays the ontology tree, or some part of it, as on the [http://bioportal.bioontology.org/visualize/39478#t_tab1: "Visualize" tab in BioPortal].

= How to use NCBO Widgets=

The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
* Find your ontology of interest in the [http://bioportal.bioontology.org/ontologies list of BioPortal ontologies] (e.g., NCI Thesaurus)
* Click on the ontology name to get to the page with '''Details''' for that ontology (e.g., the [http://bioportal.bioontology.org/ontologies/39478 Details for NCI Thesaurus])
* On the Ontology Details page, go to '''Ontology Widgets''' tab
* Select the widget you want
* Click the button below the widgets to get instructions for the specific widget

== Term-selection field on a form ==

To add a field to your form that lets the user fetch a term from your ontology of interest, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/form_complete.js <b>form_complete.js file</b>] and put it on your server
</li>
<li>In the header for the page where you want the form field, include the <b>form_complete.js</b> file
</li>
<li>On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format: <code>bp_form_complete-{ontology_id_list}-{value}</code>
<ul>
<li>For example, <code>bp_form_complete-1032-uri</code> will use NCI Thesaurus (ontology id is 1032) and will put the term URI in the field after the user selects the term from the pull-down list.
<ul>
<li>
<b>Note:</b> In addition to single ontology ids, you can use a list:<br>
<code>bp_form_complete-1032,1089-uri</code>
</li>
<li>
<b>OR</b> use 'all' to search across all BioPortal ontologies:<br>
<code>bp_form_complete-all-uri</code>
</li>
</ul>
</li>
<li>You can use the following parameters to select which value will be placed into the user-visible input field:
<ul>
<li>
<code>uri</code> : put the complete URI of the term (e.g., "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Common_Neoplasm");
</li>
<li>
<code>shortid</code> : put the short id of the term, as used in BioPortal (e.g., "Common_Neoplasm");
</li>
<li>
<code>name</code> : put the preferred name of the term (e.g., "Common Neoplasm");
</li>
</ul>
</li>
</ul>

==== Hidden form elements auto-generated ====
In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<pre>
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>
</pre>
The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<pre>
<input type="hidden" id="a_bioportal_preferred_name">
<input type="hidden" id="a_bioportal_concept_id">
<input type="hidden" id="a_bioportal_ontology_id">
<input type="hidden" id="a_bioportal_full_id">
</pre>

==== Optional attributes ====
<ul>
<li>
<strong>Include term definitions.</strong>
Use <code>data-bp_include_definitions="true"</code>.
This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with
definitions, in the NCI Thesaurus.
<br/>
<code><input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-1032-name"/></code>
</li>
<li>
<strong>Limit lookup to terms below a root term.</strong>
Use <code>data-bp_search_branch="{conceptid}"</code>
(replace {conceptid} with the term id for the term to use as the
branch root). For example, use this code to limit the search for 'heart' to terms
within the 'Anatomic_Structure_System_or_Substance'
branch of the NCI Thesaurus.
<br/>
<code><input type="text" name="n" data-bp_search_branch="Anatomic_Structure_System_or_Substance" class="bp_form_complete-1032-name"/></code>
</li>

<li><strong>Object types</strong>
<ul>

<li>
<strong>Search 'class' and 'property' objects.</strong>
Use <code>data-bp_objecttypes="class,property".</code>
For example, use this code to search for 'function' among both 'class' and
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Search only 'property' objects.</strong>
Use <code>data-bp_objecttypes="property".</code>
For example, use this code to search for 'function' among only
'property' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Search 'class' and 'individual' objects.</strong>
Use <code>data-bp_objecttypes="class,individual".</code>
For example, use this code to search for 'seizure' among 'class' and
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-1580-uri"/></code>
</li>
<li>
<strong>Only search 'individual' objects.</strong>
Use <code>data-bp_objecttypes="individual".</code>
For example, use this code to this search for 'seizure' only among
'individual' objects from the "Adverse Event Reporting Ontology".
<br/>
<code><input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-1580-uri"/></code>
</li>
</ul>
</ul>

</ul>

== Ontology search widget ==

To add a search widget to your HTML page that searches a specific ontology, do the following:
<ul>
<li>Download the [http://bioportal.bioontology.org/javascripts/widgets/quick_jump.js <b>quick_jump.js file</b>] and put it on your server
</li>
<li>Copy the code below and paste it to your HTML page.
<pre>
<div id="bp_quick_jump"></div>
<script type="text/javascript">
var BP_ontology_id = "1016";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8">
</script>
</pre>
</li>
<li>
<b>Note:</b> If you would like to use Quick Jump across multiple ontologies:
<ul>
<li>You can enter a comma-separated list of ontology ids:<br>
var BP_ontology_id = "1032,1089";
</li>
<li>You cans set the variable to 'all' to search all ontologies in BioPortal:<br>
var BP_ontology_id = "all";
</li>
</ul>
</li>
<li>In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file)
<ul>
<li>For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<pre>
<script type="text/javascript">
var BP_ontology_id = "1032";
</script>
<script src="quick_jump.js" type="text/javascript" charset="utf-8"></script>
</pre>
</li>
</ul>
</li>
<li>
To limit the term lookup to a particular branch of an ontology, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
<code>var BP_search_branch = "{conceptid}";</code>
</li>
<li>
To display definitions with the list of terms that are returned, include the following Javascript in your page:
<code>var BP_include_definitions = true;</code>
</li>
</ul>

== Ontology visualization widget ==
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your ontology of interest. Here is a sample:

<pre>
<iframe src="http://bioportal.bioontology.org/widgets/visualization?
ontology=NCIT
&class=http%3A%2F%2Fncicb.nci.nih.gov%2Fxml%2Fowl%2FEVS%2FThesaurus.owl%23C38999
&apikey=YOUR_API_KEY"
frameborder="0">
</iframe>
</pre>

== NCBO Ontology Tree Widget ==

'''Description'''<br>
The OntologyTree widget is an embeddable Flex application that allows a user to interact with a tree browser for ontologies. The widget can be configured to display a list of all the ontologies in BioPortal, allowing the user to select which one to view, or can be setup to view a particular ontology. Additionally, there are several Javascript helper functions for the widget, allowing it to be utilized as a fully functional component in other applications.

'''Location'''<br>
http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf

'''Parameters'''
* '''ontology''' = The id of the ontology to use, by default it assumes this value is the ontology version id
* '''virtual''' [true|false] - If true then the above ontology parameter is assumed to be a virtual ontology id
* '''canchangeontology''' [true|false] = If false then users can't change the current ontology
* '''canchangeroot''' [true|false] = If true the the user can specify a root concept (using the context menu)
* '''rootconceptid''' = The id of the root concept to show in the tree, leave out to show the ontology roots
* '''server''' = The rest server to use. Defaults to "http://rest.bioontology.org/bioportal/".
* '''redirecturl''' = The url to redirect to for terms and ontologies (in BioPortal). Defaults to "http://bioportal.bioontology.org/".
* '''alerterrors''' [true|false] = If true then errors will be displayed in an annoying popup box.
* '''title''' = The title for the browser window

'''Embed Example'''<br>
Using Javascript (preferred):
<pre>
<script src="http://keg.cs.uvic.ca/ncbo/ontologytree/AC_OETags.js" language="javascript"></script>


// Version check for the Flash Player that has the ability to start Player Product Install (6.0r65)
var hasProductInstall = DetectFlashVer(6, 0, 65);

// Version check based upon the values defined in globals
var hasRequestedVersion = DetectFlashVer(requiredMajorVersion, requiredMinorVersion, requiredRevision);

if (hasProductInstall && !hasRequestedVersion) {
// DO NOT MODIFY THE FOLLOWING FOUR LINES
// Location visited after installation is complete if installation is required
var MMPlayerType = (isIE == true) ? "ActiveX": "PlugIn";
var MMredirectURL = window.location;
document.title = document.title.slice(0, 47) + " - Flash Player Installation";
var MMdoctitle = document.title;

AC_FL_RunContent(
"src", "playerProductInstall",
"FlashVars", "MMredirectURL=" + MMredirectURL + '&MMplayerType=' + MMPlayerType + '&MMdoctitle=' + MMdoctitle + "",
"width", "300",
"height", "100%",
"align", "middle",
"id", "OntologyTree",
"quality", "high",
"bgcolor", "#ffffff",
"name", "OntologyTree",
"allowScriptAccess", "always",
"type", "application/x-shockwave-flash",
"pluginspage", "http://www.adobe.com/go/getflashplayer"
);
} else if (hasRequestedVersion) {
// if we've detected an acceptable version
// embed the Flash Content SWF when all tests are passed
AC_FL_RunContent(
"src", "http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf",
"width", "300",
"height", "100%",
"align", "middle",
"id", "OntologyTree",
"quality", "high",
"bgcolor", "#ffffff",
"name", "OntologyTree",
"allowScriptAccess", "always",
"flashVars", "ontology=&virtual=false&alerterrors=false&canchangeontology=true&rootconceptid=",
"type", "application/x-shockwave-flash",
"pluginspage", "http://www.adobe.com/go/getflashplayer"
);
} else {
// flash is too old or we can't detect the plugin
var alternateContent = 'Alternate HTML content should be placed here. '
+ 'This content requires the Adobe Flash Player. '
+ '<a href=http://www.adobe.com/go/getflash/>Get Flash</a>';
document.write(alternateContent);
// insert non-flash content
}
</pre>

Using HTML:
<pre>
<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
id="OntologyTree" width="300" height="100%"
codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
<param name="movie" value="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" />
<param name="quality" value="high" />
<param name="bgcolor" value="#ffffff" />
<param name="allowScriptAccess" value="always" />
<param name="flashVars" value="ontology=&alerterrors=false&canchangeontology=true" />
<embed src="http://keg.cs.uvic.ca/ncbo/ontologytree/OntologyTree.swf" quality="high" bgcolor="#ffffff"
width="300" height="100%" name="OntologyTree" align="middle"
play="true"
loop="false"
allowScriptAccess="always"
type="application/x-shockwave-flash"
flashVars="ontology=&alerterrors=false&canchangeontology=true"
pluginspage="http://www.adobe.com/go/getflashplayer">
</embed>
</object>
</pre>

Using GWT:
* See http://code.google.com/p/gwt2swf/ for information on how to embed SWF in GWT.

'''Javascript API Calls'''<br>
You will need to copy/paste this code to a Javascript file or embed directly in the HTML for usage in your page.<br>
<pre>
/*
* The following JavaScript functions allow you to interact with the Flash BioPortal Ontology Tree.
* You can load an ontology by id, and get the current ontology id or name.
* Once an ontology is loaded then you can get the currently selected concept by id or name,
* and you can also select a concept by id or name.
* You can also listen for one of these events by implementing the following functions (see the stubs below):
* appComplete, treeSelectionChanged, treeNodeDoubleClicked, or errorLoadingOntology
*
* These are the parameters that you can pass into the application using the "flashVars" parameter:
* (see the examples below):
* - ontology: the id of the ontology (version or virtual)
* - virtual: if false (default) then the ontology id above is the version id
* if true then the above ontology id is assumed to be the virtual id
* - alerterrors: (true/false) determines whether the application will display errors (default is false)
* - server: defines the URL of the rest server (null by default)
* - title: changes the default title for the page
* - canchangeontology: if true then the ontology can be changed
* - rootconceptid: sets the optional root node of the tree
* - canchangeroot: if false then the root of the tree cannot be changed by the user (using context menu items)
*/

// get a handle for the flash application
function getApp() {
if (navigator.appName.indexOf ("Microsoft") != -1) {
app = window["OntologyTree"];
} else {
app = document["OntologyTree"];
}
if (app == null) {
app = document.getElementById("OntologyTree");
}
if (app == null) {
alert("Could not get Flash object, JavaScript/Flex communication failed.");
}
return app;
}

// these are the available functions that you can call ONCE the
// flash SWF has finished loading

/** Loads a new ontology by id. */
function loadOntology(ontologyID) {
var app = getApp();
if (app && app.loadOntology) {
app.loadOntology(ontologyID);
}
}

/** Gets the id of the current ontology, will be null if no ontology is loaded. */
function getOntologyID() {
var ontologyID = null;
var app = getApp();
if (app && app.getOntologyID) {
ontologyID = app.getOntologyID();
}
return ontologyID;
}

/** Gets the name of the current ontology, will be null if no ontology is loaded. */
function getOntologyName() {
var ontologyName = null;
var app = getApp();
if (app && app.getOntologyName) {
ontologyName = app.getOntologyName();
}
return ontologyName;
}

/** Gets the id of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptID() {
var conceptID = null;
var app = getApp();
if (app && app.getSelectedConceptID) {
conceptID = app.getSelectedConceptID();
}
return conceptID;
}

/**
* Gets the full id (not all ontologies support this) of the currently selected concept.
* Will be null if nothing is selected, will be the same as the conceptID if no fullID exists.
*/
function getSelectedConceptFullID() {
var conceptID = null;
var app = getApp();
if (app && app.getSelectedConceptFullID) {
conceptID = app.getSelectedConceptFullID();
}
return conceptID;
}

/** Gets the name of the currently selected concept, will be null if nothing is selected. */
function getSelectedConceptName() {
var conceptName = null;
var app = getApp();
if (app && app.getSelectedConceptName) {
conceptName = app.getSelectedConceptName();
}
return conceptName;
}

/** Loads and selects a concept (by id) in the current ontology. */
function loadConceptByID(conceptID) {
var app = getApp();
if (app && app.loadConceptByID) {
app.loadConceptByID(conceptID);
}
}

/** Attempts to load and select a concept (by name) in the current ontology. */
function loadConceptByName(conceptName) {
var app = getApp();
if (app && app.loadConceptByName) {
app.loadConceptByName(conceptName);
}
}

/** This function gets call by flash when the swf has finished loading. */
function appComplete(swfID) {
// alert("flash app finished loading: " + swfID);
}

/** Implement this function to listen for tree selection changes */
function treeSelectionChanged(nodeID, nodeName, swfID) {
// alert("tree selection: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for tree double click events */
function treeNodeDoubleClicked(nodeID, nodeName, swfID) {
alert("tree node double clicked: " + nodeID + " - " + nodeName + " - " + swfID);
}

/** Implement this function to listen for error messages when loading an ontology */
function errorLoadingOntology(errorMsg, swfID) {
// alert("Error: " + errorMsg);
}
</pre>

= Referencing your ontology of interest in the widgets =

Most of the time you would want your widget to use the latest version of your ontology of interest that is available in BioPortal. Thus, you would want to use the ontology id and not the version is in your widget. To find the ontology id, go to the "Ontology Details" page for your ontology of interest in BioPortal (e.g., the page for [http://bioportal.bioontology.org/ontologies/39478 NCI Thesaurus]). You will find the ontology id on the Metadata tab there (e.g., the ontology id for NCI Thesaurus is 1032).

Virtual Appliance FAQ

2014-01-08T18:02:49Z

Palexand: /* How do I manually parse an ontology? */

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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)
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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? ==
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-f7e8c7b2''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2013.03
* https://aws.amazon.com/amis/ncbo-bioportal-appliance-v1-1
=== Installation Instructions ===
* Login to AWS Console: https://console.aws.amazon.com/ec2/home?region=us-west-1
* Click on Instances → Launch Instance → Classic Wizard → Community AMIs → Choose an AMI:
** Search for “NCBO Appliance” and choose the latest version
** Click '''Continue'''
* Instance Details:
** Instance Type = m1.large (or any other type with at least 2 cores and ~8 GB of RAM)
** Availability Zone = No preference
** Click '''Continue'''
* Advanced Instance Options:
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
** Click '''Continue'''
* Instance Tags:
** Name = Name this instance something meaningful
** Click '''Continue'''
* Key Pairs:
** Choose from your Existing Key Pairs or Create a Key Pair
** Click '''Continue'''
* Configure Firewall:
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8080 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
** Click '''Continue'''
* Review Instance Details:
** Make sure your settings are correct
** Click '''Launch'''
** Click '''Close'''
* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Virtual Appliance FAQ

2013-12-03T20:56:13Z

Palexand: Update documentation to Appliance v2.0

[[Category:NCBO Virtual Appliance]]

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

= Ontology Management =

== How do I add or change categories or groups? ==
There is currently no UI administrator interface (though this will likely be added in future versions). Categories and groups can be added using a console after logging into the Appliance as the root 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 can I migrate ontologies from BioPortal or previous NCBO Virtual Appliance versions into a new Appliance? ==
Programmatic migrations are currently unsupported. Ontologies can be manually downloaded and added using the Web UI.

= 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:
<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)
submission.process_submission
</pre>

== 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://example: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://example/admin and click the "Flush Memcache" button. There should be a response indicating success or failure.

== How can I use widgets with my Virtual Appliance? ==
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? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> ==

=== 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? ==
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-f7e8c7b2''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2013.03
* https://aws.amazon.com/amis/ncbo-bioportal-appliance-v1-1
=== Installation Instructions ===
* Login to AWS Console: https://console.aws.amazon.com/ec2/home?region=us-west-1
* Click on Instances → Launch Instance → Classic Wizard → Community AMIs → Choose an AMI:
** Search for “NCBO Appliance” and choose the latest version
** Click '''Continue'''
* Instance Details:
** Instance Type = m1.large (or any other type with at least 2 cores and ~8 GB of RAM)
** Availability Zone = No preference
** Click '''Continue'''
* Advanced Instance Options:
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
** Click '''Continue'''
* Instance Tags:
** Name = Name this instance something meaningful
** Click '''Continue'''
* Key Pairs:
** Choose from your Existing Key Pairs or Create a Key Pair
** Click '''Continue'''
* Configure Firewall:
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8080 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
** Click '''Continue'''
* Review Instance Details:
** Make sure your settings are correct
** Click '''Launch'''
** Click '''Close'''
* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Category:NCBO Virtual Appliance

2013-12-03T20:26:42Z

Palexand: Update documentation to Appliance v2.0

== NCBO VIRTUAL APPLIANCE v2.0 IS NOW AVAILABLE ==
The NCBO Virtual Appliance has been updated to use NCBO's new v4.0 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.

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

== Virtual Appliance Basics ==

The NCBO Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source NCBO software running on a Linux operating system. The image was created using VMWare and is available for download by contacting support@bioontology.org.

The following software is included on the image as of v2:
* Ontologies API (REST service)
* Annotator
* Recommender
* BioPortal Web User Interface (including ontology visualization, widgets, and Annotator UI)

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

== Getting Started ==
* To obtain the Virtual Appliance, contact [mailto:support@bioontology.org NCBO Support] and include your BioPortal account username. You can create a BioPortal account at: http://bit.ly/bioportal-account
* The download is provided as a tar 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
** BioPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>
* Add an ontology using the BioPortal Admin User here: http://{YourDomainName}/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://example:8080
** http://example: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
** 1 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 3GB

* Recommended for heavier usage
** 2 CPU (3 GHz)
** 6GB RAM (When using more than 4GB RAM, you should configure Tomcat to use the additional memory)
** Hard disk space: 10GB (or more depending on number/size of ontologies)

== Image Format and Operating System Details ==
The NCBO 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 5.7 64-bit running Tomcat 6.0.26, Java 6, MySQL 5.1.x, PHP 5.1.6, Rails 2.3.x, and Ruby Enterprise Edition 1.8.7, and memcached.

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, Annotator and Resource Index UIs)
* 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.
* Helper commands:
** <code>ncbostart</code>: the required services are started on boot automatically, but if they need to be started automatically
** <code>ncbostop</code>: manually stop services
** <code>ncborestart</code>: manually start/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 4store 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 4store stop</code>

== License ==
All NCBO software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

BioPortal REST services

2013-10-15T19:02:34Z

Palexand:

<div style="background-color: #FA6B6B; color: white; clear: both; padding: 2em; margin: 1em;">
<h1>WARNING</h1>
<p>The REST endpoints documented here are <b>DEPRECATED</b></p>
<p>New NCBO BioPortal v4.0 REST services are documented here: http://data.bioontology.org/documentation</p>
<p>Data in REST services located at rest.bioontology.org will not be updated and eventually these services will be disabled</p>
</div>

__TOC__

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use. See also work on wrapping Bioportal REST services as a [[CTS2_BioPortal_wrapper]].

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.
Ontology files that were successfully parsed have a value of 3 for the <statusId> attribute in the XML response.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}/{concept id}&apikey={YourAPIKey}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}?conceptid={uri-encoded concept id}
** To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

Examples using Alt Signature
* http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

Examples using Alt Virtual Signature (uses ontology id and uri-encoded concept id)
* http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FICD10%2FO80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/C3224?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3262?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3224?apikey=YourAPIKey
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

BioPortal REST services

2013-10-15T19:01:59Z

Palexand:

<div style="background-color: #FA6B6B; color: white; clear: both; padding: 2em; margin: 1em;">
<h1>WARNING</h1>
<p>The REST endpoints documented here are <b>DEPRECATED</b></p>
<p>New NCBO BioPortal v4.0 REST services are documented here: http://data.bioontology.org/documentation</p>
<p>Data in REST services located at rest.bioontology.org is not being updated and eventually these services will be disabled</p>
</div>

__TOC__

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use. See also work on wrapping Bioportal REST services as a [[CTS2_BioPortal_wrapper]].

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.
Ontology files that were successfully parsed have a value of 3 for the <statusId> attribute in the XML response.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}/{concept id}&apikey={YourAPIKey}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}?conceptid={uri-encoded concept id}
** To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

Examples using Alt Signature
* http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

Examples using Alt Virtual Signature (uses ontology id and uri-encoded concept id)
* http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FICD10%2FO80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/C3224?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3262?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3224?apikey=YourAPIKey
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

BioPortal REST services

2013-10-15T19:00:18Z

Palexand:

<div> </div>
<div style="background-color: #FA6B6B; color: white; clear: both; padding: 2em; float: right;">
<h1>WARNING</h1>
<p>The REST endpoints documented here are <b>DEPRECATED</b></p>
<p>New NCBO BioPortal v4.0 REST services are documented here: http://data.bioontology.org/documentation</p>
<p>Data in REST services located at rest.bioontology.org is not being updated and eventually these services will be disabled</p>
</div>

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use. See also work on wrapping Bioportal REST services as a [[CTS2_BioPortal_wrapper]].

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.
Ontology files that were successfully parsed have a value of 3 for the <statusId> attribute in the XML response.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}/{concept id}&apikey={YourAPIKey}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology id}?conceptid={uri-encoded concept id}
** To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

Examples using Alt Signature
* http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

Examples using Alt Virtual Signature (uses ontology id and uri-encoded concept id)
* http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FICD10%2FO80-O84.9&apikey=YourAPIKey
* http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/C3224?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3262?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/C3224?apikey=YourAPIKey
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

Modifying BioPortal Web UI

2013-05-21T01:31:18Z

Palexand:

[[Category:NCBO Virtual Appliance]]

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

Modifying BioPortal Web UI

2013-05-21T01:31:02Z

Palexand: /* Modifying BioPortal Web UI */

Modifying BioPortal Web UI

2013-05-20T23:09:44Z

Palexand: Created page with "Category:NCBO Virtual Appliance = Modifying BioPortal Web UI = The BioPortal Web UI is primarily built using Ruby on Rails, which is an MVC framework built for the web. ..."

[[Category:NCBO Virtual Appliance]]

= Modifying BioPortal Web UI =

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

Virtual Appliance FAQ

2013-05-20T22:25:50Z

Palexand:

[[Category:NCBO Virtual Appliance]]

= Ontology Management =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

= Systems Administration =

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

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

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

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

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

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

This example is for the Tree Browser.

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

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

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

= How can I use the OVF image with my virtualization software? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> =

== 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? =
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-5187dd14''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2012.03

=== Installation Instructions ===
* Login to AWS Console: https://console.aws.amazon.com/ec2/home?region=us-west-1
* Click on Instances → Launch Instance → Classic Wizard → Community AMIs → Choose an AMI:
** Search for “NCBO Appliance” and choose the latest version
** Click '''Continue'''
* Instance Details:
** Instance Type = m1.large (or any other type with at least 2 cores and ~8 GB of RAM)
** Availability Zone = No preference
** Click '''Continue'''
* Advanced Instance Options:
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
** Click '''Continue'''
* Instance Tags:
** Name = Name this instance something meaningful
** Click '''Continue'''
* Key Pairs:
** Choose from your Existing Key Pairs or Create a Key Pair
** Click '''Continue'''
* Configure Firewall:
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8080 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
** Click '''Continue'''
* Review Instance Details:
** Make sure your settings are correct
** Click '''Launch'''
** Click '''Close'''
* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Annotator Dataset Workflow Howto

2013-04-03T19:12:27Z

Palexand: /* Create Dictionary File */

== Introduction ==

Once you have submitted some ontologies into the BioPortal Ontology Services (BioPortal Core), you can use these to populate the backend data sets required by the Annotator Web Service. These datasets are collectively referred to as the Annotator datasets and comprise: The hierarchy database (formerly known as "OBS"), a dictionary file, and (optionally) a mapping database. The population process uses classes, terms, relations, and semantic types from the ontologies. The population is done in two major steps: 1) Synchronize the hierarchy database with BioPortal Core and 2) Create the dictionary file for use with MGREP. A third step, populating mapping information, should be done if there are mappings available.

== Synchronize Hierarchy Database with Ontology Services ==

<p><font color="red"><b>Note:</b></font> All NCBO REST Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. As a result, the "ObsApiKey" parameter should now be appended to all the OBS worklflow execution urls.</p>
The ontologies and related data that will be used by the Annotator are gathered from the Ontology Services (part of BioPortal Core). This process should be run any time a new ontology (or a new version of an existing ontology) is added to the Ontology Services, though it could theoretically be run from a cron script or scheduled job.

<ol>
<li>Remove out-dated ontologies from hierarchy database (e.g. older version of ontologies that does not in BioPortal anymore). By invoking this restlet, it will remove all the outdated ontology data and the associated entities such as concepts, terms, relations, semantic types and hierarchy information.
<p><code>
See the list of ontologies/versions to be removed:
http://example/obs/admin/ontologies/list/old?apikey=ObsApiKey<br/>
Remove old ontologies:
http://example/obs/admin/ontologies/remove?apikey=ObsApiKey
</code></p></li>

<li>Add new ontologies from BioPortal to the hierarchy database. By invoking this restlet, it will add all the new ontology data and the associated entities such as concepts, terms, relations, semantic types and hierarchy information.
<p><code>
See the list of ontologies/versions to be added:
http://example/obs/admin/ontologies/list/new?apikey=ObsApiKey<br/>
Add new ontologies:
http://example/obs/admin/ontologies/add?apikey=ObsApiKey
</code></p></li>

<li>Populate Concepts (For details, please refer to Chapter 2.1)
<p><code>http://example/obs/loaderBigConcepts/all?apikey=ObsApiKey</code></p></li>
<li>Populate Hierarchy (For details, please refer to Chapter 2.2)
<p><code>http://example/obs/loaderBigPaths/all?apikey=ObsApiKey</code></p>

<p>To monitor the progress and view any errors, refer to:</p>
<ol>
<li>The "status" field in the table obs_ontology in Annotator DB (obs_hibernate database).
<li>Check the Tomcat log (/var/logs/tomcat6/catalina.out)</li>
</ol></li>
</ol>

== Create Dictionary File ==

<p>All the terms will be created as dictionary file. (Data is coming from the obs_term table)</p>
<ul>
<li>Location : The directory location is specified in build.properties</li>
<pre>
# Dictionary File path
obs.dictionary.path=/srv/ncbo/bioportal_resources/annotator/dictionary/dict
</pre>
<li>The dictionary file is generated in several chunks to avoid memory problems. There is a 1,000,000 term limit per file.</li>
<li>Generate the dictionary file:</li>
<pre>
http://example/obs/createDictionary/0?apikey=ObsApiKey
</pre>
<li>After the files are generated, you can run the command <code>ncborestart</code> to concatenate the resulting dictionary files and to restart the MGREP server.</li>
</ul>

== Mapping Data Population ==
<p>Mappings between ontologies can be used in the Annotator Web Service to find related terms. Loading the mapping information is currently a manual process, though this will be automated in the future. If you have mapping data you would like to include in annotator, please [mailto:support@bioontology.org contact NCBO].</p>

== Appendix ==

=== Data Population - Concepts and Hierarchy ===
<p><b>Introduction:</b> the Annotator hierarchy database population application pulls the ontology and the concept data from BioPortal Core via the REST services, then extracts and computes the hierarchy information, and finally stores the information in the hierarchy database. Then this computed data is accessible via the Annotator REST services.</p>

<p>Data population is divided into two parts: 1) Concepts and 2) Hierarchy. Please see below for details on these two population procedures.</p>

==== Concepts and Direct Relation (level == 1) ====
===== Pre-requisite in "status": =====
<p>The ontology should be in valid status (<font color="red"><b>"status = 3"</b></font>) in the obs_ontology table in Hierarchy Database to start this process (i.e. This is the initial status from BioPortal Core when ontology is successfully parsed). This is also serves as a safety lock to avoid launching population again for ontologies that are already in the process of population or already populated.</p>

===== REST calls available =====
<ol>
<li>For all ontologies: populate all ontologies with valid status ("status = 3") currently stored in Hierarchy DB (ontologies are added during the synchronization process).<br/>
<code>http://example/obs/loaderBigConcepts/all?apikey=ObsApiKey
</code></li>
<li>For a specific ontology: populate the given ontology if "status = 3". Otherwise the data population process will complain that the status is invalid in the Tomcat log and exit.<br/>
<code>http://example/obs/loaderBigConcepts/{ontology_versoin_id}?apikey=ObsApiKey
</code></li>
</ol>

===== Troubleshooting =====
<p>Errors are logged both in Tomcat catalina.out and DB (obs_error_queue table).</p>
<ol>
<li><b>Case 1: BioPortal REST Service is Down</b>
<p>When you kick off the process using the Annotator REST call - either via web browser or shell script - it checks first if BioPortal REST service is alive. If the BioPortal REST service is down – the tomcat log will generate an error message about BioPortal REST service being down (But it does not change the ontology "status" field. Just simply kick off the process again when BioPortal REST service is back up. If BioPortal REST service is down, no change in Annotator database, therefore no need to clean up. See "Error Handling" for the "status" change scenario).</p></li>

<li><b>Case 2: Critical Error</b>
<p>If the error is critical – RunTimeException and etc – the "status" the ontology in obs_ontology table becomes "99" and the data population process halts.</p></li>

<li><b>Case 3: Non-critical Error</b>
<p>If the error is not critical, the "status" the ontology in obs_ontology table becomes "99" but the data population process still continues to populate the rest of the data. An example for a non-critical error is a discrepancy between the data from two different BioPortal REST calls – i.e. Some of the root concepts from getRootConcepts call are missing in BioPortal (The list of concepts from getAllConcepts does not have some of the root concepts).</p></li>
</ol>
<p>In the case of case 2 & 3, data clean up may be necessary. Please see "Data Clean-Up".</p>

==== Indirect Relation Hierarchy (level > 1) ====
===== Pre-requisite in "status": =====
<p>The ontology should be in valid status (<font color="red"><b>"status = 14"</b></font>) in obs_ontology table in Hierarchy Database to start this process (i.e. "loaderBigConcepts" should have been completed for the given ontology). This is a safety lock to avoid launching population again for the ontologies already in the process of population or already populated.</p>

===== REST calls available: =====
<ol>
<li>For all ontologies: populate all ontologies with "status = 14"<br/>
<code>http://example/obs/loaderBigPaths/all?apikey=ObsApiKey</code></li>
<li>For a specific ontology: populate the given ontology if "status = 14". Otherwise the data population process will complain that the status is invalid in the Tomcat log and exit.<br/>
<code>http://example/obs/loaderBigPaths/{ontology_version_id}?apikey=ObsApiKey<br/>
e.g. http://example/obs/loaderBigPaths/40671?apikey=ObsApiKey</code></li>
</ol>

==== Monitoring the Progress ====
<p>To monitor the progress, please see "status" field in obs_ontology table.</p>
<table cellpadding="5" cellspacing="1">
<tr bgcolor="#aaaaaa">
<th>Restlets</th>
<th>Status Required (valid status required to begin the process)</th>
<th>Status Start -> Finish</th>
</tr>
<tr bgcolor="#eeeeee">
<td>loaderBigConcepts</td>
<td>3</td>
<td>11 -> 14</td>
</tr>
<tr bgcolor="#eeeeee">
<td>loaderBigPaths</td>
<td>14</td>
<td>21 -> 28</td>
</tr>
<tr bgcolor="#eeeeee">
<td> </td>
<td> </td>
<td>(status value in obs_ontology table changes as progress continues)</td>
</tr>
</table>

===== Error Handling: =====
<ul>
<li>If there is any <font color="red"><b>error</b></font>, the status will be set to <font color="red"><b>99</b></font></li>
<li>If critical error (e.g. BioPortal REST services down) occurs, the population process will stop and exit. But if it is NOT a critical error (e.g. if the semantic type description is not found from semantic look up table etc), it will mark the status to 99, log the error (both Tomcat log and DB obs_error_queue), but continue with the population.</li>
<li>To restart the process, just run the script to clean up. The script will reset the status either to "3" or "14" depending on Concept clean up or Hierarchy clean up. (See Section II. Data Clean up)</li>
</ul>

=== Data Clean-Up ===
<p>The source for several SQL commands that can be used to clean up data after an aborted population attempt is located in <b>/ncbo/sources/annotator/2004/db/sql/obs_db_cleanup.sql</b> – <b><i>DO NOT RUN</i></b> the entire script since this is just compiled list of commands.</p>

<pre>
/*
-----------------------------------------------------------------------
to clean up or undo everything on one ontology, just run #1 and #2
-----------------------------------------------------------------------
1. Rollback BPConceptManager.
Run this to rollback to initial state - to undo 'loaderConcepts' restlet
*/

set @var_ontology_version_id := '39545';

delete a.* from obs_relation a, obs_concept b, obs_ontology c
where a.level = 1 and a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id;

delete a.* from obs_term a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id;

delete a.* from obs_semantic_type a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id;

delete a.* from obs_concept a, obs_ontology b
where a.ontology_id = b.id
and b.local_ontology_id = @var_ontology_version_id;

UPDATE obs_ontology set status = 3
where local_ontology_id = @var_ontology_version_id;

/*
-----------------------------------------------------------------------
2. Rollback BPPathManager.
Run this to rollback - to undo 'loaderPaths' restlet
*/

set @var_ontology_version_id := '39545';

delete a.* from obs_relation a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id and a.level > 1;

delete a.* from obs_path_to_root a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id;

delete a.* from obs_path_to_leaf a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = @var_ontology_version_id;

UPDATE obs_ontology set status = 14
where local_ontology_id = @var_ontology_version_id;
</pre>

=== Useful SQL Queries for Monitoring and Validation ===
The source for several queries that can be used for monitoring and data validation is located in <b>/ncbo/sources/annotator/2004/db/sql/obs_db_cleanup.sql</b> (In the same file as the Data Clean-Up)

== To check if there are multiple entries for an Ontology ==
<pre>
select name, virtual_ontology_id, local_ontology_id
from obs_ontology
group by virtual_ontology_id
having count(virtual_ontology_id)>1;
</pre>

== Number of concepts for a specific Ontology ==
<pre>
select OT.name, OT.local_ontology_id AS local_ontology_id,
count(CT.id) AS concepts, OT.status from obs_ontology OT
left join obs_concept CT ON CT.ontology_id=OT.id
WHERE OT.local_ontology_id in ('40133')
GROUP BY OT.local_ontology_id;
</pre>

== Number of paths to roots for a specific Ontology ==
<pre>
select OO.local_ontology_id, OO.name,
count(OPR.id) as path_to_roots, OO.status
from obs_ontology OO, obs_concept OC, obs_path_to_root OPR
where OO.id=OC.ontology_id
and OC.id = OPR.concept_id
and OO.local_ontology_id ="40133";
</pre>

== Number of total relations or path_to_root/leaf for a specific ontology (to see the progress) – by looking at how fast the number is growing ==
<pre>
select count(*) from obs_relation a, obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = '40133' and a.level > 1;

select a.*, b.local_concept_id from obs_path_to_root a,
obs_concept b, obs_ontology c
where a.concept_id = b.id and b.ontology_id = c.id
and c.local_ontology_id = '40483';
</pre>

== Ontologies that have the status "Ready" (28) but have no concepts in obs_concept table ==
<pre>
SELECT o.*, c.ontology_id
FROM obs_ontology o
LEFT OUTER JOIN (
SELECT DISTINCT ontology_id FROM obs_concept
) c ON o.id = c.ontology_id
WHERE o.status = 28 AND c.ontology_id IS NULL;
</pre>

[[Category:NCBO Virtual Appliance]]

BioPortal REST services

2012-09-24T22:39:30Z

Palexand: /* Download a specific ontology view based on the ontology view version id */

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use.

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}/{concept id}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}?conceptid={uri-encoded concept id}
**To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Example''': http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=BRO:Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/Melanoma?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Neoplasm?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Melanoma?apikey=YourAPIKey (returns an empty list since the term Melanoma is a leaf node)
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

BioPortal REST services

2012-09-24T22:39:21Z

Palexand: /* Get all versions of an ontology from a virtual ontology id */

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use.

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}/{concept id}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}?conceptid={uri-encoded concept id}
**To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Example''': http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=BRO:Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/Melanoma?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Neoplasm?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Melanoma?apikey=YourAPIKey (returns an empty list since the term Melanoma is a leaf node)
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

BioPortal REST services

2012-09-24T22:39:03Z

Palexand: /* Download an ontology file */

The list below documents the NCBO Web services. For questions on how to use these Web services or to request features, contact [mailto:support@bioontology.org Support].

The '''prefix''' for all production service URLs in the table below is http://rest.bioontology.org/

* '''<font color='red'>Note</font>''': All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, [http://bioportal.bioontology.org/login login to BioPortal] and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

* '''Note''': ''Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs.

= Overview - Using NCBO Technology in Your Project =
See [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project Using NCBO Technology in your Project] for general information and widgets available for use.

= Sample Code Cookbook =
*Examples of using the Web services in sample code can be found [http://www.bioontology.org/wiki/index.php/Sample_Code_Cookbook here]
**Sample code is located within the [https://bmir-gforge.stanford.edu/gf/project/client_examples/scmsvn/?action=browse&path=%2Ftrunk%2F NCBO Gforge repository] and can be checked out via anonymous SVN access

*Code examples for the [http://bioontology.org/wiki/index.php/Annotator_Web_service Annotator] and [http://www.bioontology.org/wiki/index.php/Resource_Index Resource Index] are located on the pages documenting these Web services

*Code examples for the ontology web services, developed in FlexViz, is available at: https://bmir-gforge.stanford.edu/gf/project/flexviz/frs/?action=index. To see the code in action, visit the [http://keg.cs.uvic.ca/ncbo/restservicestest/TestUI.html Test User Interface] that has been set-up using the FlexViz code.

= BioPortal Announce Mailing List =
To receive notices of new BioPortal releases, changes to web services, or planned downtime subscribe to the [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-annouce] list.

= Service Output Formats =
''JSON output scheduled for mid-December release''
Currently, BioPortal services allow for two output formats: <strong>XML</strong> (default) and <strong>JSON</strong> (currently works only for ontology and concept services).

* '''XML''': no special parameters required. This is the default REST services output format. It assumes the media type as <strong>application/xml</strong>.
* '''JSON''': requires an "Accept" request-header with the following value: <strong>application/json</strong>.

If both <strong>application/xml</strong> and <strong>application/json</strong> media types are present in the Accept header, the output format will be determined based on the higher "q" parameter indicating a relative quality factor of each media type. For more info, please refer to: http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html

'''NOTE:''' JSON output is currently not available for Annotator Service.

= Services to access ontologies and ontology versions =

== List all the latest version of ontologies ==

* '''Description''': Return a list of ontologies in BioPortal. To get information on Ontology Views, use the "List the latest version of all Views" Web service call.
* '''Signature''': ./ontologies?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies?apikey=YourAPIKey
** NOTE: The element <id> contains the value for the ontology version identifier.

== Get a specific ontology based on a version id ==
* '''Signature''': ./ontologies/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/39002?apikey=YourAPIKey

== Download an ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given ontology version id.
* '''Signature''': ./ontologies/download/{ontology version id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/39002?apikey=YourAPIKey
* '''Note''': File downloads can include zip archives. Where multiple files are included in the archive, BioPortal uses the following algorithm to determine the primary file: 1) look for a file named the same as the archive with a different extension (IE .owl instead of .zip) and 2) if no similarly-named file exists, use the first file in the list when sorted alphabetically.

== Download the latest ontology file ==
* '''Description''': Download the file (.obo, .owl) corresponding to the given virtual ontology id.
* '''Signature''': ./virtual/download/{ontology id}?email={email_address}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/download/1090?apikey=YourAPIKey

== Get all versions of an ontology from a virtual ontology id ==
* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/1104?apikey=YourAPIKey

== Get latest version of an ontology id ==
* '''Signature''': ./virtual/ontology/{ontology_id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?apikey=YourAPIKey

== Get Metrics for an ontology version ==
* '''Signature''': ./ontologies/metrics/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/metrics/40133?apikey=YourAPIKey
* More documentation: http://www.bioontology.org/wiki/index.php/Ontology_Metrics

== Get all the namespace prefixes for an ontology version ==
* '''Signature''': ./ontologies/namespaces/{ontology version id}?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/namespaces/44450?apikey=YourAPIKey

== List all ontology categories ==
* '''Signature''': ./categories?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/categories?apikey=YourAPIKey

== List all ontology groups ==
* '''Signature''': ./groups?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/groups?apikey=YourAPIKey

= Services to access ontology views and ontology view versions =

Since all the views on ontologies are ontologies themselves all the services that work on ontologies do work for ontology views also with the same signature.

== Download a specific ontology view based on the ontology view version id ==
* '''Signature''': ./ontologies/download/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/download/43072?apikey=YourAPIKey

== Get all view versions of a virtual view ==

* '''Signature''': ./ontologies/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/versions/2070?apikey=YourAPIKey

However, there are a few Web services that are distinct for views.

== List the latest version of all Views ==
* '''Signature''': ./views?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views?apikey=YourAPIKey

== Get all versions of views from a virtual ontology id ==
* '''Description''': Returns all versions of views defined on the latest version a virtual ontology, grouped by virtual view ids.
* '''Signature''': ./views/versions/{ontology id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/views/versions/1104?apikey=YourAPIKey

= Search services =

== Search BioPortal ==
* '''Signature''': ./search/?query={uri-encoded query}[&{optional args}]&apikey={YourAPIKey}
* '''Deprecated Signature''': ./search/{query}[?{optional args}]&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&apikey=YourAPIKey

* '''Boolean Search Options:'''
** () parentheses allow to enclose multiple terms joined by OR
*** <pre>Example: "(foo bar)" will expand to "foo* OR bar*"</pre>
** - the minus sign preceding a term indicates NOT
*** <pre>Example: "foo bar -baz" will expand to "foo* AND bar* AND NOT baz*"</pre>
** No prefix means MUST (required).

* '''Optional Arguments:'''
** ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
** isexactmatch=[1/0] – match the entire concept name (default: 0)
** includeproperties=[1/0] – include attributes in the search (default: 0 and includes the preferred name, term identifier, and synonym properties)
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
** maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
** subtreerootconceptid=<uri-encoded conceptid> - narrow the search to concepts residing in a sub-tree, where the "subtreerootconceptid" is the root node. This feature requires a SINGLE <ontologyid> passed in using the "onotlogyids" parameter.
** objecttypes=<class,individual,property> - limits the results returned to these types, multitple types can be included in the parameter, e.g. class,individual.
** includedefinitions={true} - if a search result is a hit for a term, adding this parameter will include the definition in the search result xml. '''Note''': Including the definition results in a slight performance hit.
* '''Description:'''
The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the end of each word. For example, searching for "cut mela" would return all concepts whose name contains a word starting with "cut", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc).

* '''Field Values'''
** The '<recordType></recordType>' entries can be: PREFERRED_NAME = "apreferredname", CONCEPT_ID = "bconceptid", SYNONYM = "csynonym", and PROPERTY = "dproperty".
** The '<objectType></objectType>' entries are concept types, which can be: "class", "property", or "individual".

* '''Example''': http://rest.bioontology.org/bioportal/search/?query=Gene&ontologyids=1032&isexactmatch=1&apikey=YourAPIKey
* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/search/</accessedResource>
<accessDate>2012-07-06 10:31:44.413 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>1</numPages>
<pageSize>2</pageSize>
<numResultsPage>2</numResultsPage>
<numResultsTotal>2</numResultsTotal>
<contents class="org.ncbo.stanford.bean.search.SearchResultListBean">
<searchResultList>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>apreferredname</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene</conceptId>
<conceptIdShort>Gene</conceptIdShort>
<preferredName>Gene</preferredName>
<contents>Gene</contents>
<isObsolete>0</isObsolete>
</searchBean>
<searchBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<recordType>csynonym</recordType>
<objectType>class</objectType>
<conceptId>http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Gene_Object</conceptId>
<conceptIdShort>Gene_Object</conceptIdShort>
<preferredName>Gene Object</preferredName>
<contents>Gene</contents>
<isObsolete>1</isObsolete>
</searchBean>
</searchResultList>
<ontologyHitList>
<ontologyHitBean>
<ontologyVersionId>47638</ontologyVersionId>
<ontologyId>1032</ontologyId>
<ontologyDisplayLabel>NCI Thesaurus</ontologyDisplayLabel>
<numHits>2</numHits>
</ontologyHitBean>
</ontologyHitList>
<numHitsTotal>3</numHitsTotal>
</contents>
</page>
</data>
</success>
</pre>

= Term services =
(formerly referred to as Concept services)

== Get term, including its properties, subclasses, and superclasses ==
* '''Signature''': ./concepts/{ontology version id}/{concept id}?apikey={YourAPIKey}
* '''Alt Signature''': ./concepts/{ontology version id}?conceptid={uri-encoded concept id}&apikey={YourAPIKey}
* '''Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}/{concept id}
* '''Alt Virtual Signature''' (always uses most recent version of the ontology): ./virtual/ontology/{ontology virtual id}?conceptid={uri-encoded concept id}
**To ensure that the Web service works within your application, use the Alt signature as some ontologies may contain terms where the concept id is a URI.
* '''Optional arguments:'''
** light=[1/0] - when set to 1, returns the "light" version of XML with only a basic info for the concept and its immediate children
** norelations=[1/0] - when set to 1, returns only the requested term information (id, label, fullid, type, synonyms, definitions) without the "relations" map. This is useful when you need to quickly retrieve just the base information about a term.
** maxnumchildren - an integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Example''': http://rest.bioontology.org/bioportal/concepts/44103?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/concepts/44450?conceptid=BRO:Software&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1516?conceptid=O80-O84.9&apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104?conceptid=BRO:Software&apikey=YourAPIKey

* '''Sample Output''':
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/concepts/44103</accessedResource>
<accessDate>2010-12-08 16:57:43.763 PST</accessDate>
<data>
<classBean>
<id>O80-O84.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80-O84.9</fullId>

<label>Delivery</label>
<type>Class</type>
<relations>
<entry>
<string>SubClass</string>
<list>
<classBean>

<id>O84</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O84</fullId>
<label>Multiple delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O83</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O83</fullId>

<label>Other assisted single delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>7</int>
</entry>

</relations>
</classBean>
<classBean>
<id>O82</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O82</fullId>
<label>Single delivery by caesarean section</label>
<type>Class</type>

<relations>
<entry>
<string>ChildCount</string>
<int>5</int>
</entry>
</relations>
</classBean>
<classBean>

<id>O81</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O81</fullId>
<label>Single delivery by forceps and vacuum extractor</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>6</int>
</entry>
</relations>
</classBean>
<classBean>
<id>O80</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O80</fullId>

<label>Single spontaneous delivery</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>
<int>4</int>
</entry>

</relations>
</classBean>
</list>
</entry>
<entry>
<string>PAR</string>
<list>
<classBean>

<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>
<entry>
<string>ChildCount</string>

<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>
<entry>
<string>ChildCount</string>

<int>5</int>
</entry>
<entry>
<string>Semantic_Type</string>
<list>
<string>Therapeutic or Preventive Procedure</string>
</list>

</entry>
<entry>
<string>TUI</string>
<list>
<string>T061</string>
</list>
</entry>
<entry>

<string>UMLS_CUI</string>
<list>
<string>C0011209</string>
</list>
</entry>
<entry>
<string>SuperClass</string>

<list>
<classBean>
<id>O00-O99.9</id>
<fullId>http://purl.bioontology.org/ontology/ICD10/O00-O99.9</fullId>
<label>Pregnancy, childbirth and the puerperium</label>
<type>Class</type>
<relations>

<entry>
<string>ChildCount</string>
<int>8</int>
</entry>
</relations>
</classBean>
</list>
</entry>

</relations>
</classBean>
</data>
</success>
</pre>

== Get all root terms for an ontology version id ==
* '''Signature''': ./concepts/{ontology version id}/root?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/concepts/39002/root?apikey=YourAPIKey

== Get a path between a term and the root ==

* '''Signature''': ./path/{ontology_version_id}/?source={concept1_id}&target=root&apikey=YourAPIKey

* '''Example''': http://rest.bioontology.org/bioportal/path/42838/?source=Transitional_Epithelium&target=root&apikey=YourAPIKey
* Note: If there is no path between the specified term and the set of nodes designated as "roots" then this method just returns the root node. Note that "root" here is defined as a set of classes which have been designated as "roots". It is not defined as a node which as no parents.
* Note: This service only returns a '''single path''' between a term and the root. There is a [[NCBO_REST_services#Get_paths_to_root.2Fleaves_from_a_concept_in_the_latest_version_of_a_given_ontology|service that returns '''all paths''' from a term to the root]] for most ontologies. Alternatively, all paths can be calculated by recursively calling [[NCBO_REST_services#Get_term.2C_including_its_properties.2C_subclasses.2C_and_superclasses|the term service]].

== Get all terms using the specific ontology version id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./concepts/{ontology version id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Examples''':
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Get all terms using the virtual ontology id ==

'''NOTE:''' 'Get all terms' service has changed. The new signature and examples are reflected below. See [[#Changes_to_the_Get_all_terms_service]] for more information.

* '''Signature''': ./virtual/ontology/{ontology id}/all?pagesize={pagesize}&pagenum={pagenum}&apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/ontology/1104/all?&pagesize=50&pagenum=1&apikey=YourAPIKey
* '''Arguments:'''
** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
** '''pagenum:''' An integer indicating which page of results to return.
** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

== Changes to the Get all terms service ==

Starting in BioPortal 2.3.1 (released March 15, 2010), the 'Get all terms' service has changed to support speedier and more complete term retrieval. To support this, several changes to the response XML and service signature are being made. Please see the following notes to update your existing applications to support these changes.

* '''Examples''': A preview of the new service can be seen on the NCBO staging site:
** http://rest.bioontology.org/bioportal/concepts/40644/all?pagesize=50&pagenum=1
** http://rest.bioontology.org/bioportal/concepts/42431/all?pagesize=50&pagenum=500

* '''Signature'''
** '''New parameters:''' Previously, offset and limit were used to control pagination of results. These parameters have been replaced as follows:
*** '''pagesize:''' An integer limiting how many results will be returned on a single page (a 'page' is equivalent to a single call to the REST service)
*** '''pagenum:''' An integer indicating which page of results to return.
*** '''maxnumchildren:''' An integer that sets threshold on the number of children in the SubClass relation for a term. If a term contains more children than the "maxnumchildren", the SubClass relation returns an empty list. The ChildCount relation still contains the correct number of children.

* '''Response''': The structure of the new 'Get all terms' response XML has been brought into line with other BioPortal REST term services. In addition, to assist in paging through result sets, 'page' metadata is provided. A list of classBeans is provided in the classBeanResultList element, which includes each classes' set of relations (examples of relations include SuperClass, SubClass, and rdfs:label). Please see the example below for a full demonstration of the new response.

= View Extraction Service =
* This web service can be used to extract a subtree from an ontology. See [http://www.bioontology.org/wiki/index.php/View_Extraction View Extraction] for usage details.

= Property Services =

== Get all available ontology properties using the specific ontology version id ==
* '''Signature''': ./ontologies/properties/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontologies/properties/38801?apikey=YourAPIKey
* '''Description''': returns all properties for a given ontology version.
* '''Sample Output:'''
<pre>
<success>
<accessedResource>/bioportal/ontologies/properties/38801
</accessedResource>
<accessDate>2011-09-22 15:47:46.309 PDT</accessDate>
<data>
<list>
<propertyBean>
<id>has_value</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_value
</fullId>
<label>has_value</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_description</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_description
</fullId>
<label>has_description</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations />
</propertyBean>
<propertyBean>
<id>has_pages</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#has_pages
</fullId>
<label>has_pages</label>
<type>property</type>
<isObsolete>0</isObsolete>
<relations>
<entry>
<string>Domain</string>
<classBean>
<id>BibliographicReference</id>
<fullId>http://mged.sourceforge.net/ontologies/MGEDOntology.owl#BibliographicReference
</fullId>
<label>BibliographicReference</label>
<type>class</type>
<isObsolete>0</isObsolete>
<relations />
</classBean>
</entry>
</relations>
</propertyBean>
</list>
</data>
</success>
</pre>

= Instance Services =

== Get all direct instances for a given term ==
* '''Signature''': ./concepts/instances/{ontlogyVersionId}?conceptid={uri-encoded concept id}[&{optional args}]&apikey={YourAPIKey}
* '''Optional arguments:'''
** pagesize=<pagesize> - the number of results to display in a single request (default: all)
** pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)

* '''Example''': http://rest.bioontology.org/bioportal/concepts/instances/38801?conceptid=SubstrateType&pagesize=10&pagenum=1&apikey=YourAPIKey
* '''Description''': returns all direct instances for a given term.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/concepts/instances/38801
</accessedResource>
<accessDate>20100408 18:17:21.226 PDT</accessDate>
<data>
<page>
<pageNum>1</pageNum>
<numPages>5</numPages>
<pageSize>1</pageSize>
<numResultsPage>1</numResultsPage>
<numResultsTotal>5</numResultsTotal>
<contents class="org.ncbo.stanford.bean.concept.InstanceBeanResultListBean">
<list>
<instanceBean>
<id>unknown_substrate_type</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</fullId>
<label>unknown_substrate_type</label>
<relations>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unknown_substrate_type
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>

<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_484</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>

<list>
<string>SubstrateType of unknown type.</string>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</contents>
</page>
</data>
</success>
</pre>

== Get an instance and its property/value pairs ==
* '''Signature''': ./instance/{ontlogyVersionId}?instanceid={instanceid}&apikey={YourAPIKey}

* '''Example''': http://rest.bioontology.org/bioportal/instance/38801?instanceid=glass&apikey=YourAPIKey
* '''Description''': returns information about an instance and a list of property/value pairs.
* '''Sample Output:'''
<pre>
<?xml version="1.0" encoding="UTF8" ?>
<success>
<accessedResource>/bioportal/instance/38801
</accessedResource>
<accessDate>20100408 18:10:48.760 PDT</accessDate>
<data>
<instanceBean>
<id>glass</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</fullId>
<label>glass</label>
<relations>
<entry>
<propertyBean>
<id>:NAME</id>
<fullId>:NAME</fullId>
<label>:NAME</label>
<relations />
</propertyBean>
<list>
<string>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#glass
</string>
</list>
</entry>
<entry>
<propertyBean>
<id>unique_identifier</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#unique_identifier
</fullId>
<label>unique_identifier</label>
<relations />
</propertyBean>
<list>
<string>MO_742</string>
</list>
</entry>
<entry>
<propertyBean>
<id>rdfs:comment</id>
<fullId>http://www.w3.org/2000/01/rdfschema#comment
</fullId>
<label>rdfs:comment</label>
<relations />
</propertyBean>
<list>
<string>The array is made on a glass slide.</string>
</list>
</entry>
<entry>
<propertyBean>
<id>:DIRECTTYPE</id>
<fullId>:DIRECTTYPE</fullId>
<label>:DIRECTTYPE</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
<entry>
<propertyBean>
<id>rdf:type</id>
<fullId>http://www.w3.org/1999/02/22rdfsyntaxns#type
</fullId>
<label>rdf:type</label>
<relations />
</propertyBean>
<list>
<instanceBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<relations />
<instanceType>
<list>
<classBean>
<id>owl:Class</id>
<fullId>http://www.w3.org/2002/07/owl#Class
</fullId>
<label>owl:Class</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</list>
</entry>
</relations>
<instanceType>
<list>
<classBean>
<id>SubstrateType</id>
<fullId>
http://mged.sourceforge.net/ontologies/MGEDOntology.owl#SubstrateType
</fullId>
<label>SubstrateType</label>
<type>Class</type>
<relations />
</classBean>
</list>
</instanceType>
</instanceBean>
</data>
</success>
</pre>

= Hierarchy Services =

The Hierarchy Services provide access to pre-computed term hierarchy information via a single web service call. The pre-computed hierarchy data is generated for only one version of an ontology and is periodically updated. Therefore, if using the Hierarchy Web services, it is best to use the form of the call with the virtual ontology id. To get hierarchy information for any version of an ontology, use the Term Web service to traverse the ontology structure.

* '''<font color='red'>NOTE: </font>To see which ontology versions have been processed for use with the Hierarchy Services, check http://rest.bioontology.org/obs/ontologies for ontologies with STATUS=28.'''

== Get paths to root/leaves from a concept in the latest version of a given ontology ==
* '''Signature''': ./virtual/[rootpath|leafpath]/{ontologyId}/{conceptId}[?apikey={YourAPIKey}&{optional args}]
* '''Example''': http://rest.bioontology.org/bioportal/virtual/rootpath/1032/Melanoma?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Neoplasm?apikey=YourAPIKey
* '''Example''': http://rest.bioontology.org/bioportal/virtual/leafpath/1032/Melanoma?apikey=YourAPIKey (returns an empty list since the term Melanoma is a leaf node)
* '''Optional arguments:'''
** offset=<integer> – results offset (used for pagination)
** limit=<integer> – limits the number of results
** delim=<string> – use a custom delimiter between returned terms. Default is a period (.).
* '''Description''': The same as the previous services, but takes an ontology id and returns parents from the latest version of that ontology available via the Hierarchy web services. To see which ontology versions are available, see the '''<font color='red'>NOTE</font>''' above for the [http://www.bioontology.org/wiki/index.php/BioPortal_REST_services#Hierarchy_Services Hierarchy web services].

= Bio2RDF Dump Service =

This service allows you to output a given ontology from BioPortal in the form of a N3 RDF file conforming to the requirements for integrating into the [http://sourceforge.net/projects/bio2rdf/ Bio2RDF] collection.

* '''Signature''': ./ontology/dump_n3/{ontlogyVersionId}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/ontology/dump_n3/40865?apikey=YourAPIKey

= Annotator Service =

The NCBO Annotator is a Web service that can be used to annotate text metadata with biomedical ontology concepts. The concepts are from ontologies in BioPortal and includes the Unified Medical Language System (UMLS) Metathesaurus, OBO Foundry candidate ontologies and many others.

The Annotator can be tested via a Web interface available through [http://bioportal.bioontology.org/annotate BioPortal]. For more information on using the Annotator Web service, see: http://bioontology.org/wiki/index.php/Annotator_Web_service.

= Ontology Recommender =
The Ontology Recommender is a Web service that provides information on what ontology is best covered by your text metadata. An in-depth description and links to the Web service documentation and sample clients can be found at: http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service.

= Resource Index Service =

The Resource Index provides a mechanism to search for biomedical data based on ontology concepts. For more information on using the Resource Index service, see http://www.bioontology.org/wiki/index.php/Resource_Index.

= RDF Term Service =

* '''Signature''': ./bioportal/rdf/{ontology version id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id}&apikey=YourAPIKey
* '''Alt Signature''': ./bioportal/virtual/rdf/{ontology id}/?conceptid={concept id},{concept id},...,{concept id}&apikey=YourAPIKey
** '''NOTE''': To ensure that the Web service works within your application, url-encode the concept id as some ontologies may contain terms where the concept id is a URI.
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/rdf/1321/?conceptid=NEMO_0000024&apikey=YourAPIKey
** http://rest.bioontology.org/bioportal/rdf/47799/?conceptid=NEMO_1398000&apikey=YourAPIKey
* '''Required arguments:'''
** ontology version id
** concept id
* '''Description''': returns a BioPortal concept as RDF/XML ontology snippet. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': <nowiki>http://purl.bioontology.org/ontology/{ACRONYM}/{ID}</nowiki>
*** '''OBO''': <nowiki>http://purl.obolibrary.org/{IDSPACE}_{LOCALID}</nowiki>
* '''Sample Output:'''
<pre>
<?xml version="1.0"?>
<rdf:RDF xmlns="http://purl.bioontology.org/ontology/NEMO#"
xml:base="http://purl.bioontology.org/ontology/NEMO"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:BPMetadata="http://purl.bioontology.org/ontology/BPMetadata#"
xmlns:owl="http://www.w3.org/2002/07/owl#"
xmlns:xsd="http://www.w3.org/2001/XMLSchema#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:NEMO="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#"
xmlns:ontology="http://omv.ontoware.org/2005/05/ontology/"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:ontology2="http://purl.bioontology.org/NEMO/ontology#">
<owl:Ontology rdf:about="http://purl.bioontology.org/ontology/NEMO">
<ontology:name>Neural ElectroMagnetic Ontologies</ontology:name>
<ontology:acronym>NEMO</ontology:acronym>
<ontology:description>Neural ElectroMagnetic Ontologies (NEMO) describe classes of event-related brain potentials (ERP) and their properties, including spatial, temporal, functional (cognitive/behavioral) attributes, and data-level attributes (acquisition and analysis parameters).</ontology:description>
<BPMetadata:id>45141</BPMetadata:id>
<ontology:hasOntologyLanguage rdf:resource="http://omv.ontoware.org/2005/05/ontology#owl"/>
</owl:Ontology>



<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/name"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_synonym">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#altLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#prefLabel">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2000/01/rdf-schema#label"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_definition">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#definition"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#label"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/ontology/BPMetadata#id"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#broader"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subClassOf"/>
<owl:AnnotationProperty rdf:about="http://purl.bioontology.org/NEMO/ontology#NEMO_pref_label">
<rdfs:subPropertyOf rdf:resource="http://www.w3.org/2004/02/skos/core#prefLabel"/>
</owl:AnnotationProperty>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/acronym"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#notation"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/description"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#definition"/>
<owl:AnnotationProperty rdf:about="http://omv.ontoware.org/2005/05/ontology/hasOntologyLanguage"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2000/01/rdf-schema#subPropertyOf"/>
<owl:AnnotationProperty rdf:about="http://www.w3.org/2004/02/skos/core#altLabel"/>





<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>



<owl:Class rdf:about="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000024">
<rdfs:label>left_posterotemporal_scalp_surface_region</rdfs:label>
<rdfs:subClassOf rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
<skos:prefLabel>left_posterotemporal_scalp_surface_region</skos:prefLabel>
<skos:notation>NEMO_0000024</skos:notation>
<ontology2:NEMO_pref_label>left_posterotemporal_scalp_surface_region</ontology2:NEMO_pref_label>
<skos:broader rdf:resource="http://purl.bioontology.org/NEMO/ontology/NEMO.owl#NEMO_0000010"/>
</owl:Class>
</rdf:RDF>



</pre>

= RDF Download Service =

* '''Signature''': ./bioportal/virtual/ontology/rdf/download/{ontology id}?apikey=YourAPIKey
* '''Examples''':
** http://rest.bioontology.org/bioportal/virtual/ontology/rdf/download/1537?apikey=YourAPIKey
''NOTE:'' If using the Web service calls from Firefox, disable the Tabulator Add-on in order to download the files.
* '''Required arguments:'''
** ontology version id
* '''Description''': returns a BioPortal ontology as RDF/XML. This is a prototype web service, for updates subscribe to [https://mailman.stanford.edu/mailman/listinfo/bioportal-announce bioportal-announce].
** The RDF dump will use URIs that are based on which format the ontology is in:
*** '''OWL/RDF(S)''': preserve original URIs
*** '''Protégé & RRF''': http://purl.bioontology.org/ontology/{abbreviation}/{concept_id}
*** '''OBO''': http://purl.obolibrary.org/{idspace}_{localid}

= Notes Service (Term Proposals and Comments) =
* The Notes Web service is described here: http://www.bioontology.org/wiki/index.php/Ontology_Notes.

= Mapping Service =
* The Mapping Web service is described here: http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service.



= XML Schema Definitions for the REST services =

XML Schema for [[#Term_services|Term]] and [[#Hierarchy_Services|Hierarchy]] services have been provided courtesy Eamonn Maguire. An updated XML Schema document will be posted shortly.

Virtual Appliance FAQ

2012-08-30T19:20:16Z

Palexand: /* Installation Instructions */

= Ontology Management =

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

= Systems Administration =

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

[[Category:NCBO Virtual Appliance]]

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

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

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

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

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

This example is for the Tree Browser.

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

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

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

= How can I use the OVF image with my virtualization software? <br/><span style="font-size: smaller;">(VMware, VirtualBox, KVM, Xen, etc)</span> =

== 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? =
The NCBO Virtual Appliance can be deployed in Amazon EC2. The AMI is available in US West (Northern California) region, has the id '''ami-5187dd14''' and is built on the EBS-backed 64-bit Amazon Linux AMI 2012.03

=== Installation Instructions ===
* Login to AWS Console: https://console.aws.amazon.com/ec2/home?region=us-west-1
* Click on Instances → Launch Instance → Classic Wizard → Community AMIs → Choose an AMI:
** Search for “NCBO Appliance” and choose the latest version
** Click '''Continue'''
* Instance Details:
** Instance Type = m1.large (or any other type with at least 2 cores and ~8 GB of RAM)
** Availability Zone = No preference
** Click '''Continue'''
* Advanced Instance Options:
** Termination Protection = Prevention against accidental termination
** Shutdown Behavior = Stop
** Click '''Continue'''
* Instance Tags:
** Name = Name this instance something meaningful
** Click '''Continue'''
* Key Pairs:
** Choose from your Existing Key Pairs or Create a Key Pair
** Click '''Continue'''
* Configure Firewall:
** Choose (you may need to create one first) a Security Group that has ports 22, 80, and 8080 open. It is recommended that you only allow the networks you need. We accept no responsibility/liability for machines getting compromised.
** Click '''Continue'''
* Review Instance Details:
** Make sure your settings are correct
** Click '''Launch'''
** Click '''Close'''
* Click on Instances (left hand side of the screen):
** Once the instance State has changed from Pending to Running and Status Checks is “2/2 checks passed”, login to the instance via the public hostname provided.
** Now you can SSH into the machine using your key-pair and '''ec2-user''' as the user name:
*** <code>ssh -i yourkey_pair ec2-user@{amazon public domain name}</code>
** The domain name can be retrieved by clicking on the instance and looking at the details that appear at the bottom of the screen. It should look similar to this but with a different set of numbers in the subdomain: ec2-10-0-0-1.us-west-1.compute.amazonaws.com

Category:NCBO Virtual Appliance

2012-08-30T19:19:44Z

Palexand: /* Basic System Administration */

The NCBO Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source NCBO software running on a Linux operating system. The image was created using VMWare and is available for download by contacting support@bioontology.org.

The following software is included on the image:
* BioPortal Ontology Services (BioPortal Core)
* BioPortal Web User Interface (including ontology visualization, Flex widgets, Annotator and Resource Index UIs)
* BioPortal Admin (a UI for administering BioPortal Ontology Services)
* Annotator
* Resource Index

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

== Getting Started ==
* To obtain the Virtual Appliance, contact [mailto:support@bioontology.org NCBO Support]
* The download is provided as a tar 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 as this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** BioPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>
* Add an ontology using the BioPortal Admin User here: http://{YourDomainName}/ontologies/new
** BioPortal Ontology Services can be configured to automatically process new ontologies every hour at 30 minutes past the hour (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
* Parsing, indexing, metrics calculation, and ontology deletion can all be manually triggered or re-triggered using the BioPortal Admin user interface, which is available here: http://example:8080/bioportal_admin
* REST services are available at the following locations. The URLs below are for the root of the REST service and generally will not return information. Please read the documentation for guidelines on how to interact with the services, including sample URLs:
** BioPortal Ontology Services - http://example:8080/bioportal ([http://www.bioontology.org/wiki/index.php/BioPortal_REST_services documentation])
** Annotator - http://example:8080/obs/annotator ([http://www.bioontology.org/wiki/index.php/Annotator_User_Guide documentation])
** Resource Index - http://example:8080/resource_index ([http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide 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
** 1 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 3GB

* Recommended for heavier usage
** 2 CPU (3 GHz)
** 6GB RAM (When using more than 4GB RAM, you should configure Tomcat to use the additional memory)
** Hard disk space: 10GB (or more depending on number/size of ontologies)

== Population Workflows ==
When storing an ontology using the BioPortal Ontology Services, some amount of processing is done automatically so that the ontologies can be visualized using the Web UI. However, the Annotator and Resource Index require separate, manual data population workflows in order to function with the provided ontologies. Details on running these populations can be found in the "Howto" sections located at the bottom of this page.

NOTE: Loading ontologies [1] developed using the NCI version of Protege will require an additional manual pre-processing step to remove XML tags added into the synonym and definition property values. This pre-processing step is especially important for populating the correct synonym value into the Annotator workflow. The code to pre-process ontologies developed using the NCI version of Protege is located at:
https://bmir-gforge.stanford.edu/gf/project/bp_helper_tools/scmsvn/?action=browse&path=%2Ftrunk%2FNCItProcessor%2F, the code can be checked out via anonymous SVN.

[1] The NCI Thesaurus and the NanoParticle Ontology are developed using the NCI version of Protege

== Image Format and Operating System Details ==
The NCBO 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 5.7 64-bit running Tomcat 6.0.26, Java 6, MySQL 5.1.x, PHP 5.1.6, Rails 2.3.x, and Ruby Enterprise Edition 1.8.7, and memcached.

The following applications use these services/runtime environments:
* Tomcat, Java
** BioPortal Ontology Services (BioPortal Core)
** BioPortal Admin (a UI for administering BioPortal Ontology Services)
** Annotator and Recommender
** Resource Index
* Rails, Ruby, memcached
** BioPortal Web User Interface (including ontology visualization, Flex widgets, Annotator and Resource Index UIs)
* PHP
** Resource Index UI
* 4store
** Mappings

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* Helper commands:
** <code>ncbostart</code>: the required services are started on boot automatically, but if they need to be started automatically
** <code>ncbostop</code>: manually stop services
** <code>ncborestart</code>: manually start/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 4store 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 4store stop</code>

== License ==
All NCBO software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

Category:NCBO Virtual Appliance

2012-08-30T19:18:35Z

Palexand: /* Image Format and Operating System Details */

The NCBO Virtual Appliance image contains a pre-installed, pre-configured version of commonly-used open source NCBO software running on a Linux operating system. The image was created using VMWare and is available for download by contacting support@bioontology.org.

The following software is included on the image:
* BioPortal Ontology Services (BioPortal Core)
* BioPortal Web User Interface (including ontology visualization, Flex widgets, Annotator and Resource Index UIs)
* BioPortal Admin (a UI for administering BioPortal Ontology Services)
* Annotator
* Resource Index

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

== Getting Started ==
* To obtain the Virtual Appliance, contact [mailto:support@bioontology.org NCBO Support]
* The download is provided as a tar 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 as this hostname as 'example'.
* '''Change default passwords'''
** Operating System
*** Username: <code>root</code>
*** Password: password is prompted on the first boot
** BioPortal Admin User
*** Username: <code>admin</code>
*** Password: <code>changeme</code>
* Add an ontology using the BioPortal Admin User here: http://{YourDomainName}/ontologies/new
** BioPortal Ontology Services can be configured to automatically process new ontologies every hour at 30 minutes past the hour (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
* Parsing, indexing, metrics calculation, and ontology deletion can all be manually triggered or re-triggered using the BioPortal Admin user interface, which is available here: http://example:8080/bioportal_admin
* REST services are available at the following locations. The URLs below are for the root of the REST service and generally will not return information. Please read the documentation for guidelines on how to interact with the services, including sample URLs:
** BioPortal Ontology Services - http://example:8080/bioportal ([http://www.bioontology.org/wiki/index.php/BioPortal_REST_services documentation])
** Annotator - http://example:8080/obs/annotator ([http://www.bioontology.org/wiki/index.php/Annotator_User_Guide documentation])
** Resource Index - http://example:8080/resource_index ([http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide 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
** 1 CPU (2 GHz)
** 4GB RAM
** Hard disk space: 3GB

* Recommended for heavier usage
** 2 CPU (3 GHz)
** 6GB RAM (When using more than 4GB RAM, you should configure Tomcat to use the additional memory)
** Hard disk space: 10GB (or more depending on number/size of ontologies)

== Population Workflows ==
When storing an ontology using the BioPortal Ontology Services, some amount of processing is done automatically so that the ontologies can be visualized using the Web UI. However, the Annotator and Resource Index require separate, manual data population workflows in order to function with the provided ontologies. Details on running these populations can be found in the "Howto" sections located at the bottom of this page.

NOTE: Loading ontologies [1] developed using the NCI version of Protege will require an additional manual pre-processing step to remove XML tags added into the synonym and definition property values. This pre-processing step is especially important for populating the correct synonym value into the Annotator workflow. The code to pre-process ontologies developed using the NCI version of Protege is located at:
https://bmir-gforge.stanford.edu/gf/project/bp_helper_tools/scmsvn/?action=browse&path=%2Ftrunk%2FNCItProcessor%2F, the code can be checked out via anonymous SVN.

[1] The NCI Thesaurus and the NanoParticle Ontology are developed using the NCI version of Protege

== Image Format and Operating System Details ==
The NCBO 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 5.7 64-bit running Tomcat 6.0.26, Java 6, MySQL 5.1.x, PHP 5.1.6, Rails 2.3.x, and Ruby Enterprise Edition 1.8.7, and memcached.

The following applications use these services/runtime environments:
* Tomcat, Java
** BioPortal Ontology Services (BioPortal Core)
** BioPortal Admin (a UI for administering BioPortal Ontology Services)
** Annotator and Recommender
** Resource Index
* Rails, Ruby, memcached
** BioPortal Web User Interface (including ontology visualization, Flex widgets, Annotator and Resource Index UIs)
* PHP
** Resource Index UI
* 4store
** Mappings

== Basic System Administration ==
* Most of our administration scripts and build environment assume that you will be running as the root user.
* Helper commands:
** <code>ncbostart</code>: the required services are started on boot automatically, but if they need to be started automatically
** <code>ncbostop</code>: manually stop services
** <code>ncborestart</code>: manually start/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 virtuoso 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 virtuoso stop</code>

== License ==
All NCBO software is released with the 2-clause BSD license. Source code is included on the Virtual Appliance.

BioPortal Help

2012-07-11T00:19:39Z

Palexand: /* Glossary */

== 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://www.bioontology.org/wiki/index.php/NCBO_REST_services 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://www.bioontology.org/wiki/index.php/NCBO_REST_services#Services_to_access_ontologies_and_ontology_versions Ontology REST API documentation].

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

To '''find a term in any ontology''' enter the full or partial name 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 are returned. Usually this number is sufficient to cover matches in all names, ids, and synonyms.

Some boolean search capability is available. Prefixing a term with "-" means NOT for that term. Thus "heart -attack" will search for terms with "heart" but not "attack" in the name. An OR capability is also available using parentheses. Thus "(heart attack)" means to find terms with either "heart" or "attack" in the name.

To '''search programmatically''' see our [http://www.bioontology.org/wiki/index.php/NCBO_REST_services#Search_services 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://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service Mappings REST API documentation].

=== Recommender Tab ===

The Recommender accepts text or a set of keywords describing a domain of interest; it then suggests appropriate ontologies to use if you want to identify terms in similar text.

The '''ontology ranking algorithm''' is described in the paper [http://www.ncbi.nlm.nih.gov/pubmed/20626921 Jonquet et al J Biomed Semantics. 2010 Jun 22;1 Suppl 1:S1].

To '''retrieve ontology recommendations programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service Ontology Recommender REST API documentation].

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

=== 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 ===
Go to the "Browse" page and press the "Submit Ontology" button near the top of the page.

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

== Glossary ==
; <span id="glossary_class">class</span>: 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.
; <span id="glossary_obsolete_term">obsolete term</span>: 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.
; <span id="glossary_property">property</span>: 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.
; <span id="slice_definition">slice</span>: 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 ==
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 Notes

2012-06-15T18:56:22Z

Palexand: /* Creating a 'New Term Proposal' proposal */

BioPortal uses Notes to describe a variety of user-specified comments and metadata for an ontology, including new term proposals, requests for changes, comments and questions.

The prefix for all production service URLs in the table below is http://rest.bioontology.org/bioportal

* '''<font color='red'>Note</font>''': All NCBO REST Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.
* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

== Types of notes in BioPortal ==
The following are the types of notes in BioPortal. Please, email us at [mailto:support@bioontology.org support@bioontology.org] if you have suggestions for other note types (or specific parameters for the notes).

* Basic comments (as they are in BioPortal currently)
* Proposals
** New term proposal
*** PrefName
*** Synonym
*** Definition
*** Superclass
*** Comment
** New relationship proposal
*** Relationship type: is-a, part-of
*** Relationship target
** New attribute value proposal
*** Attribute: documentation, definition, etc.
*** New value
*** Flag: replaces the current value (which one, in case of multiple values) or in addition to the current value(s)
*** (future implementation) Special kind of new attribute value proposal: Assigning UMLS semantic type
**** Semantic type
**** Semantic typeID

* (future implementation) Structured annotations with user-defined structure
* (future implementation) Usage-guideline notes

== Web services to access and generate notes ==
If you have specific requirements that the list of services below does not satisfy, please contact us at [mailto:support@bioontology.org support@bioontology.org]

=== Get notes for an ontology by version id ===

* '''Signature''': ./notes/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/notes/44450?apikey=YourAPIKey
* '''Description''': returns all notes for a specific version of the ontology
* '''Optional arguments:'''
** conceptid={conceptid} - returns notes associated with the given term.
** instanceid={instanceid} - returns notes associated with the given instance (individual).
** noteid={noteid} - returns notes associated with the given note id.
** threaded=[true|false] - returns notes in a threaded format where responses are nested in their parent notes. Default is false.
** Planned (not yet implemented):
*** notetype={notetype} - returns only the notes of the specific type.
*** includearchived=[true|false] - include archived notes. Default is false.

=== Get notes for an ontology by virtual id ===

* '''Signature''': ./virtual/notes/{ontology virtual id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/notes/1104?apikey=YourAPIKey
* '''Description''': returns all notes for the virtual ontology, i.e., all notes associated with any version of this ontology
* '''Optional arguments:'''
** conceptid={conceptid} - returns notes associated with the given term.
** instanceid={instanceid} - returns notes associated with the given instance (individual).
** noteid={noteid} - returns notes associated with the given note id.
** threaded=[true|false] - returns notes in a threaded format where responses are nested in their parent notes. Default is false.
** Planned (not yet implemented):
*** notetype={notetype} - returns only the notes of the specific type.
*** includearchived=[true|false] - include archived notes. Default is false.

=== Sample of the XML returned for a note ===

==== Possible Values ====
Some elements have a range of possible returned values.
* appliesTo/type: Ontology|Class|Individual|Property|Note
* noteBean/type: Comment|ProposalForCreateEntity|ProposalForChangeHierarchy|ProposalForPropertyValueChange
** Notes with types other than Comment will have an element in noteBean/values that matches the noteBean/type. This contains information specific to these Notes types.

==== A single 'Comment' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 13:02:57.418 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070868364</created>
<updated>1272070868250</updated>
<subject>Including clinical trial data as clinical data</subject>
<body>I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
</noteBean>
</list>
</data>
</success>
</pre>

==== A single 'New Term Proposal' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104/</accessedResource>
<accessDate>2010-04-26 18:13:24.407 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_f8bb4dc0-10b3-48b9-ab69-79aed042c0ff</id>
<ontologyId>1104</ontologyId>
<type>ProposalForCreateEntity</type>
<author>1234</author>
<created>1272319359680</created>
<updated>1272319377224</updated>
<subject>Test Proposal Reply</subject>
<body>Testing new term submission</body>
<appliesToList>
<appliesTo>
<ontologyId>1104</ontologyId>
<type>Ontology</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForCreateEntity>
<reasonForChange>Bad data</reasonForChange>
<contactInfo>palexander@stanford.edu</contactInfo>
<id>TERM_1100</id>
<preferredName>New Term</preferredName>
<definition>Test new definition</definition>
<synonyms>
<string>best term</string>
<string>amazing term</string>
<string>great term</string>
</synonyms>
<parent>
<string>http://www.owl-ontologies.com/2009/9/24/Ontology1253802770.owl#Summary</string>
</parent>
</ProposalForCreateEntity>
</values>
</noteBean>
</list>
</data>
</success>
</pre>

==== A single 'Change Relationship/Hierarchy Proposal' note ====

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 18:21:52.474 PDT</accessDate>
<data>
<noteBean>
<id>Note_b4e749c8-5ca7-414f-a123-acd16ba656fe</id>
<ontologyId>1104</ontologyId>
<type>ProposalForChangeHierarchy</type>
<author>1234</author>
<created>1272331290991</created>
<updated>1272331295114</updated>
<subject>Change Relationship</subject>
<body>Testing change hierarchy</body>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForChangeHierarchy>
<reasonForChange>Incorrect data</reasonForChange>
<contactInfo>palexander@stanford.edu/contactInfo>
<relationshipTarget>
<string>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Software</string>
</relationshipTarget>
<oldRelationshipTarget>
<string>isa</string>
</oldRelationshipTarget>
</ProposalForChangeHierarchy>
</values>
</noteBean>
</data>
</success>
</pre>

==== A single 'Property Value Change Proposal' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 18:25:30.465 PDT</accessDate>
<data>
<noteBean>
<id>Note_8cfde654-2c2c-42e3-8187-0f6c05c6deff</id>
<ontologyId>1104</ontologyId>
<type>ProposalForPropertyValueChange</type>
<author>1234</author>
<created>1272331520036</created>
<updated>1272331522822</updated>
<subject>Tet Property Value Change</subject>
<body>Testing a proposal to change a property value</body>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForPropertyValueChange>
<reasonForChange>The value was entered incorrectly initially</reasonForChange>
<contactInfo>palexander@stanford.edu</contactInfo>
<newValue>200</newValue>
<oldValue>100</oldValue>
<propertyId>Cell_Count</propertyId>
</ProposalForPropertyValueChange>
</values>
</noteBean>
</data>
</success>
</pre>

==== A nested thread of 'Comment' notes ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 13:21:28.104 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070868364</created>
<updated>1272070868250</updated>
<subject>Including clinical trial data as clinical data</subject>
<body>I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<associated>
<noteBean>
<id>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38144</author>
<created>1272070984380</created>
<updated>1272070984243</updated>
<subject>RE:Including clinical trial data as clinical data</subject>
<body>Not sure I follow the argument here.&nbsp; Clinical trial data is covered under PHI so no distinction there.&nbsp; Data generated in the course of delivering routine standard of care may be needed in the course of a clinical trial.&nbsp; Does this make clinical trial data an overlapping superset of clinical data?</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
<associated>
<noteBean>
<id>Note_6bdc5fae-bd95-492c-ab47-0aaae7a2193a</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070985097</created>
<updated>1272070985195</updated>
<subject>RE:RE:Including clinical trial data as clinical data</subject>
<body>I was only reacting to the definition of BRO:Clinical_Data in the current version: "Any type of data obtained in the course of caring for humans outside of measurements obtained in clinical trials". I think I'm agreeing with you that clinical trial data should be overlapping clinical data (whether its a superset I'm not sure). So I'm not clear why the definition that is in the current version is there. Somehow this might be related to the fact that BRO:Data_Object is subclassed partly by function (eg clinical data) and partly by data type (eg image). I would think images could also be a type of clinical data.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
</noteBean>
<noteBean>
<id>Note_1b490c3a-dd19-458a-9446-5184e42d03ab</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38145</author>
<created>1272070986051</created>
<updated>1272070986093</updated>
<subject>RE: Including clinical trial data as clinical data</subject>
<body>Hi David and all,<br><br>Clinical Trial Data should probably be dealt with separately from Clinical Data<br>collected in the course of administering clinical care.&nbsp; The use of Clinical<br>Trial data will be governed by the Consent that the patient signs as part of the<br>IRB Protocol that is set up to allow its collection, while the use Clinical Care<br>Data will be governed by the HIPAA notification that the patient receives, as<br>well as any IRB Protocols set up for the research involved.<br></body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
</noteBean>
</associated>
</noteBean>
</associated>
</noteBean>
</list>
</data>
</success>
</pre>

= Creating Notes in BioPortal =
BioPortal uses ontology notes to describe a variety of user-specified comments and metadata on ontology, including new-term proposals, proposals for changes, comments and questions about classes, and so on.

== BioPortal and REST Principles ==
BioPortal utilizes REST principles to create, read, update, and delete resources. The following service documentation uses the HTTP POST method to create notes in the BioPortal system. For more information, please see [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html W3C's documentation on HTTP methods].

== Types of notes in BioPortal ==
The following are the types of notes in BioPortal. Please, email us at [mailto:support@bioontology.org support@bioontology.org] if you have suggestions for other note types (or specific parameters for the notes).

* Basic comments (as they are in BioPortal currently)
* Proposals
** New term proposal
** New relationship proposal
** New attribute value proposal

=== Creating a 'Comment' note ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=Comment&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=Comment&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&email={email_address}
* '''Description''': creates a new note of the type 'Comment'
* '''Arguments''':
** type=Comment - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype={Ontology|Class|Individual|Property|Note} - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

=== Creating a 'New Term Proposal' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForCreateEntity&appliesto={appliestoid}&appliestotype=Ontology&subject={subject}&reasonforchange={reasonforchange}&author={author}&newtermdefinition={definition}&newtermparent={termparent}&newtermpreferredname={preferredname}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForCreateEntity&appliesto={appliestoid}&appliestotype=Ontology&subject={subject}&reasonforchange={reasonforchange}&author={author}&newtermdefinition={definition}&newtermparent={termparent}&newtermpreferredname={preferredname}&email={email_address}
* '''Description''': creates a new note of the type 'New Term Proposal'
* '''Arguments''' (* required):
** * type=ProposalForCreateEntity - the type of note to create.
** * appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** * appliestotype={Ontology|Class} - The type of the thing that the note is associated with.
** * author={authorid} - The author's BioPortal user id.
** * reasonforchange={reason for change} - An explanation for why the proposal is being made.
** * termpreferredname={preferredname} - Preferred name for the new term.
** * termdefinition={definition} - Definition for the new term.
** * termparent={termparent} - ID for the parent of the new term. Must be a valid IRI or 'root' to include the term at the root of the ontology.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** contactinfo={contact information} - Contact information for the entity making the request.
** termsynonyms={synonym1,synonym2,synonym3} - Synonyms for the new term. Can be a single entry or comma-separated list.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.
* '''Removed Arugments''' (no longer used):
** newtermid={termid} - Proposed or generated id for the new term.
*** This has been removed to allow for automatic generation of temporary URI ids for use with terms. This will allow you to refer to a term immediately after creating a new term proposal.

=== Creating a 'Change Relationship/Hierarchy' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForChangeHierarchy&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={parent}&newtermpreferredname={preferredname}&newtermsynonyms={listofsynonyms}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForChangeHierarchy&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={parent}&newtermpreferredname={preferredname}&newtermsynonyms={listofsynonyms}&email={email_address}
* '''Description''': creates a new note of the type 'Comment'
* '''Arguments''':
** type=ProposalForChangeHierarchy - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Class - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** reasonforchange={reason for change} - An explanation for why the proposal is being made.
** contactinfo={contact information} - Contact information for the entity making the request.
** relationshiptype={relationshiptype} - The type of relationship that should be created (is_a, part_of, has_part, etc)
** relationshiptarget={relationshiptarget} - The term to create the relationship with.
** oldrelationshiptarget={oldrelationshiptarget} - The term that the relationship is being changed from (if different than relationshiptarget).
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

=== Creating a 'Change Property Value' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForPropertyValueChange&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newpropertyvalue={newvalue}&oldpropertyvalue={oldvalue}&propertyid={propertyid}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForPropertyValueChange&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newpropertyvalue={newvalue}&oldpropertyvalue={oldvalue}&propertyid={propertyid}&email={email_address}
* '''Description''': creates a new note of the type 'Change Property Value'
* '''Arguments''':
** type=ProposalForPropertyValueChange - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Property - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** reasonforchange={reason for change} - An explanation for why the proposal is being made.
** contactinfo={contact information} - Contact information for the entity making the request.
** newpropertyvalue={newpropertyvalue} - The new value for the property.
** oldpropertyvalue={oldpropertyvalue} - The old value for the property.
** propertyid={propertyid}= The ID of the property to change.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

== Updating an Existing Note ==

* '''Signature (HTTP PUT)''': ./virtual/notes/{ontology virtual id}?noteid={note_id}
* '''Alt Signature (HTTP PUT)''': ./notes/{ontology version id}?noteid={note_id}
* '''Description''': updates an existing note using the given note id.
* '''Arguments:''' (* = required)
** * noteid={note_id} - Id of the note to update.
** archive=true - Archives the note with the given note id.
** archivethread=true - Archives all of the notes that are listed as associated to the given note id plus all of their children.
** unarchive=true - Unarchives the note with the given note id.
** unarchivethread=true - Unarchives all of the notes that are listed as associated to the given note id plus all of their children.
** type=Comment|ProposalForCreateEntity|ProposalForChangeHierarchy|ProposalForPropertyValueChange - the type of note.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Property - The type of the thing that the note is associated with.
** subject={subject} - The subject for the note.
** content={content} - The content of the note.
** author={authorid} - The author's BioPortal user id.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

== Web services to submit Terms ==
* See http://www.bioontology.org/wiki/index.php/BioPortal_Provisional_Terms

Ontology Notes

2012-06-15T18:48:29Z

Palexand:

BioPortal uses Notes to describe a variety of user-specified comments and metadata for an ontology, including new term proposals, requests for changes, comments and questions.

The prefix for all production service URLs in the table below is http://rest.bioontology.org/bioportal

* '''<font color='red'>Note</font>''': All NCBO REST Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.
* '''''Note for Application Developers''''': Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

== Types of notes in BioPortal ==
The following are the types of notes in BioPortal. Please, email us at [mailto:support@bioontology.org support@bioontology.org] if you have suggestions for other note types (or specific parameters for the notes).

* Basic comments (as they are in BioPortal currently)
* Proposals
** New term proposal
*** PrefName
*** Synonym
*** Definition
*** Superclass
*** Comment
** New relationship proposal
*** Relationship type: is-a, part-of
*** Relationship target
** New attribute value proposal
*** Attribute: documentation, definition, etc.
*** New value
*** Flag: replaces the current value (which one, in case of multiple values) or in addition to the current value(s)
*** (future implementation) Special kind of new attribute value proposal: Assigning UMLS semantic type
**** Semantic type
**** Semantic typeID

* (future implementation) Structured annotations with user-defined structure
* (future implementation) Usage-guideline notes

== Web services to access and generate notes ==
If you have specific requirements that the list of services below does not satisfy, please contact us at [mailto:support@bioontology.org support@bioontology.org]

=== Get notes for an ontology by version id ===

* '''Signature''': ./notes/{ontology version id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/notes/44450?apikey=YourAPIKey
* '''Description''': returns all notes for a specific version of the ontology
* '''Optional arguments:'''
** conceptid={conceptid} - returns notes associated with the given term.
** instanceid={instanceid} - returns notes associated with the given instance (individual).
** noteid={noteid} - returns notes associated with the given note id.
** threaded=[true|false] - returns notes in a threaded format where responses are nested in their parent notes. Default is false.
** Planned (not yet implemented):
*** notetype={notetype} - returns only the notes of the specific type.
*** includearchived=[true|false] - include archived notes. Default is false.

=== Get notes for an ontology by virtual id ===

* '''Signature''': ./virtual/notes/{ontology virtual id}?apikey={YourAPIKey}
* '''Example''': http://rest.bioontology.org/bioportal/virtual/notes/1104?apikey=YourAPIKey
* '''Description''': returns all notes for the virtual ontology, i.e., all notes associated with any version of this ontology
* '''Optional arguments:'''
** conceptid={conceptid} - returns notes associated with the given term.
** instanceid={instanceid} - returns notes associated with the given instance (individual).
** noteid={noteid} - returns notes associated with the given note id.
** threaded=[true|false] - returns notes in a threaded format where responses are nested in their parent notes. Default is false.
** Planned (not yet implemented):
*** notetype={notetype} - returns only the notes of the specific type.
*** includearchived=[true|false] - include archived notes. Default is false.

=== Sample of the XML returned for a note ===

==== Possible Values ====
Some elements have a range of possible returned values.
* appliesTo/type: Ontology|Class|Individual|Property|Note
* noteBean/type: Comment|ProposalForCreateEntity|ProposalForChangeHierarchy|ProposalForPropertyValueChange
** Notes with types other than Comment will have an element in noteBean/values that matches the noteBean/type. This contains information specific to these Notes types.

==== A single 'Comment' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 13:02:57.418 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070868364</created>
<updated>1272070868250</updated>
<subject>Including clinical trial data as clinical data</subject>
<body>I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
</noteBean>
</list>
</data>
</success>
</pre>

==== A single 'New Term Proposal' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104/</accessedResource>
<accessDate>2010-04-26 18:13:24.407 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_f8bb4dc0-10b3-48b9-ab69-79aed042c0ff</id>
<ontologyId>1104</ontologyId>
<type>ProposalForCreateEntity</type>
<author>1234</author>
<created>1272319359680</created>
<updated>1272319377224</updated>
<subject>Test Proposal Reply</subject>
<body>Testing new term submission</body>
<appliesToList>
<appliesTo>
<ontologyId>1104</ontologyId>
<type>Ontology</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForCreateEntity>
<reasonForChange>Bad data</reasonForChange>
<contactInfo>palexander@stanford.edu</contactInfo>
<id>TERM_1100</id>
<preferredName>New Term</preferredName>
<definition>Test new definition</definition>
<synonyms>
<string>best term</string>
<string>amazing term</string>
<string>great term</string>
</synonyms>
<parent>
<string>http://www.owl-ontologies.com/2009/9/24/Ontology1253802770.owl#Summary</string>
</parent>
</ProposalForCreateEntity>
</values>
</noteBean>
</list>
</data>
</success>
</pre>

==== A single 'Change Relationship/Hierarchy Proposal' note ====

<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 18:21:52.474 PDT</accessDate>
<data>
<noteBean>
<id>Note_b4e749c8-5ca7-414f-a123-acd16ba656fe</id>
<ontologyId>1104</ontologyId>
<type>ProposalForChangeHierarchy</type>
<author>1234</author>
<created>1272331290991</created>
<updated>1272331295114</updated>
<subject>Change Relationship</subject>
<body>Testing change hierarchy</body>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForChangeHierarchy>
<reasonForChange>Incorrect data</reasonForChange>
<contactInfo>palexander@stanford.edu/contactInfo>
<relationshipTarget>
<string>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Software</string>
</relationshipTarget>
<oldRelationshipTarget>
<string>isa</string>
</oldRelationshipTarget>
</ProposalForChangeHierarchy>
</values>
</noteBean>
</data>
</success>
</pre>

==== A single 'Property Value Change Proposal' note ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 18:25:30.465 PDT</accessDate>
<data>
<noteBean>
<id>Note_8cfde654-2c2c-42e3-8187-0f6c05c6deff</id>
<ontologyId>1104</ontologyId>
<type>ProposalForPropertyValueChange</type>
<author>1234</author>
<created>1272331520036</created>
<updated>1272331522822</updated>
<subject>Tet Property Value Change</subject>
<body>Testing a proposal to change a property value</body>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<values>
<ProposalForPropertyValueChange>
<reasonForChange>The value was entered incorrectly initially</reasonForChange>
<contactInfo>palexander@stanford.edu</contactInfo>
<newValue>200</newValue>
<oldValue>100</oldValue>
<propertyId>Cell_Count</propertyId>
</ProposalForPropertyValueChange>
</values>
</noteBean>
</data>
</success>
</pre>

==== A nested thread of 'Comment' notes ====
<pre>
<?xml version="1.0" encoding="UTF-8"?>
<success>
<accessedResource>/bioportal/virtual/notes/1104</accessedResource>
<accessDate>2010-04-26 13:21:28.104 PDT</accessDate>
<data>
<list>
<noteBean>
<id>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070868364</created>
<updated>1272070868250</updated>
<subject>Including clinical trial data as clinical data</subject>
<body>I note that clinical data is specifically defined not to include clinical trial data. So is anyone already thinking about where at a high level subtrees might be added to deal with clinical trial data and clinical trial management systems? Or is it premature to do that? This is for the CTSAs.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<fullId>http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Clinical_Data</fullId>
<type>Class</type>
</appliesTo>
</appliesToList>
<associated>
<noteBean>
<id>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38144</author>
<created>1272070984380</created>
<updated>1272070984243</updated>
<subject>RE:Including clinical trial data as clinical data</subject>
<body>Not sure I follow the argument here.&nbsp; Clinical trial data is covered under PHI so no distinction there.&nbsp; Data generated in the course of delivering routine standard of care may be needed in the course of a clinical trial.&nbsp; Does this make clinical trial data an overlapping superset of clinical data?</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_0a78922c-3d1e-4689-8af8-48d10d4cdaa8</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
<associated>
<noteBean>
<id>Note_6bdc5fae-bd95-492c-ab47-0aaae7a2193a</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38143</author>
<created>1272070985097</created>
<updated>1272070985195</updated>
<subject>RE:RE:Including clinical trial data as clinical data</subject>
<body>I was only reacting to the definition of BRO:Clinical_Data in the current version: "Any type of data obtained in the course of caring for humans outside of measurements obtained in clinical trials". I think I'm agreeing with you that clinical trial data should be overlapping clinical data (whether its a superset I'm not sure). So I'm not clear why the definition that is in the current version is there. Somehow this might be related to the fact that BRO:Data_Object is subclassed partly by function (eg clinical data) and partly by data type (eg image). I would think images could also be a type of clinical data.</body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
</noteBean>
<noteBean>
<id>Note_1b490c3a-dd19-458a-9446-5184e42d03ab</id>
<ontologyId>1104</ontologyId>
<type>Comment</type>
<author>38145</author>
<created>1272070986051</created>
<updated>1272070986093</updated>
<subject>RE: Including clinical trial data as clinical data</subject>
<body>Hi David and all,<br><br>Clinical Trial Data should probably be dealt with separately from Clinical Data<br>collected in the course of administering clinical care.&nbsp; The use of Clinical<br>Trial data will be governed by the Consent that the patient signs as part of the<br>IRB Protocol that is set up to allow its collection, while the use Clinical Care<br>Data will be governed by the HIPAA notification that the patient receives, as<br>well as any IRB Protocols set up for the research involved.<br></body>
<createdInOntologyVersion>2</createdInOntologyVersion>
<appliesToList>
<appliesTo>
<noteId>Note_02e4b8cd-f582-411c-8561-035a0f7d1dd9</noteId>
<type>Note</type>
</appliesTo>
</appliesToList>
</noteBean>
</associated>
</noteBean>
</associated>
</noteBean>
</list>
</data>
</success>
</pre>

= Creating Notes in BioPortal =
BioPortal uses ontology notes to describe a variety of user-specified comments and metadata on ontology, including new-term proposals, proposals for changes, comments and questions about classes, and so on.

== BioPortal and REST Principles ==
BioPortal utilizes REST principles to create, read, update, and delete resources. The following service documentation uses the HTTP POST method to create notes in the BioPortal system. For more information, please see [http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html W3C's documentation on HTTP methods].

== Types of notes in BioPortal ==
The following are the types of notes in BioPortal. Please, email us at [mailto:support@bioontology.org support@bioontology.org] if you have suggestions for other note types (or specific parameters for the notes).

* Basic comments (as they are in BioPortal currently)
* Proposals
** New term proposal
** New relationship proposal
** New attribute value proposal

=== Creating a 'Comment' note ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=Comment&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=Comment&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&email={email_address}
* '''Description''': creates a new note of the type 'Comment'
* '''Arguments''':
** type=Comment - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype={Ontology|Class|Individual|Property|Note} - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

=== Creating a 'New Term Proposal' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForCreateEntity&appliesto={appliestoid}&appliestotype=Ontology&subject={subject}&reasonforchange={reasonforchange}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={termparent}&newtermpreferredname={preferredname}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForCreateEntity&appliesto={appliestoid}&appliestotype=Ontology&subject={subject}&reasonforchange={reasonforchange}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={termparent}&newtermpreferredname={preferredname}&email={email_address}
* '''Description''': creates a new note of the type 'New Term Proposal'
* '''Arguments''':
** type=ProposalForCreateEntity - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype={Ontology|Class} - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** reasonforchange={reason for change} - An explanation for why the proposal is being made.
** contactinfo={contact information} - Contact information for the entity making the request.
** termdefinition={definition} - Definition for the new term.
** termparent={termparent} - ID for the parent of the new term. Must be a valid IRI.
** termpreferredname={preferredname} - Preferred name for the new term.
** termsynonyms={synonym1,synonym2,synonym3} - Synonyms for the new term. Can be a single entry or comma-separated list.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.
* '''Removed Arugments''' (no longer used):
** newtermid={termid} - Proposed or generated id for the new term.
*** This has been removed to allow for automatic generation of temporary URI ids for use with terms. This will allow you to refer to a term immediately after creating a new term proposal.

=== Creating a 'Change Relationship/Hierarchy' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForChangeHierarchy&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={parent}&newtermpreferredname={preferredname}&newtermsynonyms={listofsynonyms}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForChangeHierarchy&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newtermdefinition={definition}&newtermid={termid}&newtermparent={parent}&newtermpreferredname={preferredname}&newtermsynonyms={listofsynonyms}&email={email_address}
* '''Description''': creates a new note of the type 'Comment'
* '''Arguments''':
** type=ProposalForChangeHierarchy - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Class - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** reasonforchange={reason for change} - An explanation for why the proposal is being made.
** contactinfo={contact information} - Contact information for the entity making the request.
** relationshiptype={relationshiptype} - The type of relationship that should be created (is_a, part_of, has_part, etc)
** relationshiptarget={relationshiptarget} - The term to create the relationship with.
** oldrelationshiptarget={oldrelationshiptarget} - The term that the relationship is being changed from (if different than relationshiptarget).
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

=== Creating a 'Change Property Value' proposal ===

* '''Signature (HTTP POST)''': ./virtual/notes/{ontology virtual id}?type=ProposalForPropertyValueChange&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newpropertyvalue={newvalue}&oldpropertyvalue={oldvalue}&propertyid={propertyid}&email={email_address}
* '''Alt Signature (HTTP POST)''': ./notes/{ontology version id}?type=ProposalForPropertyValueChange&appliesto={appliestoid}&appliestotype={appliestotype}&subject={subject}&content={content}&author={author}&newpropertyvalue={newvalue}&oldpropertyvalue={oldvalue}&propertyid={propertyid}&email={email_address}
* '''Description''': creates a new note of the type 'Change Property Value'
* '''Arguments''':
** type=ProposalForPropertyValueChange - the type of note to create.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Property - The type of the thing that the note is associated with.
** subject={subject} - The subject for the comment.
** content={content} - The content of the comment.
** author={authorid} - The author's BioPortal user id.
** reasonforchange={reason for change} - An explanation for why the proposal is being made.
** contactinfo={contact information} - Contact information for the entity making the request.
** newpropertyvalue={newpropertyvalue} - The new value for the property.
** oldpropertyvalue={oldpropertyvalue} - The old value for the property.
** propertyid={propertyid}= The ID of the property to change.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

== Updating an Existing Note ==

* '''Signature (HTTP PUT)''': ./virtual/notes/{ontology virtual id}?noteid={note_id}
* '''Alt Signature (HTTP PUT)''': ./notes/{ontology version id}?noteid={note_id}
* '''Description''': updates an existing note using the given note id.
* '''Arguments:''' (* = required)
** * noteid={note_id} - Id of the note to update.
** archive=true - Archives the note with the given note id.
** archivethread=true - Archives all of the notes that are listed as associated to the given note id plus all of their children.
** unarchive=true - Unarchives the note with the given note id.
** unarchivethread=true - Unarchives all of the notes that are listed as associated to the given note id plus all of their children.
** type=Comment|ProposalForCreateEntity|ProposalForChangeHierarchy|ProposalForPropertyValueChange - the type of note.
** appliesto={appliestoid} - The id of the thing to associate the note with. This can be a class (term), individual, property, or another note. For classes, individuals, and properties, the specified id must exist in the target ontology. URIs must be URL-encoded.
** appliestotype=Property - The type of the thing that the note is associated with.
** subject={subject} - The subject for the note.
** content={content} - The content of the note.
** author={authorid} - The author's BioPortal user id.
** status={status} - Status for this notes. The Changes and Annotation Ontology provides a default set of statuses for proposals (Submitted, Rejected, Under Discussion, Under Review, Approved, Rejected, Implemented, Published) but the service also accepts arbitrary strings.

== Web services to submit Terms ==
* See http://www.bioontology.org/wiki/index.php/BioPortal_Provisional_Terms