Skip to content

Commit 9138c1f

Browse files
makc4usmakc4us
authored
Create OMOP GIS Vocabulary Package Installation Manual
1 parent 3ab675d commit 9138c1f

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

‎rmd/vocabulary-ingestion‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
## OMOP GIS Vocabulary Package Installation Manual
2+
3+
This manual guides you through the process of integrating the OMOP GIS Vocabulary Package, which enhances standard vocabularies with geospatial concepts, into your OMOP CDM database. This integration leverages data from Athena OHDSI and delta tables provided in a GitHub repository, ensuring your data is enriched with accurate and up-to-date geospatial terminology.
4+
5+
### Prerequisites:
6+
7+
* Access to [Athena OHDSI](http://athena.ohdsi.org) (vocabulary service).
8+
* Access to your workspace (database).
9+
* SQL client (e.g., SQL Workbench, DBeaver, SQL Developer, pgAdmin) with permissions to upload data.
10+
* Access to the [GitHub repository](https://github.com/TuftsCTSI/CVB/tree/main/GIS/Ontology) containing delta tables.
11+
* Basic understanding of [OMOP CDM](https://www.ohdsi.org/data-standardization/) (Common Data Model) and vocabulary concepts.
12+
13+
### Step-by-Step Manual:
14+
15+
#### 1. Preparation and Workspace Setup
16+
17+
##### 1.1 Verify OMOP CDM Instance and Database Access:
18+
19+
* Ensure your OMOP Common Data Model (CDM) instance is properly deployed and operational.
20+
* Confirm that you have the necessary credentials and permissions to access the database schema where the OMOP Standardized Vocabularies will be stored.
21+
22+
##### 1.2 Verify Required OMOP Vocabulary Tables:
23+
24+
* Connect to your OMOP database using your preferred SQL client.
25+
* Verify the existence of the following OMOP Standardized Vocabulary tables:
26+
27+
||
28+
|---|
29+
| CONCEPT |
30+
| CONCEPT_ANCESTOR |
31+
| CONCEPT_CLASS |
32+
| CONCEPT_RELATIONSHIP |
33+
| CONCEPT_SYNONYM |
34+
| DOMAIN |
35+
| DRUG_STRENGTH |
36+
| RELATIONSHIP |
37+
| VOCABULARY |
38+
39+
* If any of the required OMOP vocabulary tables are missing, create them using the [Data Definition Language (DDL)](https://github.com/OHDSI/Vocabulary-v5.0/blob/master/working/DevV5_DDL.sql) specifications provided in the official OMOP CDM documentation.
40+
41+
##### 1.3. Create GIS Vocabulary Package Tables:
42+
43+
Use this script to create delta tables: [create_delta_tables.sql](https://github.com/OHDSI/GIS/blob/main/rmd/data/create_delta_tables.sql)
44+
45+
#### 2. Download Required Vocabularies from Athena OHDSI:
46+
47+
##### 2.1 Access Athena:
48+
49+
* Open your web browser and navigate to the [Athena OHDSI](http://athena.ohdsi.org) website.
50+
* Log in using your credentials. If you don't have an account, register for one.
51+
52+
##### 2.2 Search for Relevant Vocabularies:
53+
54+
* Use the search functionality to find the vocabulary versions you need.
55+
* You may need the following vocabularies:
56+
57+
||
58+
|---|
59+
| ATC |
60+
| CPT4* |
61+
| HCPCS |
62+
| ICD10CM |
63+
| LOINC |
64+
| Nebraska Lexicon |
65+
| OMOP Extension |
66+
| OSM |
67+
| PPI |
68+
| RxNorm |
69+
| RxNorm Extension |
70+
| SNOMED |
71+
| UK Biobank |
72+
73+
##### 2.3 Select and Download:
74+
75+
* Click "Download" in the top right corner of the page.
76+
* Select the desired vocabularies.
77+
* Click "Download Vocabularies."
78+
* Name the bundle and choose the appropriate version.
79+
* Initiate the download process. Athena will send the vocabularies as CSV files (often zipped) to your email.
80+
* Unzip the downloaded files to a local directory.
81+
82+
##### 2.4 Verify Downloaded Files:
83+
84+
Confirm that you have the following essential vocabulary files:
85+
86+
||
87+
|---|
88+
| CONCEPT.csv |
89+
| CONCEPT_ANCESTOR.csv |
90+
| CONCEPT_CLASS.csv |
91+
| CONCEPT_RELATIONSHIP.csv |
92+
| CONCEPT_SYNONYM.csv |
93+
| DOMAIN.csv |
94+
| DRUG_STRENGTH.csv |
95+
| RELATIONSHIP.csv |
96+
| VOCABULARY.csv |
97+
98+
##### 2.5. Download Delta Tables from the GitHub Repository:
99+
100+
**Access the GitHub Repository:** Open the provided [GitHub repository](https://github.com/TuftsCTSI/CVB/tree/main/GIS/Ontology) link.
101+
102+
**Download Delta Tables:**
103+
* Locate and download the delta table files.
104+
* Save these files to a local directory.
105+
* Ensure you download:
106+
||
107+
|---|
108+
| concept_ancestor_delta.csv |
109+
| concept_class_delta.csv |
110+
| concept_delta.csv |
111+
| concept_relationship_delta.csv |
112+
| concept_synonym_delta.csv |
113+
| domain_delta.csv |
114+
| mapping_metadata.csv |
115+
| relationship_delta.csv |
116+
| source_to_concept_map.csv |
117+
| vocabulary_delta.csv |
118+
119+
**Note!** You can disregard `restore.sql` and `update_log.csv`; they are not part of the necessary download files
120+
121+
#### 3. Upload Vocabularies into Your OMOP Workspace Schema:
122+
123+
##### 3.1 Connect to Your OMOP Database:
124+
125+
* Open your SQL client and connect to your database using your credentials.
126+
* Ensure you are connected to the correct schema where your tables reside.
127+
128+
##### 3.2 Import CSV Files:
129+
130+
Import the data from the downloaded Athena CSV files into the corresponding OMOP vocabulary tables:
131+
132+
||||
133+
|---|---|---|
134+
| CONCEPT.csv | → |concept |
135+
| CONCEPT_ANCESTOR.csv | → |concept_ancestor |
136+
| CONCEPT_CLASS.csv | → |concept_class |
137+
| CONCEPT_RELATIONSHIP.csv | → |concept_relationship |
138+
| CONCEPT_SYNONYM.csv | → |concept_synonym |
139+
| DOMAIN.csv | → |domain |
140+
| DRUG_STRENGTH.csv | → |drug_strength |
141+
| RELATIONSHIP.csv | → |relationship |
142+
| VOCABULARY.csv | → |vocabulary |
143+
144+
##### 3.3 Verify Upload:
145+
146+
Use this script to check delta tables: [check_delta_tables.sql](https://github.com/OHDSI/GIS/blob/main/rmd/data/check_delta_tables.sql)
147+
148+
##### 3.4 Apply Delta Changes Using SQL:
149+
150+
Use this script to insert GIS Vocabulary Package entities into your tables: [insert_delta_tables_into_omop.sql](https://github.com/OHDSI/GIS/blob/main/rmd/data/insert_delta_tables_into_omop.sql)
151+
152+
||||
153+
|---|---|---|
154+
| concept_ancestor_delta.csv | → | concept_ancestor |
155+
| concept_class_delta.csv | → | concept_class |
156+
| concept_delta.csv | → | concept |
157+
| concept_relationship_delta.csv | → | concept_relationship |
158+
| concept_synonym_delta.csv | → | concept_synonym |
159+
| domain_delta.csv | → | domain |
160+
| mapping_metadata.csv | → | mapping_metadata |
161+
| relationship_delta.csv | → | relationship |
162+
| source_to_concept_map.csv | → | source_to_concept_map |
163+
| vocabulary_delta.csv | → | vocabulary |
164+
165+
##### 3.5. Verify Delta Table Application:
166+
167+
Use this script toto verify that the delta data has been successfully applied to the vocabulary tables and the GIS tables: [check_delta_tables_inserts.sql](https://github.com/OHDSI/GIS/blob/main/rmd/data/check_delta_tables_inserts.sql)
168+
169+
##### OMOP GIS Vocabulary Package Installation Complete

0 commit comments

Comments
 (0)