PhenotypeLibrary is part of HADES

This document is a DRAFT guidance.

A submission to the OHDSI Phenotype Library is considered complete if it is accompanied by:

  • OHDSI forum post with the title that starts with ‘Phenotype submission -’ example: ‘Phenotype submission - Acute Hepatic Failure’
  • You have a clinical description conforming to the submission requirements.

Submission process

Post a new OHDSI Forum thread

  • A new thread on OHDSI forum. By default the original poster (op) will be considered the phenotype submitter.
  • General guidance for your forum post title.
    • Title of the thread: should start with ’Phenotype Submission - ’.
    • Examples of titles for the thread ‘Phenotype submission - Acute Hepatic Failure’
    • This name has two parts -
      • Prefix: ‘Phenotype submission -’ This prefix in your title makes it easier for reviewers to review your work, provide their feedback and for your contribution to make its way to the OHDSI Phenotype Library.
      • Phenotype Name: The phenotype name is expected to be a meaningful but succinct name. It should try to capture some of the key dimensions of the clinical idea e.g. in the name ‘Acute Hepatic Failure among persons with no pre-existing liver disease’. This name conveys that the clinical idea is ‘Acute’. It also tells us that there are exclusions for persons with pre-existing liver disease. Another example is ‘events of pneumonia’. Here the word ‘events’ tells us that a person may have more than one event of pneumonia.
      • Note: among OHDSI Phenotype typers, some words have key meaning - please review Reserved words with special meaning to Phentoypers. If you use those words, please ensure your intention aligns with this document.
      • Your submission is identified by your forum title. So a good name will help the community volunteer reviewers find your submission and promptly respond to it.
  • Phenotype names are necessarily short. As a result, it may not convey the full clinical meaning and can be ambiguous. That’s one reason we ask that your submission be accompanied by a clinical description, that provides the additional information needed to fully describe the clinical idea.

Start your post with a clinical description

  • Clinical Description is required for peer review.
  • The motivation behind starting out with a clinical description is so that everyone has a shared understanding of the clinical phenotype i.e. what are the expected characteristics of the persons we are identifying from the data source. This step not only clarifies the clinical idea, but also helps justify why certain decisions were made during the cohort definition development (build) process, and also provides context to the persons who might be interpreting the results of a study that used the phenotype.

Please see article Guidelines on writing clinical description for Condition Phenotypes

Literature Review

  • Literature review is required for peer review.
  • See
  • In OHDSI we like to learn from and improve the work of others. Performing a literature review to understand what others have done for this phenotype is considered best practice.
  • There is no fixed format for submission of literature review, but we expect that if your submission is based on literature review, you give references to (do not attach original articles) in the same thread and summarize the key salient information from the publication that may inform OHDSI phenotyping.

Please see article Guidelines on Literature Review

Logic Description

  • Logic description is required for peer review.
  • We recommend you write a logic description prior to beginning phenotyping. It is written after clinical description is complete.
  • The logic description would follow the structure of building cohort definitions in Atlas, but without the full details. It is expected to succint.
  • We have experienced that taking this approach improves the quality of your cohort definitions, reduces bugs in your cohort definition and allows to build cohort definitions collaboratively.
  • It is also a required element for peer-review, as a logic description indicates to the peer reviewers that the rules implemented in Atlas are deliberate design choices and not an unintentional accident (i.e. bug).

Please see article Guidelines on writing Cohort Definition Logic Description

Having followed OHDSI Best practices and gone through development/evaluation iteration

Published Cohort Diagnostics output on one or more data sources

heValuator and other evaluation/validation metrics as applicable.

Discuss your evaluation/validation findings on

Insights on sensitivity, specificity and index date mis-classification errors

Attach ‘CohortDefinitionSet’ R object.

For importing into

Please see article Guidelines on Cohort Definition Set R Object

Post submission

Validity Checks prior to consideration

  • Your submissions will be subjected to the following routine Validity Checks For CohortDefinitions
  • Your submission is expected to pass these tests prior to being posted into

Addition to [Atlas-phenotype] (

Assignment for Peer Review

  • OHDSI will perform on open peer review through the OHDSI Phenotype Development and Evaluation workgroup.
  • Workgroup members ill be assigned as peer reviewers. The peer review will be oral feedback followed by a recommendation.
  • The peer review will be video recorded and the recordings will be available in the workgroup archives.
  • It is up-to the submitter to then consider the peer review recommendations, make changes, or not.
  • Based on the decision of the peer reviewer(s) the cohort definition would be considered accepted.
  • Once accepted, the cohort definitions will be made immutable and a version number will be assigned to it. Key peer review notes will usually be referenced (commonly to the forum post).