OMOP/docs/cdmRequestProcess.html

740 lines
22 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<title> How to Request Changes to the CDM</title>
<script src="site_libs/header-attrs-2.25/header-attrs.js"></script>
<script src="site_libs/jquery-3.6.0/jquery-3.6.0.min.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link href="site_libs/bootstrap-3.3.5/css/cosmo.min.css" rel="stylesheet" />
<script src="site_libs/bootstrap-3.3.5/js/bootstrap.min.js"></script>
<script src="site_libs/bootstrap-3.3.5/shim/html5shiv.min.js"></script>
<script src="site_libs/bootstrap-3.3.5/shim/respond.min.js"></script>
<style>h1 {font-size: 34px;}
h1.title {font-size: 38px;}
h2 {font-size: 30px;}
h3 {font-size: 24px;}
h4 {font-size: 18px;}
h5 {font-size: 16px;}
h6 {font-size: 12px;}
code {color: inherit; background-color: rgba(0, 0, 0, 0.04);}
pre:not([class]) { background-color: white }</style>
<script src="site_libs/jqueryui-1.13.2/jquery-ui.min.js"></script>
<link href="site_libs/tocify-1.9.1/jquery.tocify.css" rel="stylesheet" />
<script src="site_libs/tocify-1.9.1/jquery.tocify.js"></script>
<script src="site_libs/navigation-1.1/tabsets.js"></script>
<link href="site_libs/highlightjs-9.12.0/default.css" rel="stylesheet" />
<script src="site_libs/highlightjs-9.12.0/highlight.js"></script>
<link href="site_libs/font-awesome-6.4.2/css/all.min.css" rel="stylesheet" />
<link href="site_libs/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet" />
<link rel='shortcut icon' type='image/x-icon' href='favicon.ico' />
<style type="text/css">
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block; vertical-align: top; width: 50%;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
ul.task-list{list-style: none;}
</style>
<style type="text/css">code{white-space: pre;}</style>
<script type="text/javascript">
if (window.hljs) {
hljs.configure({languages: []});
hljs.initHighlightingOnLoad();
if (document.readyState && document.readyState === "complete") {
window.setTimeout(function() { hljs.initHighlighting(); }, 0);
}
}
</script>
<link rel="stylesheet" href="style.css" type="text/css" />
<style type = "text/css">
.main-container {
max-width: 940px;
margin-left: auto;
margin-right: auto;
}
img {
max-width:100%;
}
.tabbed-pane {
padding-top: 12px;
}
.html-widget {
margin-bottom: 20px;
}
button.code-folding-btn:focus {
outline: none;
}
summary {
display: list-item;
}
details > summary > p:only-child {
display: inline;
}
pre code {
padding: 0;
}
</style>
<style type="text/css">
.dropdown-submenu {
position: relative;
}
.dropdown-submenu>.dropdown-menu {
top: 0;
left: 100%;
margin-top: -6px;
margin-left: -1px;
border-radius: 0 6px 6px 6px;
}
.dropdown-submenu:hover>.dropdown-menu {
display: block;
}
.dropdown-submenu>a:after {
display: block;
content: " ";
float: right;
width: 0;
height: 0;
border-color: transparent;
border-style: solid;
border-width: 5px 0 5px 5px;
border-left-color: #cccccc;
margin-top: 5px;
margin-right: -10px;
}
.dropdown-submenu:hover>a:after {
border-left-color: #adb5bd;
}
.dropdown-submenu.pull-left {
float: none;
}
.dropdown-submenu.pull-left>.dropdown-menu {
left: -100%;
margin-left: 10px;
border-radius: 6px 0 6px 6px;
}
</style>
<script type="text/javascript">
// manage active state of menu based on current page
$(document).ready(function () {
// active menu anchor
href = window.location.pathname
href = href.substr(href.lastIndexOf('/') + 1)
if (href === "")
href = "index.html";
var menuAnchor = $('a[href="' + href + '"]');
// mark the anchor link active (and if it's in a dropdown, also mark that active)
var dropdown = menuAnchor.closest('li.dropdown');
if (window.bootstrap) { // Bootstrap 4+
menuAnchor.addClass('active');
dropdown.find('> .dropdown-toggle').addClass('active');
} else { // Bootstrap 3
menuAnchor.parent().addClass('active');
dropdown.addClass('active');
}
// Navbar adjustments
var navHeight = $(".navbar").first().height() + 15;
var style = document.createElement('style');
var pt = "padding-top: " + navHeight + "px; ";
var mt = "margin-top: -" + navHeight + "px; ";
var css = "";
// offset scroll position for anchor links (for fixed navbar)
for (var i = 1; i <= 6; i++) {
css += ".section h" + i + "{ " + pt + mt + "}\n";
}
style.innerHTML = "body {" + pt + "padding-bottom: 40px; }\n" + css;
document.head.appendChild(style);
});
</script>
<!-- tabsets -->
<style type="text/css">
.tabset-dropdown > .nav-tabs {
display: inline-table;
max-height: 500px;
min-height: 44px;
overflow-y: auto;
border: 1px solid #ddd;
border-radius: 4px;
}
.tabset-dropdown > .nav-tabs > li.active:before, .tabset-dropdown > .nav-tabs.nav-tabs-open:before {
content: "\e259";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li.active:before {
content: "\e258";
font-family: 'Glyphicons Halflings';
border: none;
}
.tabset-dropdown > .nav-tabs > li.active {
display: block;
}
.tabset-dropdown > .nav-tabs > li > a,
.tabset-dropdown > .nav-tabs > li > a:focus,
.tabset-dropdown > .nav-tabs > li > a:hover {
border: none;
display: inline-block;
border-radius: 4px;
background-color: transparent;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open > li {
display: block;
float: none;
}
.tabset-dropdown > .nav-tabs > li {
display: none;
}
</style>
<!-- code folding -->
<style type="text/css">
#TOC {
margin: 25px 0px 20px 0px;
}
@media (max-width: 768px) {
#TOC {
position: relative;
width: 100%;
}
}
@media print {
.toc-content {
/* see https://github.com/w3c/csswg-drafts/issues/4434 */
float: right;
}
}
.toc-content {
padding-left: 30px;
padding-right: 40px;
}
div.main-container {
max-width: 1200px;
}
div.tocify {
width: 20%;
max-width: 260px;
max-height: 85%;
}
@media (min-width: 768px) and (max-width: 991px) {
div.tocify {
width: 25%;
}
}
@media (max-width: 767px) {
div.tocify {
width: 100%;
max-width: none;
}
}
.tocify ul, .tocify li {
line-height: 20px;
}
.tocify-subheader .tocify-item {
font-size: 0.90em;
}
.tocify .list-group-item {
border-radius: 0px;
}
</style>
</head>
<body>
<div class="container-fluid main-container">
<!-- setup 3col/9col grid for toc_float and main content -->
<div class="row">
<div class="col-xs-12 col-sm-4 col-md-3">
<div id="TOC" class="tocify">
</div>
</div>
<div class="toc-content col-xs-12 col-sm-8 col-md-9">
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-bs-toggle="collapse" data-target="#navbar" data-bs-target="#navbar">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html"><div><img src="ohdsi16x16.png"></img> OMOP Common Data Model </div></a>
</div>
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li>
<a href="index.html">
<span class="fa fa-house"></span>
</a>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-landmark"></span>
Background
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="background.html">Model Background</a>
</li>
<li>
<a href="cdmRefreshProcess.html">CDM Refresh Process</a>
</li>
<li>
<a href="vocabulary.html">How the Vocabulary is Built</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-list-alt"></span>
Conventions
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="dataModelConventions.html">General Conventions</a>
</li>
<li>
<a href="ehrObsPeriods.html">Observation Periods for EHR Data</a>
</li>
<li>
<a href="cdmPrivacy.html">Patient Privacy and OMOP</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-history"></span>
CDM Versions
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="cdm30.html">CDM v3.0</a>
</li>
<li>
<a href="cdm53.html">CDM v5.3</a>
</li>
<li class="dropdown-submenu">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">CDM v5.4</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="cdm54.html">CDM v5.4</a>
</li>
<li>
<a href="cdm54Changes.html">Changes from CDM v5.3</a>
</li>
<li>
<a href="cdm54erd.html">Entity Relationships</a>
</li>
<li>
<a href="cdm54ToolingSupport.html">Detailed tooling support per CDM field</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-plus-square"></span>
CDM Proposals
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="cdmRequestProcess.html">How to Propose Changes to the CDM</a>
</li>
<li>
<a href="https://github.com/OHDSI/CommonDataModel/issues?q=is%3Aopen+is%3Aissue+label%3AProposal">Under Review</a>
</li>
<li class="dropdown-submenu">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">Accepted</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="https://github.com/OHDSI/CommonDataModel/issues/252">Region_concept_id</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-question"></span>
How to
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="download.html">Download the DDL</a>
</li>
<li>
<a href="cdmRPackage.html">Use the CDM R Package</a>
</li>
<li>
<a href="drug_dose.html">Calculate Drug Dose</a>
</li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" data-bs-toggle="dropdown" aria-expanded="false">
<span class="fa fa-life-ring"></span>
Support
<span class="caret"></span>
</a>
<ul class="dropdown-menu" role="menu">
<li>
<a href="cdmDecisionTree.html">Help! My Data Doesn't Fit!</a>
</li>
<li>
<a href="faq.html">FAQ</a>
</li>
<li>
<a href="sqlScripts.html">SQL Scripts</a>
</li>
<li>
<a href="contribute.html">Ask a Question</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav navbar-right">
<li>
<a href="https://github.com/OHDSI/CommonDataModel">
<span class="fa fa-github"></span>
</a>
</li>
</ul>
</div><!--/.nav-collapse -->
</div><!--/.container -->
</div><!--/.navbar -->
<div id="header">
<h1 class="title toc-ignore"><img src="ohdsi40x40.png"></img> How to
Request Changes to the CDM</h1>
</div>
<p>Are you in the right place? Please answer the questions in the <a
href="cdmDecisionTree.html">decision tree</a> prior to beginning a CDM
Request to make sure you arent missing something.</p>
<p>As OHDSI is an open-source community working towards developing a
Common Data Model that fulfills the needs of its users, it is often the
case that changes need to be made to the model as the community and its
research continues to mature. However, the number of people,
institutions, and initiatives that rely on the OMOP CDM to advance the
science of observational health has grown dramatically since its
inception in 2015. Therefore, care must be taken when considering any
update to the model, big or small. This document outlines the process
that should be taken to ratify a change to the CDM.</p>
<p><strong>If you would like guidance prior to starting this process,
consider contacting us on our <a
href="https://github.com/OHDSI/CommonDataModel">GitHub</a> or <a
href="https://teams.microsoft.com/l/team/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/conversations?groupId=a6f2c516-e568-4974-8f1e-a7bdc2f997c5&amp;tenantId=a30f0094-9120-4aab-ba4c-e5509023b2d5">Teams
Channel</a>.</strong></p>
<div id="scope" class="section level3">
<h3>Scope</h3>
<ul>
<li>What kind of changes?
<ul>
<li>Minor, e.g. new field in existing table</li>
<li>Major, e.g. breaking changes, additional tables</li>
</ul></li>
<li>Who can propose changes?
<ul>
<li>Individuals, OHDSI working groups, organizations</li>
</ul></li>
</ul>
</div>
<div id="step-1-proposal" class="section level2">
<h2>Step 1: Proposal</h2>
<p>Once a group or organization has decided on the update they would
like made to the model, they must produce a document including the
following:</p>
<ol style="list-style-type: decimal">
<li>A clear description of the change or addition including the User
Guide and ETL Conventions in the same structure as what is present on
the website for every table and field currently in the CDM.</li>
<li>A clearly defined use case noting why the latest version of the OMOP
CDM fails to adequately address said use case. This should include
describing what you have already tried with the latest version of the
OMOP CDM and why it does not meet your needs.</li>
<li>An example of how the requested change or addition will be used in
practice. This can be in the form of sample data, SQL code, a diagram,
or text. The proposal can optionally include suggestions as to how other
OHDSI tools (Achilles, DataQualityDashboard, Atlas, etc.) should work
with your change or addition.</li>
</ol>
<p>Once the document is ready to submit, please email <a
href="mailto:a58abde7.ohdsi.org@amer.teams.ms">CDM Proposals - Workgroup
- Common Data Model</a>. This will go directly to a separate channel in
the OHDSI Teams environment that is available to all members of the CDM
Working Group. After submitting your document with your proposal to
email listed above, someone in the OMOP CDM Working Group will respond
to you within 2 weeks. The potential outcomes are as follows:</p>
<ul>
<li>Proposal merits further review (move on to next steps)</li>
<li>Proposal is not ready for workgroup review due to one or more
factors
<ul>
<li>Incomplete</li>
<li>Insufficiently aligned with the OMOP framework</li>
<li>Poorly described use case</li>
</ul></li>
</ul>
</div>
<div id="step-2-initial-presentation" class="section level2">
<h2>Step 2: Initial Presentation</h2>
<p>Should your proposals merit further review, the OMOP CDM Working
Group will reach out to you to schedule a time for you to present your
case at an upcoming meeting. You will be given 15-30 minutes to present
your document and you can include anything you feel will help illustrate
the need and your potential solution. The group will then discuss, ask
questions, and potentially offer other solutions. Depending on the
nature of the request, this may go over multiple sessions and you may be
asked to make changes to your initial design. At the end of this process
your proposal will then be put to consensus in the CDM WG. If the group
decides no, they will give feedback describing why they did not feel
your proposal should be accepted at this time. If the group decides yes,
you move on to step 3.</p>
<p><strong>Potential Decision Criteria:</strong></p>
<ul>
<li>If the change is foundational to OHDSI tools, then the proposal will
be put to the larger community open to public comment</li>
<li>How generalizable is your change? Can it be readily applied to other
use cases?</li>
<li>Are the proposed changes/additions well designed from a modeling
perspective? Do they follow the existing OMOP CDM conventions?</li>
<li>What are the consequences of the change? Are they potentially
breaking changes or are they just changes to existing conventions? Will
they require the remapping of existing OMOP datasources?</li>
<li>How complicated is your change? Is it an addition of a field or
multiple tables?</li>
</ul>
</div>
<div id="step-3-preliminary-decision" class="section level2">
<h2>Step 3: Preliminary Decision</h2>
<p>If the proposal is accepted in the preliminary decision, then a
branch will be created in the CommonDataModel repository, based on the
latest version of the OMOP CDM in use (currently v5.4). It will then be
your responsibility to apply the change programmatically in this branch.
This should include:</p>
<ul>
<li>Updating the CSV file with the CDM specification, including the User
Guide and ETL Conventions documentation</li>
<li>Generating the DDL files with the change</li>
<li>Testing the new DDL files in at least one supported environment</li>
</ul>
<p>Once the DDLs with the proposed change are created and tested, you
should then ETL some data (either real or synthetic) into the new
table/fields. Then, an example cohort should be created that utilizes
the change or addition and clearly displays how it can be used in a real
study. It is expected that during this stage the proposal will change as
you work through your idea in a tangible environment.</p>
<p><strong>Potential Decision Criteria:</strong></p>
<ul>
<li>How would you evaluate the quality of this new field/table?</li>
<li>What characterizations would you perform?</li>
<li>How would you perform a study using this new feature?</li>
</ul>
<p><strong>Potential Outcomes:</strong></p>
<ul>
<li>Proposal demonstrates merit for further consideration as:
<ul>
<li>a core data model change (move on to next steps)</li>
<li>an extension (how do we deal with these/do we have ownership of
them?)</li>
</ul></li>
<li>Proposal does not demonstrate merit for further consideration at
this time, and:
<ul>
<li>recommend as a LOCAL extension</li>
<li>recommend a different course</li>
</ul></li>
</ul>
</div>
<div id="step-4-final-presentation" class="section level2">
<h2>Step 4: Final Presentation</h2>
<p>After generating, testing, and implementing your proposal in a
real-world environment the CDM working group will invite you again to
present your findings in another 15-30 minute presentation. This should
include learnings from the exercise and any updates made to the initial
proposal.</p>
</div>
<div id="step-5-final-decision" class="section level2">
<h2>Step 5: Final Decision</h2>
<p>At this point, the working group liaisons will also take the proposal
to other groups to elicit feedback. Then the CDM working group will vote
and give a final decision on the proposed change. If ratified, the
branch in the repository will be merged into the develop branch to be
included in a next version of the OMOP Common Data Model.</p>
<p>The change should initiate requests for features in tools. The end of
this process should be a trigger for using the new feature as per the
use case. The group should also produce at least one query for the query
library on how to work with the new addition/change.</p>
<div id="resources" class="section level3">
<h3>Resources</h3>
<p>“Implementing &amp; adopting a customized OMOP Common Data Model”
(Melany Philofsky, OHDSI Symposium 2021) <a
href="https://www.ohdsi.org/2021-global-symposium-showcase-18/"
class="uri">https://www.ohdsi.org/2021-global-symposium-showcase-18/</a></p>
</div>
</div>
</div>
</div>
</div>
<script>
// add bootstrap table styles to pandoc tables
function bootstrapStylePandocTables() {
$('tr.odd').parent('tbody').parent('table').addClass('table table-condensed');
}
$(document).ready(function () {
bootstrapStylePandocTables();
});
</script>
<!-- tabsets -->
<script>
$(document).ready(function () {
window.buildTabsets("TOC");
});
$(document).ready(function () {
$('.tabset-dropdown > .nav-tabs > li').click(function () {
$(this).parent().toggleClass('nav-tabs-open');
});
});
</script>
<!-- code folding -->
<script>
$(document).ready(function () {
// temporarily add toc-ignore selector to headers for the consistency with Pandoc
$('.unlisted.unnumbered').addClass('toc-ignore')
// move toc-ignore selectors from section div to header
$('div.section.toc-ignore')
.removeClass('toc-ignore')
.children('h1,h2,h3,h4,h5').addClass('toc-ignore');
// establish options
var options = {
selectors: "h1,h2,h3",
theme: "bootstrap3",
context: '.toc-content',
hashGenerator: function (text) {
return text.replace(/[.\\/?&!#<>]/g, '').replace(/\s/g, '_');
},
ignoreSelector: ".toc-ignore",
scrollTo: 0
};
options.showAndHide = true;
options.smoothScroll = true;
// tocify
var toc = $("#TOC").tocify(options).data("toc-tocify");
});
</script>
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
(function () {
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML";
document.getElementsByTagName("head")[0].appendChild(script);
})();
</script>
</body>
</html>