OHDSI · clairblacketer · Apr 18, 2024 · Apr 18, 2024 · Apr 18, 2024 · Apr 18, 2024
diff --git a/docs/cdm53.html b/docs/cdm53.html
@@ -985,7 +985,7 @@
 Due to the small number of options, this tends to be zero.
 </td>
 <td style="text-align:left;">
 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;">
@@ -4596,9 +4596,11 @@
 modifier_source_value
 </td>
 <td style="text-align:left;">
+This field houses the verbatim value from the source data representing
+the modifier code for the procedure that occurred.
 </td>
 <td style="text-align:left;">
-The original modifier code from the source is stored here for reference.
+The value stored here is mapped to a MODIFIER_CONCEPT_ID.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -5484,15 +5486,10 @@
 are captured and mapped to standard concepts in the ‘Meas Value’ domain.
 </td>
 <td style="text-align:left;">
-If the raw data provides categorial results as well as continuous
-results for measurements, it is a valid ETL choice to preserve both
-values. The continuous value should go in the VALUE_AS_NUMBER field and
-the categorical value should be mapped to a standard concept in the
-‘Meas Value’ domain and put in the VALUE_AS_CONCEPT_ID field. This is
-also the destination for the ‘Maps to value’ relationship. If there’s no
-categorial result in a source_data, set value_as_concept_id to NULL, if
-there is a categorial result in a source_data but without mapping, set
-value_as_concept_id to 0.
+If there is no categorial result in the source data, set
+VALUE_AS_CONCEPT_ID to NULL, if there is a categorial result in a source
+data but without mapping, set VALUE_AS_CONCEPT_ID to 0, else map to a
+CONCEPT_ID.
 </td>
 <td style="text-align:left;">
 integer
@@ -5712,14 +5709,14 @@
 measurement_source_value
 </td>
 <td style="text-align:left;">
-This field houses the verbatim value from the source data representing
-the Measurement that occurred. For example, this could be an ICD10 or
-Read code.
+This field contains the exact value from the source data that represents
+the measurement that occurred.
 </td>
 <td style="text-align:left;">
-This code is mapped to a Standard Measurement Concept in the
-Standardized Vocabularies and the original code is stored here for
-reference.
+This value corresponds to a standardized CONCEPT_ID found in
+MEASUREMENT_CONCEPT_ID and in the ‘Measurement’ domain within the
+Standardized Vocabularies. The original code is retained here for
+reference purposes.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -5753,9 +5750,9 @@
 be consistent across the network.
 </td>
 <td style="text-align:left;">
-If the MEASUREMENT_SOURCE_VALUE is coded in the source data using an
-OMOP supported vocabulary put the concept id representing the source
-value here.
+If the MEASUREMENT_SOURCE_VALUE is coded in the source data using a
+vocabulary supported by OMOP Standardized Vocabularies, insert the
+CONCEPT_ID representing the source value here.
 </td>
 <td style="text-align:left;">
 integer

diff --git a/docs/cdm54.html b/docs/cdm54.html
@@ -1093,7 +1093,7 @@
 Due to the small number of options, this tends to be zero.
 </td>
 <td style="text-align:left;">
 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;">
@@ -4792,9 +4792,11 @@
 modifier_source_value
 </td>
 <td style="text-align:left;">
+This field houses the verbatim value from the source data representing
+the modifier code for the procedure that occurred.
 </td>
 <td style="text-align:left;">
-The original modifier code from the source is stored here for reference.
+The value stored here is mapped to a MODIFIER_CONCEPT_ID.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -5818,15 +5820,10 @@
 are captured and mapped to standard concepts in the ‘Meas Value’ domain.
 </td>
 <td style="text-align:left;">
-If the raw data provides categorial results as well as continuous
-results for measurements, it is a valid ETL choice to preserve both
-values. The continuous value should go in the VALUE_AS_NUMBER field and
-the categorical value should be mapped to a standard concept in the
-‘Meas Value’ domain and put in the VALUE_AS_CONCEPT_ID field. This is
-also the destination for the ‘Maps to value’ relationship. If there’s no
-categorial result in a source_data, set value_as_concept_id to NULL, if
-there is a categorial result in a source_data but without mapping, set
-value_as_concept_id to 0.
+If there is no categorial result in the source data, set
+VALUE_AS_CONCEPT_ID to NULL, if there is a categorial result in a source
+data but without mapping, set VALUE_AS_CONCEPT_ID to 0, else map to a
+CONCEPT_ID.
 </td>
 <td style="text-align:left;">
 integer
@@ -6046,14 +6043,14 @@
 measurement_source_value
 </td>
 <td style="text-align:left;">
-This field houses the verbatim value from the source data representing
-the Measurement that occurred. For example, this could be an ICD10 or
-Read code.
+This field contains the exact value from the source data that represents
+the measurement that occurred.
 </td>
 <td style="text-align:left;">
-This code is mapped to a Standard Measurement Concept in the
-Standardized Vocabularies and the original code is stored here for
-reference.
+This value corresponds to a standardized CONCEPT_ID found in
+MEASUREMENT_CONCEPT_ID and in the ‘Measurement’ domain within the
+Standardized Vocabularies. The original code is retained here for
+reference purposes.
 </td>
 <td style="text-align:left;">
 varchar(50)
@@ -6087,9 +6084,9 @@
 be consistent across the network.
 </td>
 <td style="text-align:left;">
-If the MEASUREMENT_SOURCE_VALUE is coded in the source data using an
-OMOP supported vocabulary put the concept id representing the source
-value here.
+If the MEASUREMENT_SOURCE_VALUE is coded in the source data using a
+vocabulary supported by OMOP Standardized Vocabularies, insert the
+CONCEPT_ID representing the source value here.
 </td>
 <td style="text-align:left;">
 integer

diff --git a/inst/csv/OMOP_CDMv5.3_Field_Level.csv b/inst/csv/OMOP_CDMv5.3_Field_Level.csv
@@ -1,4 +1,4 @@
 cdmTableName,cdmFieldName,isRequired,cdmDatatype,userGuidance,etlConventions,isPrimaryKey,isForeignKey,fkTableName,fkFieldName,fkDomain,fkClass,unique DQ identifiers
 person,person_id,Yes,integer,It is assumed that every person with a different unique identifier is in fact a different person and should be treated independently.,"Any person linkage that needs to occur to uniquely identify Persons ought to be done prior to writing this table. This identifier can be the original id from the source data provided if it is an integer, otherwise it can be an autogenerated number.",Yes,No,NA,NA,NA,NA,NA
 person,gender_concept_id,Yes,integer,This field is meant to capture the biological sex at birth of the Person. This field should not be used to study gender identity issues.,Use the gender or sex value present in the data under the assumption that it is the biological sex at birth. If the source data captures gender identity it should be stored in the [OBSERVATION](https://ohdsi.github.io/CommonDataModel/cdm531.html#observation) table. [Accepted gender concepts](http://athena.ohdsi.org/search-terms/terms?domain=Gender&standardConcept=Standard&page=1&pageSize=15&query=). Please refer to the [THEMIS repository](https://ohdsi.github.io/Themis/tag_gender_concept_id.html) for detailed conventions on how to populate this field.,No,Yes,CONCEPT,CONCEPT_ID,Gender,NA,NA
 person,year_of_birth,Yes,integer,Compute age using year_of_birth.,"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 [THEMIS repository](https://ohdsi.github.io/Themis/tag_year_of_birth.html).",No,No,NA,NA,NA,NA,NA
@@ -12,7 +12,7 @@
 person,care_site_id,No,integer,The Care Site refers to where the Provider typically provides the primary care.,NA,No,Yes,CARE_SITE,CARE_SITE_ID,NA,NA,NA
 person,person_source_value,No,varchar(50),Use this field to link back to persons in the source data. This is typically used for error checking of ETL logic.,Some use cases require the ability to link back to persons in the source data. This field allows for the storing of the person value as it appears in the source. This field is not required but strongly recommended.,No,No,NA,NA,NA,NA,NA
 person,gender_source_value,No,varchar(50),This field is used to store the biological sex of the person from the source data. It is not intended for use in standard analytics but for reference only.,Put the assigned sex at birth of the person as it appears in the source data.,No,No,NA,NA,NA,NA,NA
 person,gender_source_concept_id,No,integer,"Due to the small number of options, this tends to be zero.","If the source data codes asigned sex at birth in a non-standard vocabulary, store the concept_id here.",No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
 person,race_source_value,No,varchar(50),This field is used to store the race of the person from the source data. It is not intended for use in standard analytics but for reference only.,Put the race of the person as it appears in the source data.,No,No,NA,NA,NA,NA,NA
 person,race_source_concept_id,No,integer,"Due to the small number of options, this tends to be zero.",If the source data codes race in an OMOP supported vocabulary store the concept_id here.,No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
 person,ethnicity_source_value,No,varchar(50),This field is used to store the ethnicity of the person from the source data. It is not intended for use in standard analytics but for reference only.,"If the person has an ethnicity other than the OMB standard of ""Hispanic"" or ""Not Hispanic"" store that value from the source data here.",No,No,NA,NA,NA,NA,NA
@@ -124,7 +124,7 @@
 procedure_occurrence,visit_detail_id,No,integer,"The VISIT_DETAIL record during which the Procedure occurred. For example, if the Person was in the ICU at the time of the Procedure the VISIT_OCCURRENCE record would reflect the overall hospital stay and the VISIT_DETAIL record would reflect the ICU stay during the hospital visit.",Same rules apply as for the VISIT_OCCURRENCE_ID.,No,No,VISIT_DETAIL,VISIT_DETAIL_ID,NA,NA,NA
 procedure_occurrence,procedure_source_value,No,varchar(50),"This field houses the verbatim value from the source data representing the procedure that occurred. For example, this could be an CPT4 or OPCS4 code.",Use this value to look up the source concept id and then map the source concept id to a standard concept id.,No,No,NA,NA,NA,NA,NA
 procedure_occurrence,procedure_source_concept_id,No,integer,"This is the concept representing the procedure source value and may not necessarily be standard. This field is discouraged from use in analysis because it is not required to contain Standard Concepts that are used across the OHDSI community, and should only be used when Standard Concepts do not adequately represent the source detail for the Procedure necessary for a given analytic use case. Consider using PROCEDURE_CONCEPT_ID instead to enable standardized analytics that can be consistent across the network.",If the PROCEDURE_SOURCE_VALUE is coded in the source data using an OMOP supported vocabulary put the concept id representing the source value here.,No,No,CONCEPT,CONCEPT_ID,NA,NA,NA
-procedure_occurrence,modifier_source_value,No,varchar(50),NA,The original modifier code from the source is stored here for reference.,No,No,NA,NA,NA,NA,NA
+procedure_occurrence,modifier_source_value,No,varchar(50),This field houses the verbatim value from the source data representing the modifier code for the procedure that occurred.,The value stored here is mapped to a MODIFIER_CONCEPT_ID.,No,No,NA,NA,NA,NA,NA
 device_exposure,device_exposure_id,Yes,integer,The unique key given to records a person's exposure to a foreign physical object or instrument.,Each instance of an exposure to a foreign object or device present in the source data should be assigned this unique key.,Yes,No,NA,NA,NA,NA,NA
 device_exposure,person_id,Yes,integer,NA,NA,No,Yes,PERSON,PERSON_ID,NA,NA,NA
 device_exposure,device_concept_id,Yes,integer,"The DEVICE_CONCEPT_ID field is recommended for primary use in analyses, and must be used for network studies. This is the standard concept mapped from the source concept id which represents a foreign object or instrument the person was exposed to.",The CONCEPT_ID that the DEVICE_SOURCE_VALUE maps to.,No,Yes,CONCEPT,CONCEPT_ID,Device,NA,NA
@@ -149,15 +149,15 @@
 measurement,measurement_type_concept_id,Yes,integer,"This field can be used to determine the provenance of the Measurement record, as in whether the measurement was from an EHR system, insurance claim, registry, or other sources.","Choose the MEASUREMENT_TYPE_CONCEPT_ID that best represents the provenance of the record, for example whether it came from an EHR record or billing claim. [Accepted Concepts](https://athena.ohdsi.org/search-terms/terms?domain=Type+Concept&standardConcept=Standard&page=1&pageSize=15&query=).",No,Yes,CONCEPT,CONCEPT_ID,Type Concept,NA,NA
 measurement,operator_concept_id,No,integer,"The meaning of Concept [4172703](https://athena.ohdsi.org/search-terms/terms/4172703) for '=' is identical to omission of a OPERATOR_CONCEPT_ID value. Since the use of this field is rare, it's important when devising analyses to not to forget testing for the content of this field for values different from =.","Operators are <, <=, =, >=, > and these concepts belong to the 'Meas Value Operator' domain. [Accepted Concepts](https://athena.ohdsi.org/search-terms/terms?domain=Meas+Value+Operator&standardConcept=Standard&page=1&pageSize=15&query=). Leave it NULL if there's an exact numeric value given (instead of putting '=') or there's no numeric value at all.",No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
 measurement,value_as_number,No,float,"This is the numerical value of the Result of the Measurement, if available. Note that measurements such as blood pressures will be split into their component parts i.e. one record for systolic, one record for diastolic.",[Convention for negative values](https://ohdsi.github.io/Themis/negative_value_as_number.html),No,No,NA,NA,NA,NA,NA
-measurement,value_as_concept_id,No,integer,If the raw data gives a categorial result for measurements those values are captured and mapped to standard concepts in the 'Meas Value' domain.,"If the raw data provides categorial results as well as continuous results for measurements, it is a valid ETL choice to preserve both values. The continuous value should go in the VALUE_AS_NUMBER field and the categorical value should be mapped to a standard concept in the 'Meas Value' domain and put in the VALUE_AS_CONCEPT_ID field. This is also the destination for the 'Maps to value' relationship. If there's no categorial result in a source_data, set value_as_concept_id to NULL, if there is a categorial result in a source_data but without mapping, set value_as_concept_id to 0.",No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
+measurement,value_as_concept_id,No,integer,If the raw data gives a categorial result for measurements those values are captured and mapped to standard concepts in the 'Meas Value' domain.,"If there is no categorial result in the source data, set VALUE_AS_CONCEPT_ID to NULL, if there is a categorial result in a source data but without mapping, set VALUE_AS_CONCEPT_ID to 0, else map to a CONCEPT_ID.",No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
 measurement,unit_concept_id,No,integer,"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.","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.",No,Yes,CONCEPT,CONCEPT_ID,Unit,NA,NA
 measurement,range_low,No,float,Ranges have the same unit as the VALUE_AS_NUMBER. These ranges are provided by the source and should remain NULL if not given.,If reference ranges for upper and lower limit of normal as provided (typically by a laboratory) these are stored in the RANGE_HIGH and RANGE_LOW fields. This should be set to NULL if not provided.,No,No,NA,NA,NA,NA,NA
 measurement,range_high,No,float,Ranges have the same unit as the VALUE_AS_NUMBER. These ranges are provided by the source and should remain NULL if not given.,If reference ranges for upper and lower limit of normal as provided (typically by a laboratory) these are stored in the RANGE_HIGH and RANGE_LOW fields. This should be set to NULL if not provided.,No,No,NA,NA,NA,NA,NA
 measurement,provider_id,No,integer,"The provider associated with measurement record, e.g. the provider who ordered the test or the provider who recorded the result.",The ETL may need to make a choice as to which PROVIDER_ID to put here. Based on what is available this may or may not be different than the provider associated with the overall VISIT_OCCURRENCE record. For example the admitting vs attending physician on an EHR record.,No,Yes,PROVIDER,PROVIDER_ID,NA,NA,NA
 measurement,visit_occurrence_id,No,integer,The visit during which the Measurement occurred.,"Depending on the structure of the source data, this may have to be determined based on dates. If a MEASUREMENT_DATE occurs within the start and end date of a Visit it is a valid ETL choice to choose the VISIT_OCCURRENCE_ID from the visit that subsumes it, even if not explicitly stated in the data. While not required, an attempt should be made to locate the VISIT_OCCURRENCE_ID of the measurement record. If a measurement is related to a visit explicitly in the source data, it is possible that the result date of the Measurement falls outside of the bounds of the Visit dates.",No,Yes,VISIT_OCCURRENCE,VISIT_OCCURRENCE_ID,NA,NA,NA
 measurement,visit_detail_id,No,integer,"The VISIT_DETAIL record during which the Measurement occurred. For example, if the Person was in the ICU at the time the VISIT_OCCURRENCE record would reflect the overall hospital stay and the VISIT_DETAIL record would reflect the ICU stay during the hospital visit.",Same rules apply as for the VISIT_OCCURRENCE_ID.,No,Yes,VISIT_DETAIL,VISIT_DETAIL_ID,NA,NA,NA
-measurement,measurement_source_value,No,varchar(50),"This field houses the verbatim value from the source data representing the Measurement that occurred. For example, this could be an ICD10 or Read code.",This code is mapped to a Standard Measurement Concept in the Standardized Vocabularies and the original code is stored here for reference.,No,No,NA,NA,NA,NA,NA
-measurement,measurement_source_concept_id,No,integer,"This is the concept representing the MEASUREMENT_SOURCE_VALUE and may not necessarily be standard. This field is discouraged from use in analysis because it is not required to contain Standard Concepts that are used across the OHDSI community, and should only be used when Standard Concepts do not adequately represent the source detail for the Measurement necessary for a given analytic use case. Consider using MEASUREMENT_CONCEPT_ID instead to enable standardized analytics that can be consistent across the network.",If the MEASUREMENT_SOURCE_VALUE is coded in the source data using an OMOP supported vocabulary put the concept id representing the source value here.,No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
+measurement,measurement_source_value,No,varchar(50),This field contains the exact value from the source data that represents the measurement that occurred.,This value corresponds to a standardized CONCEPT_ID found in MEASUREMENT_CONCEPT_ID and in the 'Measurement' domain within the Standardized Vocabularies. The original code is retained here for reference purposes.,No,No,NA,NA,NA,NA,NA
+measurement,measurement_source_concept_id,No,integer,"This is the concept representing the MEASUREMENT_SOURCE_VALUE and may not necessarily be standard. This field is discouraged from use in analysis because it is not required to contain Standard Concepts that are used across the OHDSI community, and should only be used when Standard Concepts do not adequately represent the source detail for the Measurement necessary for a given analytic use case. Consider using MEASUREMENT_CONCEPT_ID instead to enable standardized analytics that can be consistent across the network.","If the MEASUREMENT_SOURCE_VALUE is coded in the source data using a vocabulary supported by OMOP Standardized Vocabularies, insert the CONCEPT_ID representing the source value here.",No,Yes,CONCEPT,CONCEPT_ID,NA,NA,NA
 measurement,unit_source_value,No,varchar(50),This field contains the exact value from the source data that represents the unit of measurement used.,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.,No,No,NA,NA,NA,NA,NA
 measurement,value_source_value,No,varchar(50),This field houses the verbatim result value of the Measurement from the source data .,"If both a continuous and categorical result are given in the source data such that both VALUE_AS_NUMBER and VALUE_AS_CONCEPT_ID are both included, store the verbatim value that was mapped to VALUE_AS_CONCEPT_ID here.",No,No,NA,NA,NA,NA,NA
 observation,observation_id,Yes,integer,The unique key given to an Observation record for a Person. Refer to the ETL for how duplicate Observations during the same Visit were handled.,Each instance of an observation present in the source data should be assigned this unique key.,Yes,No,NA,NA,NA,NA,NA