add docs on ontologies

docs/data-model/index.rst

@@ -7,5 +7,6 @@ Data Model
   model
   data-labels
   overlaps
+  model-ontologies
 
 

docs/data-model/model-ontologies.rst

@@ -0,0 +1,57 @@
+Decorating your model with ontologies
+================================================================
+
+It is possible to add ontolgy terms to the data types in your data model. 
+
+Why would you do this? Where is this used?
+----------------------------------------------
+
+Adding an ontology term to a class will facilitate cross InterMine querying. 
+
+It can also enable cross-database analysis. Is the “gene” data type in MouseMine the same one as in the EBI?
+
+We will use these ontologies in the future when we generate RDF.
+
+How do you chose an ontology term?
+--------------------------------------
+
+We used an ontology search, then selected the most specific and accurate term available.
+
+This is the search we used: https://bioportal.bioontology.org/search
+
+We ended up selecting terms that were in the following ontologies:
+
+* `Sequence Ontology <http://www.sequenceontology.org/>`_
+* `Semantic Science <https://bioportal.bioontology.org/ontologies/SIO>`_
+* `EDAM <https://bioportal.bioontology.org/ontologies/EDAM>`_
+* `MeSH <https://bioportal.bioontology.org/ontologies/MESH>`_
+* `Dublin Core <https://bioportal.bioontology.org/ontologies/DC>`_ 
+* `National Cancer Institute Thesaurus (US NIH) <https://bioportal.bioontology.org/ontologies/NCIT>`_ 
+
+
+
+How do you add an ontology term to the data model?
+----------------------------------------------------------------------------
+
+We've already added the terms to the core InterMine data model, and data types in the sequence ontology are updated automatically. You'll need to add ontology terms only to classes and attributes that you have added to your mine.
+
+Once you have selected the correct ontology term, use the attribute `term` and add it to your data model. See the example below
+
+
+An example additions.xml snippet with an ontology term
+---------------------------------------------------------------------
+
+.. code-block:: xml
+
+  <?xml version="1.0"?>
+  <model name="testing" package="org.intermine.model.bio">
+    <class name="Protein" is-interface="true" term="http://semanticscience.org/resource/SIO_010043">
+      <attribute name="name" type="java.lang.String" term="http://edamontology.org/data_2099"/>
+    </class>
+  </model>
+
+For a more complete example, see `FlyMine <http://www.flymine.org/flymine/service/model>`_ which covers many data types.
+
+For a detailed description of the data model, see :doc:`/data-model/model`.
+
+.. index:: model with ontology terms, data model with ontology terms

docs/data-model/model.rst

@@ -119,6 +119,8 @@ It's possible to decorate your InterMine data model with ontology terms.
 
 This isn't used anywhere (yet) but will be used in the future when we start generating RDF.
 
+See for :doc:`How to add ontology terms to your model </data-model/model-ontologies>` for details. 
+
 A short example
 -----------------------
 
@@ -127,8 +129,8 @@ A short example
   <?xml version="1.0"?>
   <model name="testing" package="org.intermine.model.bio">
 
-    <class name="Protein" is-interface="true">
-      <attribute name="name" type="java.lang.String"/>
+    <class name="Protein" is-interface="true" term="http://semanticscience.org/resource/SIO_010043">
+      <attribute name="name" type="java.lang.String" term="http://edamontology.org/data_2099"/>
       <attribute name="extraData" type="java.lang.String"/> 
       <collection name="features"  referenced-type="NewFeature" reverse-reference="protein"/>  
     </class>

docs/database/data-sources/data-licences.rst

@@ -3,27 +3,20 @@ Data Licences
 
 You are using InterMine to integrate several data sets into a single database, for ease of querying for your end users. It's important that you make it very clear to your users how the data in your mine is licenced and how it can be re-used.
 
-DataSet.licence
-----------------
+New DataSet.licence field
+--------------------------------
 
 In InterMine 4.0, we've added `licence` to the "data set" model as a text field. This column is meant to be a **URL** to point to the standard data licence, e.g. https://creativecommons.org/licenses/by/4.0/
 
 .. code-block:: xml
 
-    <!-- InterMine 4.0.0 -->
-    <class name="DataSet" is-interface="true" term="http://semanticscience.org/resource/SIO_000089">
-        <attribute name="description" type="java.lang.String" term="http://semanticscience.org/resource/SIO_000136"/>
+    <!-- InterMine 4.0.0 data model -->
+    <class name="DataSet" is-interface="true" term="http://semanticscience.org/resource/SIO_000089">        
         <!-- licence is a new text field -->
         <attribute name="licence" type="java.lang.String" term="http://purl.org/dc/terms/license"/>
-        <attribute name="url" type="java.lang.String" term="http://edamontology.org/data_1052"/>
-        <attribute name="name" type="java.lang.String" term="http://edamontology.org/data_2099"/>
-        <attribute name="version" type="java.lang.String" term="http://semanticscience.org/resource/SIO_000653"/>
-        <reference name="dataSource" referenced-type="DataSource" reverse-reference="dataSets"/>
-        <reference name="publication" referenced-type="Publication"/>
-        <collection name="bioEntities" referenced-type="BioEntity" reverse-reference="dataSets"/>
+        ...
     </class>
 
-
 How is this information being used?
 ------------------------------------
 
@@ -37,7 +30,7 @@ The contents of `DataSet.licence` should a URL that points to a standard data li
 Why can't I put a URL to the fair use policy?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you put a URL to the data source's fair use policy for example, the URL might change. Also, sometimes the fair use policy is vague, contradictory or just hard to understand. 
+If you put a URL to the data source's fair use policy for example, the URL might change. Also, sometimes the fair use policy is vague, contradictory or just hard to understand. It's better to only use standard data licences.
 
 Why can't I put a short snippet about the fair use policy for these data?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -80,6 +73,8 @@ FASTA
       ...
     </source>
 
+NB: The prefix has to match the `type` of the data source.
+
 OBO
 
 .. code-block:: xml