Phenotips HPO TermRequester

This service is designed to request that new phenotypes be added to the HPO and give a handle to requested phenotypes whilst they're being considered for inclusion. Each request is posted to the Github repo via Github API in a form of a separate issue that will be automatically tagged as “autorequested” tag and SUBMITTED status. Decisions may be made regarding the inclusion/exclusion of the submitted term via follow-up manual review, which should be done by editing the payload of the ticket, i.e. applying one of the available tags.

REST API

DATA STRUCTURES

phenotype

{
  'id': 'TEMPHPO_...',           /* The id of this phenotype within the request service */
  'name': '...',
  'status': '...', /* See the status below */
  'synonyms': ['...', '...', ],
  'description': '...',
  'issueNumber': '...',           /* The github issue number in the HPO's github */
  'parents': ['...', ], /* The ids of this phenotype's parents */
  'hpoId': '...', /* The id of the term in the HPO. Non-null iff status == ACCEPTED */
}

status

One of:

• SUBMITTED
• REJECTED
• ACCEPTED
• PUBLISHED

CREATE

POST /phenotypes

Create a new phenotype request. If one already exists with that same name or as a synonym of this one, none will be created, and the previously existing one will be returned.

Parameters

A Phenotype object, missing the id, status, issueNumber and hpoId fields.

{
  'name': '...',
  'synonyms': ['...', '...', ],
  'description': '...',
  'parents': ['...', '...', ],
}

Response

If the phenotype has already been requested, the response code will be HTTP 409. Otherwise it will be HTTP 201.

In either case the new (or previously existing) phenotype will be returned (see above for phenotype object format).

READ

GET /phenotype/{id}

Where id is either a TEMPHPO_ style id or an HP_ type id.

Response

If the phenotype exists and is not in PUBLISHED status, it will be returned.

If the phenotype exists but is in PUBLISHED status, a truncated version of it will be returned, containing only the hpoId of the phenotype.

If the phenotype does not exist, an HTTP 404 will be returned.

If the id is malformed, an HTTP 400 will be returned.

Note that the returned Phenotype may have a different id or hpoId than that requested, since it might have been accepted as a synonym of a different phenotype.

GET /phenotypes

Search the phenotypes that match a given text.

Parameters

{
  'text': '...',
}

Response

[{...}, ...] /* the results as phenotype instances */

CONFIGURATION

In order to run the webapp, you need to edit its web.xml. In particular, these parameters must be set on the TermRequester servlet:

    <init-param>
      <param-name>org.phenotips.termrequester.repositoryOwner</param-name>
      <param-value></param-value>
    </init-param>
    <init-param>
      <param-name>org.phenotips.termrequester.repositoryName</param-name>
      <param-value></param-value>
    </init-param>
    <init-param>
      <param-name>org.phenotips.termrequester.oauthToken</param-name>
      <param-value></param-value>
    </init-param>
    <init-param>
      <param-name>org.phenotips.termrequester.homeDir</param-name>
      <param-value></param-value>
    </init-param>

The repositoryOwner is the owner of the repo issues will be posted to. For example, if posting to https://github.com/phenotips/termrequester/ the owner would be set to phenotips.

The repositoryName is the name of the repo; in this example termrequester.

The oauthToken is the token for the account that will be opening the issue. (Can be obtained from https://github.com/settings/tokens).

The homeDir is a path on the server to store local data for example /var/lib/termRequester).

DEVELOPMENT

To develop for the termrequester, you should:

• build and install the phenotips variant store
• populate backend/src/test/resources/org/phenotips/termrequester/github/credentials.properties by copying credentials.template.properties in that same directory

HPO Communication Spec

To simplify automatic interaction with github, the tool adheres to a few standards:

• The issue body of tool-opened issues will match the following format:

TERM: ...
SYNONYMS: ...
PARENTS: ...
DESCRIPTION: ...
HPO_ID: ...
This issue was autogenerated by phenotips.org

With HPO_ID initially being populated as NONE.

• Accepted phenotypes should be given the label acceptedautorequest
• Phenotypes accepted as synonyms of others should be given the label synonymautorequest
• The issue body for accepted phenotypes should be modified to match the eventual format of the accepted phenotype. Thus, for example, the DESCRIPTION: line should be changed to reflect the description of the newly added term in the HPO. Importantly, the HPO_ID: line should be populated by the id of the new term.
• Rejected phenotypes should be given the label rejectedautorequest
• Once a version of the HPO is released that contains a given acceptedautorequest labeled phenotype, said phenotype should have its label changed to publishedautorequest