Ontology Notes

From NCBO Wiki
Jump to navigation Jump to search

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

  • Note: 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 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 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

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

A single 'New Term Proposal' note

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

A single 'Change Relationship/Hierarchy Proposal' note

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

A single 'Property Value Change Proposal' note

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

A nested thread of 'Comment' notes

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

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 W3C's documentation on HTTP methods.

Types of notes in BioPortal

The following are the types of notes in BioPortal. Please, email us at 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}&termdefinition={definition}&termparent={termparent}&termpreferredname={preferredname}&email={email_address}
  • Alt Signature (HTTP POST): ./notes/{ontology version id}?type=ProposalForCreateEntity&appliesto={appliestoid}&appliestotype=Ontology&subject={subject}&reasonforchange={reasonforchange}&author={author}&termdefinition={definition}&termparent={termparent}&termpreferredname={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

Retrieved from "https://www.bioontology.org//mediawiki/index.php?title=Ontology_Notes&oldid=12595"