From 888c87383e771d6cde435dc60f0a435b59e26040 Mon Sep 17 00:00:00 2001 From: Clair Blacketer Date: Mon, 25 Jul 2022 15:27:08 -0400 Subject: [PATCH] Adding Decision Tree --- docs/cdmDecisionTree.html | 472 +++++++++++++++++++++++++ docs/cdmRefreshProcess.html | 49 +-- docs/cdmRequestProcess.html | 665 ++++++++++++++++++++++++++++++++++++ docs/contactVocab.html | 469 +++++++++++++++++++++++++ docs/leaveAsIs.html | 467 +++++++++++++++++++++++++ docs/localChange.html | 467 +++++++++++++++++++++++++ docs/useCaseN.html | 469 +++++++++++++++++++++++++ docs/useCaseY.html | 470 +++++++++++++++++++++++++ docs/vocabN.html | 469 +++++++++++++++++++++++++ docs/vocabRequest.html | 469 +++++++++++++++++++++++++ docs/vocabY.html | 468 +++++++++++++++++++++++++ rmd/.Rapp.history | 2 + rmd/_site.yml | 6 +- rmd/cdmDecisionTree.Rmd | 13 + rmd/cdmRefreshProcess.Rmd | 20 +- rmd/cdmRequestProcess.Rmd | 91 +++++ rmd/contactVocab.Rmd | 10 + rmd/index.Rmd | 2 +- rmd/leaveAsIs.Rmd | 6 + rmd/localChange.Rmd | 6 + rmd/useCaseN.Rmd | 10 + rmd/useCaseY.Rmd | 13 + rmd/vocabN.Rmd | 10 + rmd/vocabRequest.Rmd | 10 + rmd/vocabY.Rmd | 8 + 25 files changed, 5111 insertions(+), 30 deletions(-) create mode 100644 docs/cdmDecisionTree.html create mode 100644 docs/cdmRequestProcess.html create mode 100644 docs/contactVocab.html create mode 100644 docs/leaveAsIs.html create mode 100644 docs/localChange.html create mode 100644 docs/useCaseN.html create mode 100644 docs/useCaseY.html create mode 100644 docs/vocabN.html create mode 100644 docs/vocabRequest.html create mode 100644 docs/vocabY.html create mode 100644 rmd/cdmDecisionTree.Rmd create mode 100644 rmd/cdmRequestProcess.Rmd create mode 100644 rmd/contactVocab.Rmd create mode 100644 rmd/leaveAsIs.Rmd create mode 100644 rmd/localChange.Rmd create mode 100644 rmd/useCaseN.Rmd create mode 100644 rmd/useCaseY.Rmd create mode 100644 rmd/vocabN.Rmd create mode 100644 rmd/vocabRequest.Rmd create mode 100644 rmd/vocabY.Rmd diff --git a/docs/cdmDecisionTree.html b/docs/cdmDecisionTree.html new file mode 100644 index 0000000..9feb8c7 --- /dev/null +++ b/docs/cdmDecisionTree.html @@ -0,0 +1,472 @@ + + + + + + + + + + + + + +cdmDecisionTree.knit + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

If you have arrived to this page then you must be thinking HELP! I have some data that doesn’t fit in the CDM! Never fear as this handy guide will point you in the right direction and all you have to do is answer a few questions.

+

First things first, do you have a documented network use case for this data? This could take the form of an upcoming study or a convention for how to store information. In this scenario, at least two or more collaborators with data to contribute constitute a network need.

+

Yes, I have a network use case

+

No, I do not have a network use case

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/cdmRefreshProcess.html b/docs/cdmRefreshProcess.html index cdf8a99..b437a9b 100644 --- a/docs/cdmRefreshProcess.html +++ b/docs/cdmRefreshProcess.html @@ -13,7 +13,7 @@ cdmRefreshProcess.knit - + @@ -63,6 +63,7 @@ if (window.hljs) { + @@ -88,6 +89,9 @@ button.code-folding-btn:focus { summary { display: list-item; } +details > summary > p:only-child { + display: inline; +} pre code { padding: 0; } @@ -312,7 +316,7 @@ div.tocify { + + + + +

Are you in the right place? Please answer the questions in the decision tree prior to beginning a CDM Request to make sure you aren’t missing something.

+

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.

+

If you would like guidance prior to starting this process, consider contacting us on our GitHub or Teams Channel.

+
+

Scope

+ +
+
+

Step 1: Proposal

+

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:

+
    +
  1. 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.
    2. +
  2. 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.
    3. +
  3. 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.
    4. +
+

Once the document is ready to submit, please email CDM Proposals - Workgroup - Common Data Model. 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:

+ +
+
+

Step 2: Initial Presentation

+

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.

+

Potential Decision Criteria:

+ +
+
+

Step 3: Preliminary Decision

+

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:

+ +

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.

+

Potential Decision Criteria:

+ +

Potential Outcomes:

+ +
+
+

Step 4: Final Presentation

+

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.

+
+
+

Step 5: Final Decision

+

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.

+

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.

+
+

Resources

+

“Implementing & adopting a customized OMOP Common Data Model” (Melany Philofsky, OHDSI Symposium 2021) https://www.ohdsi.org/2021-global-symposium-showcase-18/

+
+
+ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/contactVocab.html b/docs/contactVocab.html new file mode 100644 index 0000000..5aa5c7a --- /dev/null +++ b/docs/contactVocab.html @@ -0,0 +1,469 @@ + + + + + + + + + + + + + +Contact the Vocab Team + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Okay so you have something you would like to add to the CDM but there is not an existing OMOP vocabulary nor an open-source vocabulary we can bring in to support it. In this case, please contact the vocabulary team on next steps as data elements in the CDM must have a vocabulary in place before they can be implemented.

+

Vocabulary Teams Channel

+

Once you come to consensus with the vocabulary team regarding your needs, please follow the CDM Request Process to begin the steps soliciting a change or addition to the model itself. Need more guidance? Consider contacting the CDM Working Group on our GitHub or Teams Channel.

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/leaveAsIs.html b/docs/leaveAsIs.html new file mode 100644 index 0000000..1feb8db --- /dev/null +++ b/docs/leaveAsIs.html @@ -0,0 +1,467 @@ + + + + + + + + + + + + + +Leave As Is + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Okay, so you do not have a network use case but multiple collaborators have access to the element you are interested in adding to the CDM. In this circumstance, the CDM Working Group suggests leaving the model as-is. Without a network use case there is no need to augment the data model. If this is something you need for your work, consider a local change or a model extension.

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/localChange.html b/docs/localChange.html new file mode 100644 index 0000000..247f9e8 --- /dev/null +++ b/docs/localChange.html @@ -0,0 +1,467 @@ + + + + + + + + + + + + + +Local Change + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Since you do not have a network use case and this element is specific to your data source, feel free to create a local change to your instance of the OMOP Common Data Model. Augmenting the model at your institution for administrative purposes or other in-house needs is totally acceptable with the understanding that any local changes cannot and should not be relied upon in network studies or supported by the open-source tools.

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/useCaseN.html b/docs/useCaseN.html new file mode 100644 index 0000000..2d0af16 --- /dev/null +++ b/docs/useCaseN.html @@ -0,0 +1,469 @@ + + + + + + + + + + + + + +Local Data + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Okay, so you don’t have a network use case. Is this data element specific to your data source, or are there others in the community who might also have this data but don’t yet need it for a study or data model convention?

+

Yes, this element is specific to my data source

+

No, there are others in the community who also have this data

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/useCaseY.html b/docs/useCaseY.html new file mode 100644 index 0000000..f0f2c78 --- /dev/null +++ b/docs/useCaseY.html @@ -0,0 +1,470 @@ + + + + + + + + + + + + + +OMOP Vocabulary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Great, you have a network use case!

+

Next question: Is there an existing OMOP vocabulary to support this new element? If you are unsure, feel free to check Athena.

+

Yes, I have all the required vocabulary I need

+

No, I there is not an existing OMOP vocabulary to support my request

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/vocabN.html b/docs/vocabN.html new file mode 100644 index 0000000..f832692 --- /dev/null +++ b/docs/vocabN.html @@ -0,0 +1,469 @@ + + + + + + + + + + + + + +Open Source Vocabulary + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Okay, so you have a use case but you don’t have an OMOP vocabulary to support your need. Is there an existing open-source (not proprietary or custom) vocabulary that has not yet been incorporated into the OMOP vocabulary?

+

Yes, the vocabulary exists, it just needs to be brought in

+

No, there is no open-source vocabulary for this data element

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/vocabRequest.html b/docs/vocabRequest.html new file mode 100644 index 0000000..ede123f --- /dev/null +++ b/docs/vocabRequest.html @@ -0,0 +1,469 @@ + + + + + + + + + + + + + +Vocabulary Request + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Okay so you have something you would like to add to the CDM and there is an existing OMOP vocabulary we can bring in to support it. In this case, please open an issue on the vocabulary github with the details of what you need added as data elements in the CDM must have a vocabulary in place before they can be implemented. The team will follow up with you should they need additional information.

+

Vocabulary GitHub Issue Tracker

+

Once that request is made, please follow the CDM Request Process to begin the steps soliciting a change or addition to the model itself. Need more guidance? Consider contacting the CDM Working Group on our GitHub or Teams Channel.

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/docs/vocabY.html b/docs/vocabY.html new file mode 100644 index 0000000..f32dedb --- /dev/null +++ b/docs/vocabY.html @@ -0,0 +1,468 @@ + + + + + + + + + + + + + +Request Process + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + + + + + + + + +

Great, so you have a network use case and an existing OMOP Vocabulary! From here, please follow the steps to formally request a change to the OMOP Common Data Model.

+

CDM Request Process

+ + + + +
+ + + + + + + + + + + + + + + diff --git a/rmd/.Rapp.history b/rmd/.Rapp.history index 9052497..85b7cd5 100644 --- a/rmd/.Rapp.history +++ b/rmd/.Rapp.history @@ -1,2 +1,4 @@ setwd("/Users/clairblacketer/Documents/Github/CommonDataModel/rmd")# rmarkdown::render_site() +setwd("/Users/clairblacketer/Documents/Github/CommonDataModel/rmd")# +rmarkdown::render_site() diff --git a/rmd/_site.yml b/rmd/_site.yml index 27f67cb..680ecfd 100644 --- a/rmd/_site.yml +++ b/rmd/_site.yml @@ -48,9 +48,11 @@ navbar: href: cdm54.html - text: "Changes from CDM v5.3" href: cdm54Changes.html - - text: "Proposals" + - text: "CDM Proposals" icon: fa-plus-square menu: + - text: "How to Propose Changes to the CDM" + href: cdmRequestProcess.html - text: "Under Review" href: https://github.com/OHDSI/CommonDataModel/issues?q=is%3Aopen+is%3Aissue+label%3AProposal - text: "Accepted" @@ -69,6 +71,8 @@ navbar: - text: "Support" icon: fa-life-ring menu: + - text: "Help! My Data Doesn't Fit!" + href: cdmDecisionTree.html - text: "FAQ" href: faq.html - text: "SQL Scripts" diff --git a/rmd/cdmDecisionTree.Rmd b/rmd/cdmDecisionTree.Rmd new file mode 100644 index 0000000..a9b8707 --- /dev/null +++ b/rmd/cdmDecisionTree.Rmd @@ -0,0 +1,13 @@ +--- +title: '
CDM Request Decision Tree
' +output: + html_document +--- + +If you have arrived to this page then you must be thinking **HELP! I have some data that doesn't fit in the CDM!** Never fear as this handy guide will point you in the right direction and all you have to do is answer a few questions. + +**First things first, do you have a documented network use case for this data? This could take the form of an upcoming study or a convention for how to store information.** In this scenario, at least two or more collaborators with data to contribute constitute a network need. + +[Yes, I have a network use case](useCaseY.html) + +[No, I do not have a network use case](useCaseN.html) diff --git a/rmd/cdmRefreshProcess.Rmd b/rmd/cdmRefreshProcess.Rmd index 261d88a..f12f178 100644 --- a/rmd/cdmRefreshProcess.Rmd +++ b/rmd/cdmRefreshProcess.Rmd @@ -8,29 +8,31 @@ output: The OMOP Common Data Model is managed by the OHDSI CDM Working Group. The formal remit of the CDM Working Group (WG) is to hear proposals for change, ratifying only those with valid use cases and data to support them. Then, once ratified, these proposals are incorporated into the next version of the CDM. In the past, this was done by the WG alone. The group would invite others from around the community to present use cases for change and suggestions for improvement. The WG would then vote on the proposals and a new CDM version would be released after a certain period of time or if enough proposals were voted in. This approach worked when the community was smaller but as it is growing rapidly the CDM WG needed to adapt the refresh cycle such that everyone has an opportunity to weigh in on the proposed changes. +Looking to make a change or addition to the OMOP CDM? Please answer the questions in the [decision tree](cdmDecisionTree.html) to point you in the right direction. + ## CDM Refresh Cycle ![](images/CDM_refresh_cycle.png) -### 1. Define New Version [Completed for v5.4] +### 1. Define New Version -The image above describes the new CDM refresh cycle. It begins with **defining a new version**. This has been completed for the current cycle. Issues and proposals on the github were considered during a 4-hour workshop where it was decided the next CDM version will be CDM v5.4, building off of CDM v5.3. The group then participated in a rapid-fire voting activity to identify which changes should be incorporated into CDM v5.4. Any items that were not unanimously agreed upon were then discussed in small groups to hone the proposal and suggestions were presented back to the group. The final roadmap for CDM v5.4 can be found [here](https://github.com/OHDSI/CommonDataModel/projects/3). +The image above describes the new CDM refresh cycle. It begins with **defining a new version**. Proposals are heard over the course of a year according to the [CDM Request Process](cdmRequestProcess.html) and the ratified changes are added to the roadmap until such time that there are enough updates to warrant a new version of the model. -Looking to open a proposal to change or augment the CDM? Please open an [issue](https://github.com/OHDSI/CommonDataModel/issues) and use the **proposal template**. +Looking to open a proposal to change or augment the CDM? Please follow the questions in the [decision tree](cdmDecisionTree.html) to help you determine what you will need. -### 2. Sign off from Work Groups [Completed for v5.4] +### 2. Sign off from Work Groups Each member of the CDM WG is a liaison for another workgroup in the community. They are responsible for presenting the proposed changes to the CDM and collecting the feedback. This has resulted in very helpful suggestions from the EHR, Data Quality, Device, HADES, and ACHILLES groups. This outreach has proven to be very effective and should result in a very stable version. -### 3. Release DDLs +### 3. Release DDLs -After all changes and suggestions are agreed upon by the community and work groups the next step is to generate the DDLs. The CDM WG hosted a hackathon on August 18-19, 2021. During this time the group created an R package to automatically generate the DDLs and the code to instantiate an empty CDM instance. Changes were made to v5.3 to generate v5.4 and the repository was refactored. +After all changes and suggestions are agreed upon by the community and work groups the next step is to generate the DDLs. For example, the CDM WG hosted a hackathon on August 18-19, 2021. During this time the group created an R package to automatically generate the DDLs and the code to instantiate an empty CDM instance. Changes were made to v5.3 to generate v5.4 and the repository was refactored. -### 4. Software Update +### 4. Software Update There will be period of time once the DDLs are ready to allow the software and methods developers to prepare for the official release of the CDM. This is meant to serve as a buffer so that once the community starts adopting the new model, the tools and methods will be ready to support it. -### 5. Community Support +### 5. Community Support This is the final stage of the CDM refresh cycle. Once the DDLs are ready and the software and tools supports the new version, the CDM WG will work to help the community convert their data to the new model. @@ -39,7 +41,7 @@ This is the final stage of the CDM refresh cycle. Once the DDLs are ready and th The CDM working group meets the first and third Tuesday of the month. See below for links to the meetings. -**Every first Tuesday of the month at 1pm est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1601910741972?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%2281c21b6d-448d-4634-abbc-6b0962d1138a%22%7d) +**Every first Tuesday of the month at 10am est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1601910741972?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%2281c21b6d-448d-4634-abbc-6b0962d1138a%22%7d) **Every third Tuesday of the month at 1pm est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1611000164347?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%223c193b7f-c2ab-4bcf-b88c-f89a6b1fba38%22%7d) diff --git a/rmd/cdmRequestProcess.Rmd b/rmd/cdmRequestProcess.Rmd new file mode 100644 index 0000000..31c343e --- /dev/null +++ b/rmd/cdmRequestProcess.Rmd @@ -0,0 +1,91 @@ +--- +title: '
How to Request Changes to the CDM
' +output: + html_document: + toc: TRUE + toc_float: TRUE +--- + +Are you in the right place? Please answer the questions in the [decision tree](cdmDecisionTree.html) prior to beginning a CDM Request to make sure you aren't missing something. + +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. + +**If you would like guidance prior to starting this process, consider contacting us on our [GitHub](https://github.com/OHDSI/CommonDataModel) or [Teams Channel](https://teams.microsoft.com/l/team/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/conversations?groupId=a6f2c516-e568-4974-8f1e-a7bdc2f997c5&tenantId=a30f0094-9120-4aab-ba4c-e5509023b2d5).** + + +### Scope + +- What kind of changes? + - Minor, e.g. new field in existing table + - Major, e.g. breaking changes, additional tables +- Who can propose changes? + - Individuals, OHDSI working groups, organizations + +## Step 1: Proposal + +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: + +1. 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. +2. 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. +3. 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. + +Once the document is ready to submit, please email [CDM Proposals - Workgroup - Common Data Model](a58abde7.ohdsi.org@amer.teams.ms). 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: + +- Proposal merits further review (move on to next steps) +- Proposal is not ready for workgroup review due to one or more factors + - Incomplete + - Insufficiently aligned with the OMOP framework + - Poorly described use case + +## Step 2: Initial Presentation + +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. + +**Potential Decision Criteria:** + +- If the change is foundational to OHDSI tools, then the proposal will be put to the larger community open to public comment +- How generalizable is your change? Can it be readily applied to other use cases? +- Are the proposed changes/additions well designed from a modeling perspective? Do they follow the existing OMOP CDM conventions? +- 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? +- How complicated is your change? Is it an addition of a field or multiple tables? + +## Step 3: Preliminary Decision + +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: + +- Updating the CSV file with the CDM specification, including the User Guide and ETL Conventions documentation +- Generating the DDL files with the change +- Testing the new DDL files in at least one supported environment + +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. + +**Potential Decision Criteria:** + +- How would you evaluate the quality of this new field/table? +- What characterizations would you perform? +- How would you perform a study using this new feature? + +**Potential Outcomes:** + +- Proposal demonstrates merit for further consideration as: + - a core data model change (move on to next steps) + - an extension (how do we deal with these/do we have ownership of them?) +- Proposal does not demonstrate merit for further consideration at this time, and: + - recommend as a LOCAL extension + - recommend a different course + +## Step 4: Final Presentation + +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. + +## Step 5: Final Decision + +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. + +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. + +### Resources + +“Implementing & adopting a customized OMOP Common Data Model” (Melany Philofsky, OHDSI Symposium 2021) https://www.ohdsi.org/2021-global-symposium-showcase-18/ + diff --git a/rmd/contactVocab.Rmd b/rmd/contactVocab.Rmd new file mode 100644 index 0000000..d69af85 --- /dev/null +++ b/rmd/contactVocab.Rmd @@ -0,0 +1,10 @@ +--- +title: "Contact the Vocab Team" +output: html_document +--- + +Okay so you have something you would like to add to the CDM but there is not an existing OMOP vocabulary nor an open-source vocabulary we can bring in to support it. **In this case, please contact the vocabulary team on next steps** as data elements in the CDM must have a vocabulary in place before they can be implemented. + +[Vocabulary Teams Channel](https://teams.microsoft.com/l/channel/19%3a31208179438d45749ff484124e7b1e5e%40thread.tacv2/Vocabulary%2520Subgroup?groupId=a6f2c516-e568-4974-8f1e-a7bdc2f997c5&tenantId=a30f0094-9120-4aab-ba4c-e5509023b2d5) + +Once you come to consensus with the vocabulary team regarding your needs, please follow the [CDM Request Process](cdmRequestProcess.html) to begin the steps soliciting a change or addition to the model itself. Need more guidance? Consider contacting the CDM Working Group on our [GitHub](https://github.com/OHDSI/CommonDataModel) or [Teams Channel](https://teams.microsoft.com/l/team/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/conversations?groupId=a6f2c516-e568-4974-8f1e-a7bdc2f997c5&tenantId=a30f0094-9120-4aab-ba4c-e5509023b2d5). diff --git a/rmd/index.Rmd b/rmd/index.Rmd index e093c9e..1e26260 100644 --- a/rmd/index.Rmd +++ b/rmd/index.Rmd @@ -46,7 +46,7 @@ The CDM is managed by the OHDSI CDM Working Group. If you would like to join our The CDM working group meets the first and third Tuesday of the month. See below for links to the meetings. -**Every first Tuesday of the month at 1pm est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1601910741972?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%2281c21b6d-448d-4634-abbc-6b0962d1138a%22%7d) +**Every first Tuesday of the month at 10am est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1601910741972?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%2281c21b6d-448d-4634-abbc-6b0962d1138a%22%7d) **Every third Tuesday of the month at 1pm est** [Teams Meeting](https://teams.microsoft.com/l/meetup-join/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/1611000164347?context=%7b%22Tid%22%3a%22a30f0094-9120-4aab-ba4c-e5509023b2d5%22%2c%22Oid%22%3a%223c193b7f-c2ab-4bcf-b88c-f89a6b1fba38%22%7d) diff --git a/rmd/leaveAsIs.Rmd b/rmd/leaveAsIs.Rmd new file mode 100644 index 0000000..e4de014 --- /dev/null +++ b/rmd/leaveAsIs.Rmd @@ -0,0 +1,6 @@ +--- +title: "Leave As Is" +output: html_document +--- + +Okay, so you do not have a network use case but multiple collaborators have access to the element you are interested in adding to the CDM. **In this circumstance, the CDM Working Group suggests leaving the model as-is.** Without a network use case there is no need to augment the data model. If this is something you need for your work, consider a [local change](localChange.html) or a model extension. diff --git a/rmd/localChange.Rmd b/rmd/localChange.Rmd new file mode 100644 index 0000000..b28d20f --- /dev/null +++ b/rmd/localChange.Rmd @@ -0,0 +1,6 @@ +--- +title: "Local Change" +output: html_document +--- + +Since you do not have a network use case and this element is specific to your data source, **feel free to create a local change to your instance of the OMOP Common Data Model.** Augmenting the model at your institution for administrative purposes or other in-house needs is totally acceptable with the understanding that any local changes cannot and should not be relied upon in network studies or supported by the open-source tools. diff --git a/rmd/useCaseN.Rmd b/rmd/useCaseN.Rmd new file mode 100644 index 0000000..32f7de7 --- /dev/null +++ b/rmd/useCaseN.Rmd @@ -0,0 +1,10 @@ +--- +title: "Local Data" +output: html_document +--- + +Okay, so you don't have a network use case. **Is this data element specific to your data source, or are there others in the community who might also have this data but don't yet need it for a study or data model convention?** + +[Yes, this element is specific to my data source](localChange.html) + +[No, there are others in the community who also have this data](leaveAsIs.html) diff --git a/rmd/useCaseY.Rmd b/rmd/useCaseY.Rmd new file mode 100644 index 0000000..f308231 --- /dev/null +++ b/rmd/useCaseY.Rmd @@ -0,0 +1,13 @@ +--- +title: "OMOP Vocabulary" +output: html_document +--- + +Great, you have a network use case! + +Next question: **Is there an existing OMOP vocabulary to support this new element? If you are unsure, feel free to check [Athena](https://athena.ohdsi.org/search-terms/terms?query).** + +[Yes, I have all the required vocabulary I need](vocabY.html) + +[No, I there is not an existing OMOP vocabulary to support my request](vocabN.html) + diff --git a/rmd/vocabN.Rmd b/rmd/vocabN.Rmd new file mode 100644 index 0000000..0eccca8 --- /dev/null +++ b/rmd/vocabN.Rmd @@ -0,0 +1,10 @@ +--- +title: "Open Source Vocabulary" +output: html_document +--- + +Okay, so you have a use case but you don't have an OMOP vocabulary to support your need. **Is there an existing open-source (not proprietary or custom) vocabulary that has not yet been incorporated into the OMOP vocabulary?** + +[Yes, the vocabulary exists, it just needs to be brought in](vocabRequest.html) + +[No, there is no open-source vocabulary for this data element](contactVocab.html) diff --git a/rmd/vocabRequest.Rmd b/rmd/vocabRequest.Rmd new file mode 100644 index 0000000..b80fd2e --- /dev/null +++ b/rmd/vocabRequest.Rmd @@ -0,0 +1,10 @@ +--- +title: "Vocabulary Request" +output: html_document +--- + +Okay so you have something you would like to add to the CDM and there is an existing OMOP vocabulary we can bring in to support it. **In this case, please open an issue on the vocabulary github with the details of what you need added** as data elements in the CDM must have a vocabulary in place before they can be implemented. The team will follow up with you should they need additional information. + +[Vocabulary GitHub Issue Tracker](https://github.com/OHDSI/Vocabulary-v5.0/issues) + +Once that request is made, please follow the [CDM Request Process](cdmRequestProcess.html) to begin the steps soliciting a change or addition to the model itself. Need more guidance? Consider contacting the CDM Working Group on our [GitHub](https://github.com/OHDSI/CommonDataModel) or [Teams Channel](https://teams.microsoft.com/l/team/19%3a133f2b94b86a41a884d4a4d160610148%40thread.tacv2/conversations?groupId=a6f2c516-e568-4974-8f1e-a7bdc2f997c5&tenantId=a30f0094-9120-4aab-ba4c-e5509023b2d5). diff --git a/rmd/vocabY.Rmd b/rmd/vocabY.Rmd new file mode 100644 index 0000000..7211460 --- /dev/null +++ b/rmd/vocabY.Rmd @@ -0,0 +1,8 @@ +--- +title: "Request Process" +output: html_document +--- + +Great, so you have a network use case and an existing OMOP Vocabulary! **From here, please follow the steps to formally request a change to the OMOP Common Data Model.** + +[CDM Request Process](cdmRequestProcess.html)