OMOP/docs/cdmRequestProcess.html

666 lines
21 KiB
HTML
Raw Normal View History

2022-07-25 19:27:08 +00:00
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta http-equiv="X-UA-Compatible" content="IE=EDGE" />
<title>cdmRequestProcess.knit</title>
<script src="site_libs/header-attrs-2.13/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.11.4/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-5.1.0/css/all.css" rel="stylesheet" />
<link href="site_libs/font-awesome-5.1.0/css/v4-shims.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 it active
menuAnchor.tab('show');
// if it's got a parent navbar menu mark it active as well
menuAnchor.closest('li.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 {
content: "";
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: "&#xe258;";
border: none;
}
.tabset-dropdown > .nav-tabs.nav-tabs-open:before {
content: "";
font-family: 'Glyphicons Halflings';
display: inline-block;
padding: 10px;
border-right: 1px solid #ddd;
}
.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-home"></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="cdm60.html">CDM v6.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">NEW 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>
</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"><div>
<img src="ohdsi40x40.png"></img> How to Request Changes to the CDM
</div></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>
2022-07-27 01:48:28 +00:00
<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>
2022-07-25 19:27:08 +00:00
<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>