Merge pull request #650 from OHDSI/olympians_week2

Olympians week2

docs/cdm53.html

@@ -524,7 +524,10 @@ <h3 class="tabset tabset-pills">person</h3>
 contributes Events to the database, Persons must be reconciled, if
 possible, across the sources to create one single record per Person. The
 content of the BIRTH_DATETIME must be equivalent to the content of
-BIRTH_DAY, BIRTH_MONTH and BIRTH_YEAR.</p>
+BIRTH_DAY, BIRTH_MONTH and BIRTH_YEAR.<br><br>For detailed conventions
+for how to populate this table, please refer to the <a
+href="https://ohdsi.github.io/Themis/person.html">THEMIS
+repository</a>.</p>
 <table class="table table-condensed table-hover" style="font-size: 13px; margin-left: auto; margin-right: auto;">
 <thead>
 <tr>
@@ -604,7 +607,9 @@ <h3 class="tabset tabset-pills">person</h3>
 href="https://ohdsi.github.io/CommonDataModel/cdm531.html#observation">OBSERVATION</a>
 table. <a
 href="http://athena.ohdsi.org/search-terms/terms?domain=Gender&amp;standardConcept=Standard&amp;page=1&amp;pageSize=15&amp;query=">Accepted
-gender concepts</a>
+gender concepts</a>. Please refer to the <a
+href="https://ohdsi.github.io/Themis/tag_gender_concept_id.html">THEMIS
+repository</a> for detailed conventions on how to populate this field.
 </td>
 <td style="text-align:left;">
 integer
@@ -633,11 +638,12 @@ <h3 class="tabset tabset-pills">person</h3>
 Compute age using year_of_birth.
 </td>
 <td style="text-align:left;">
-For data sources with date of birth, the year should be extracted. For
-data sources where the year of birth is not available, the approximate
-year of birth could be derived based on age group categorization, if
-available. If no year of birth is available all the person’s data should
-be dropped from the CDM instance.
+For data sources with date of birth, the year should be extracted. If no
+year of birth is available all the person’s data should be dropped from
+the CDM instance. For additional information on how to populate this
+field, please refer to the <a
+href="https://ohdsi.github.io/Themis/tag_year_of_birth.html">THEMIS
+repository</a>.
 </td>
 <td style="text-align:left;">
 integer
@@ -719,13 +725,9 @@ <h3 class="tabset tabset-pills">person</h3>
 <td style="text-align:left;">
 This field is not required but highly encouraged. For data sources that
 provide the precise datetime of birth, that value should be stored in
-this field. If birth_datetime is not provided in the source, use the
-following logic to infer the date: If day_of_birth is null and
-month_of_birth is not null then use the first of the month in that year.
-If month_of_birth is null or if day_of_birth AND month_of_birth are both
-null and the person has records during their year of birth then use the
-date of the earliest record, otherwise use the 15th of June of that
-year. If time of birth is not given use midnight (00:00:0000).
+this field. For more information on how to populate this field, please
+refer to the <a href="https://ohdsi.github.io/Themis/person.html">THEMIS
+repository</a>.
 </td>
 <td style="text-align:left;">
 datetime
@@ -828,11 +830,10 @@ <h3 class="tabset tabset-pills">person</h3>
 Put the location_id from the <a
 href="https://ohdsi.github.io/CommonDataModel/cdm531.html#location">LOCATION</a>
 table here that represents the most granular location information for
-the person. This could represent anything from postal code or parts
-thereof, state, or county for example. Since many databases contain
-deidentified data, it is common that the precision of the location is
-reduced to prevent re-identification. This field should capture the last
-known location.
+the person. For additional information on how to populate this field,
+please refer to the <a
+href="https://ohdsi.github.io/Themis/populate_person_location_id.html">THEMIS
+repository</a>.
 </td>
 <td style="text-align:left;">
 integer
@@ -953,7 +954,8 @@ <h3 class="tabset tabset-pills">person</h3>
 reference only.
 </td>
 <td style="text-align:left;">
-Put the biological sex of the person as it appears in the source data.
+Put the assigned sex at birth of the person as it appears in the source
+data.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -980,8 +982,8 @@ <h3 class="tabset tabset-pills">person</h3>
 Due to the small number of options, this tends to be zero.
 </td>
 <td style="text-align:left;">
-If the source data codes biological sex in a non-standard vocabulary,
-store the concept_id here.
+If the source data codes asigned sex at birth in a non-standard
+vocabulary, store the concept_id here.
 </td>
 <td style="text-align:left;">
 integer
@@ -3310,7 +3312,10 @@ <h3 class="tabset tabset-pills">drug_exposure</h3>
 dispensed. If a patient has multiple records on the same day for the
 same drug or procedures the ETL should not de-dupe them unless there is
 probable reason to believe the item is a true data duplicate. Take note
-on how to handle refills for prescriptions written.</p>
+on how to handle refills for prescriptions written.<br><br>For detailed
+conventions on how to populate this table, please refer to the <a
+href="https://ohdsi.github.io/Themis/drug_exposure.html">THEMIS
+repository</a>.</p>
 <table class="table table-condensed table-hover" style="font-size: 13px; margin-left: auto; margin-right: auto;">
 <thead>
 <tr>
@@ -3432,14 +3437,16 @@ <h3 class="tabset tabset-pills">drug_exposure</h3>
 DRUG_SOURCE_VALUE and a DRUG_CONCEPT_ID of 0. The Drug Concept with the
 most detailed content of information is preferred during the mapping
 process. These are indicated in the CONCEPT_CLASS_ID field of the
-Concept and are recorded in the following order of precedence: ‘Branded
-Pack’, ‘Clinical Pack’, ‘Branded Drug’, ‘Clinical Drug’, ‘Branded Drug
-Component’, ‘Clinical Drug Component’, ‘Branded Drug Form’, ‘Clinical
-Drug Form’, and only if no other information is available ‘Ingredient’.
-Note: If only the drug class is known, the DRUG_CONCEPT_ID field should
-contain 0. <a
+Concept and are recorded in the following order of precedence:
+<d2>Marketed Product<d3>, <d2>Branded Pack<d3>, <d2>Clinical Pack<d3>,
+<d2>Branded Drug<d3>, <d2>Clinical Drug<d3>, <d2>Branded Drug
+Component<d3>, <d2>Clinical Drug Component<d3>, <d2>Branded Drug
+Form<d3>, <d2>Clinical Drug Form<d3>, and only if no other information
+is available <d2>Ingredient<d3>. Note: If only the drug class is known,
+the DRUG_CONCEPT_ID field should contain 0. <a
 href="https://athena.ohdsi.org/search-terms/terms?domain=Drug&amp;standardConcept=Standard&amp;page=1&amp;pageSize=15&amp;query=">Accepted
 Concepts</a>.
+</d3></d2></d3></d2></d3></d2></d3></d2></d3></d2></d3></d2></d3></d2></d3></d2></d3></d2></d3></d2>
 </td>
 <td style="text-align:left;">
 integer
@@ -3542,7 +3549,10 @@ <h3 class="tabset tabset-pills">drug_exposure</h3>
 as quantity (200 example) * daily dose (5mL) /concentration (20mg/mL)
 200*5/20 = 50 days. <a
 href="https://ohdsi.github.io/CommonDataModel/drug_dose.html">Examples
-by dose form</a>
+by dose form</a><br><br>For detailed conventions for how to populate
+this field, please see the <a
+href="https://ohdsi.github.io/Themis/tag_drug_exposure.html">THEMIS
+repository</a>.
 </td>
 <td style="text-align:left;">
 date
@@ -5248,12 +5258,13 @@ <h3 class="tabset tabset-pills">measurement</h3>
 </td>
 <td style="text-align:left;">
 The MEASUREMENT_CONCEPT_ID field is recommended for primary use in
-analyses, and must be used for network studies.
+analyses, and must be used for network studies. This is the standard
+concept mapped from the source value which represents a measurement.
 </td>
 <td style="text-align:left;">
-The CONCEPT_ID that the MEASUREMENT_SOURCE_CONCEPT_ID maps to. Only
-records whose SOURCE_CONCEPT_IDs map to Standard Concepts with a domain
-of “Measurement” should go in this table.
+The CONCEPT_ID that the MEASUREMENT_SOURCE_VALUE maps to. Only records
+whose source values map to concepts with a domain of <d2>Measurement<d3>
+should go in this table. </d3></d2>
 </td>
 <td style="text-align:left;">
 integer
@@ -5517,19 +5528,17 @@ <h3 class="tabset tabset-pills">measurement</h3>
 unit_concept_id
 </td>
 <td style="text-align:left;">
-There is currently no recommended unit for individual measurements,
-i.e. it is not mandatory to represent Hemoglobin a1C measurements as a
-percentage. UNIT_SOURCE_VALUES should be mapped to a Standard Concept in
-the Unit domain that best represents the unit as given in the source
-data.
+At present, there isn’t a prescribed unit for individual measurements,
+such as Hemoglobin A1C, meaning it’s not obligatory to express these
+measurements as a percentage. UNIT_SOURCE_VALUES should be linked to a
+Standard Concept within the Unit domain that most accurately reflects
+the unit provided in the source data.
 </td>
 <td style="text-align:left;">
-There is no standardization requirement for units associated with
-MEASUREMENT_CONCEPT_IDs, however, it is the responsibility of the ETL to
-choose the most plausible unit. If the source unit is NULL (applicable
-to cases when there’s no numerical value or when it doesn’t require a
-unit), keep unit_concept_id NULL as well. If there’s no mapping of a
-source unit, populate unit_concept_id with 0.
+If the source data does not include units, set UNIT_CONCEPT_ID to NULL.
+If units are provided but not mapped, set UNIT_CONCEPT_ID to 0.
+Otherwise, map the units to a CONCEPT_ID. Remember that units are
+case-sensitive in vocabulary.
 </td>
 <td style="text-align:left;">
 integer
@@ -5782,12 +5791,13 @@ <h3 class="tabset tabset-pills">measurement</h3>
 unit_source_value
 </td>
 <td style="text-align:left;">
-This field houses the verbatim value from the source data representing
-the unit of the Measurement that occurred.
+This field contains the exact value from the source data that represents
+the unit of measurement used.
 </td>
 <td style="text-align:left;">
-This code is mapped to a Standard Condition Concept in the Standardized
-Vocabularies and the original code is stored here for reference.
+This value corresponds to a standardized CONCEPT_ID found in
+UNIT_CONCEPT_ID and in the ‘Unit’ domain within the Standardized
+Vocabularies. The original code is retained here for reference purposes.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -5858,10 +5868,18 @@ <h3 class="tabset tabset-pills">observation</h3>
 table. If the clinical fact observed determines a sign, symptom,
 diagnosis of a disease or other medical condition, it is recorded in the
 CONDITION_OCCURRENCE table. Valid Observation Concepts are not enforced
-to be from any domain though they still should be Standard Concepts.</p>
+to be from any domain but they must not belong to the Condition,
+Procedure, Drug, Device, Specimen, or Measurement domains and they must
+be Standard Concepts. <br><br>The observation table usually records the
+date or datetime of when the observation was obtained, not the date of
+the observation starting. For example, if the patient reports that they
+had a heart attack when they were 50, the observation date or datetime
+is the date of the report, the heart attack observation can have a
+value_as_concept which captures how long ago the observation applied to
+the patient.</p>
 <p><strong>ETL Conventions</strong></p>
 <p>Records whose Source Values map to any domain besides Condition,
-Procedure, Drug, Measurement or Device should be stored in the
+Procedure, Drug, Specimen, Measurement or Device should be stored in the
 Observation table. Observations can be stored as attribute value pairs,
 with the attribute as the Observation Concept and the value representing
 the clinical fact. This fact can be a Concept (stored in
@@ -5999,9 +6017,9 @@ <h3 class="tabset tabset-pills">observation</h3>
 observation_date
 </td>
 <td style="text-align:left;">
-The date of the Observation. Depending on what the Observation
-represents this could be the date of a lab test, the date of a survey,
-or the date a patient’s family history was taken.
+The date of when the Observation was obtained. Depending on what the
+Observation represents this could be the date of a lab test, the date of
+a survey, or the date a patient’s family history was taken.
 </td>
 <td style="text-align:left;">
 For some observations the ETL may need to make a choice as to which date
@@ -6498,7 +6516,9 @@ <h3 class="tabset tabset-pills">death</h3>
 <p><strong>User Guide</strong></p>
 <p>NA</p>
 <p><strong>ETL Conventions</strong></p>
-<p>NA</p>
+<p>For specific conventions on how to populate this table, please refer
+to the <a href="https://ohdsi.github.io/Themis/death.html">THEMIS
+repository</a>.</p>
 <table class="table table-condensed table-hover" style="font-size: 13px; margin-left: auto; margin-right: auto;">
 <thead>
 <tr>
@@ -6568,7 +6588,10 @@ <h3 class="tabset tabset-pills">death</h3>
 <td style="text-align:left;">
 If the precise date include day or month is not known or not allowed,
 December is used as the default month, and the last day of the month the
-default day.
+default day. For additional conventions related to this field, please
+refer to the <a
+href="https://ohdsi.github.io/Themis/tag_death_date.html">THEMIS
+repository</a>.
 </td>
 <td style="text-align:left;">
 date
@@ -6711,7 +6734,8 @@ <h3 class="tabset tabset-pills">death</h3>
 </td>
 <td style="text-align:left;">
 If the cause of death was coded using a Vocabulary present in the OMOP
-Vocabularies put the CONCEPT_ID representing the cause of death here.
+Vocabularies (not necessarily a standard concept) put the CONCEPT_ID
+representing the cause of death here.
 </td>
 <td style="text-align:left;">
 integer
@@ -8542,19 +8566,23 @@ <h3 class="tabset tabset-pills">care_site</h3>
 <p><strong>User Guide</strong></p>
 <p>NA</p>
 <p><strong>ETL Conventions</strong></p>
-<p>Care site is a unique combination of location_id and
-place_of_service_source_value. Care site does not take into account the
-provider (human) information such a specialty. Many source data do not
-make a distinction between individual and institutional providers. The
-CARE_SITE table contains the institutional providers. If the source,
+<p>Care site is a unique combination of location_id and nature of the
+site - the latter could be the place of service, name, or another
+characteristic in your source data. Care site does not take into account
+the provider (human) information such a specialty. Many source data do
+not make a distinction between individual and institutional providers.
+The CARE_SITE table contains the institutional providers. If the source,
 instead of uniquely identifying individual Care Sites, only provides
 limited information such as Place of Service, generic or “pooled” Care
 Site records are listed in the CARE_SITE table. There can be
 hierarchical and business relationships between Care Sites. For example,
 wards can belong to clinics or departments, which can in turn belong to
 hospitals, which in turn can belong to hospital systems, which in turn
 can belong to HMOs.The relationships between Care Sites are defined in
-the FACT_RELATIONSHIP table.</p>
+the FACT_RELATIONSHIP table.<br><br>For additional detailed conventions
+on how to populate this table, please refer to <a
+href="https://ohdsi.github.io/Themis/care_site.html">THEMIS
+repository</a>.</p>
 <table class="table table-condensed table-hover" style="font-size: 13px; margin-left: auto; margin-right: auto;">
 <thead>
 <tr>
@@ -8657,7 +8685,10 @@ <h3 class="tabset tabset-pills">care_site</h3>
 represent Inpatient. If information is present about a unique Care Site
 (e.g. Pharmacy) then a Care Site record should be created. <a
 href="https://athena.ohdsi.org/search-terms/terms?domain=Visit&amp;standardConcept=Standard&amp;page=2&amp;pageSize=15&amp;query=">Accepted
-Concepts</a>.
+Concepts</a>. For information about how to populate this field please
+see the <a
+href="https://ohdsi.github.io/Themis/tag_place_of_service.html">THEMIS
+Conventions</a>.
 </td>
 <td style="text-align:left;">
 integer