Person
======

*Source file:* ``person.py``

Root XPath
----------

.. code-block:: xpath

    ./hl7:recordTarget/hl7:patientRole

**Expected OMOP domain:** Person

Fields
------

+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| Field                                   | Type     | Order | Details                                                                                                                                               |
+=========================================+==========+=======+=======================================================================================================================================================+
| person_id                               | DERIVED  | 1     | ``VT.map_filename_to_mspi(filename=filename)``                                                                                                        |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_id                       | PRIORITY | 2     | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| year_of_birth                           | DERIVED  | 3     | ``VT.extract_year_of_birth(date_object=birth_datetime)``                                                                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| month_of_birth                          | DERIVED  | 4     | ``VT.extract_month_of_birth(date_object=birth_datetime)``                                                                                             |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| day_of_birth                            | DERIVED  | 5     | ``VT.extract_day_of_birth(date_object=birth_datetime)``                                                                                               |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| birth_datetime                          | FIELD    | 6     | ``hl7:patient/hl7:birthTime`` @value [DATETIME]                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_id                         | PRIORITY | 7     | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_id                    | PRIORITY | 8     | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| location_id                             | HASH     | 9     | hash(address_1, city, state, zip)                                                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| provider_id                             | None     | 10    | —                                                                                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| care_site_id                            | CONSTANT | 11    | ``0``                                                                                                                                                 |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| person_source_value                     | CONSTANT | 12    | ````                                                                                                                                                  |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_source_value                     | PRIORITY | 13    | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_source_concept_id                | None     | 14    | —                                                                                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_source_value                       | PRIORITY | 15    | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_source_concept_id                  | None     | 16    | —                                                                                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_source_value                  | PRIORITY | 17    | coalesce candidates by priority                                                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_source_concept_id             | None     | 18    | —                                                                                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| data_partner_id                         | DERIVED  | 20    | ``VT.get_data_partner_id(filename=filename)``                                                                                                         |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| filename                                | FILENAME | 100   | source XML filename                                                                                                                                   |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| cfg_name                                | CONSTANT | 101   | ``Person``                                                                                                                                            |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| address_1                               | FIELD    |       | ``hl7:addr/hl7:streetAddressLine`` @#text                                                                                                             |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| city                                    | FIELD    |       | ``hl7:addr/hl7:city`` @#text                                                                                                                          |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_codeSystem_direct     | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode[not(@nullFlavor="OTH")]`` @codeSystem                                                                               |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_codeSystem_sdtc       | FIELD    |       | ``hl7:patient/sdtc:ethnicGroupCode`` @codeSystem                                                                                                      |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_codeSystem_translated | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode/hl7:translation`` @codeSystem                                                                                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_code_direct           | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode[not(@nullFlavor="OTH")]`` @code                                                                                     |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_code_sdtc             | FIELD    |       | ``hl7:patient/sdtc:ethnicGroupCode`` @code                                                                                                            |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_code_translated       | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode/hl7:translation`` @code                                                                                             |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_id_direct             | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=ethnicity_concept_code_direct, vocabulary_oid=ethnicity_concept_codeSystem_direct, default=None)``         |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_id_sdtc               | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=ethnicity_concept_code_sdtc, vocabulary_oid=ethnicity_concept_codeSystem_sdtc, default=None)``             |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_concept_id_translated         | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=ethnicity_concept_code_translated, vocabulary_oid=ethnicity_concept_codeSystem_translated, default=None)`` |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_source_value_direct           | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode`` @code → priority ('ethnicity_source_value', 1)                                                                    |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_source_value_sdtc             | FIELD    |       | ``hl7:patient/sdtc:ethnicGroupCode`` @code → priority ('ethnicity_source_value', 2)                                                                   |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| ethnicity_source_value_translated       | FIELD    |       | ``hl7:patient/hl7:ethnicGroupCode/hl7:translation`` @code → priority ('ethnicity_source_value', 3)                                                    |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_codeSystem_direct        | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode[not(@nullFlavor="OTH")]`` @codeSystem                                                                      |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_codeSystem_translated    | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode/hl7:translation`` @codeSystem                                                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_code_direct              | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode[not(@nullFlavor="OTH")]`` @code                                                                            |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_code_translated          | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode/hl7:translation`` @code                                                                                    |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_id_direct                | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=gender_concept_code_direct, vocabulary_oid=gender_concept_codeSystem_direct, default=None)``               |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_concept_id_translated            | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=gender_concept_code_translated, vocabulary_oid=gender_concept_codeSystem_translated, default=None)``       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_source_value_direct              | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode`` @code → priority ('gender_source_value', 1)                                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| gender_source_value_translated          | FIELD    |       | ``hl7:patient/hl7:administrativeGenderCode/hl7:translation`` @code → priority ('gender_source_value', 2)                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| person_id_extension                     | FIELD    |       | ``hl7:id[not(@nullFlavor="UNK")]`` @extension                                                                                                         |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| person_id_root                          | FIELD    |       | ``hl7:id[not(@nullFlavor="UNK")]`` @root                                                                                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_codeSystem_direct          | FIELD    |       | ``hl7:patient/hl7:raceCode[not(@nullFlavor="OTH")]`` @codeSystem                                                                                      |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_codeSystem_sdtc            | FIELD    |       | ``hl7:patient/sdtc:raceCode`` @codeSystem                                                                                                             |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_codeSystem_translated      | FIELD    |       | ``hl7:patient/hl7:raceCode/hl7:translation`` @codeSystem                                                                                              |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_code_direct                | FIELD    |       | ``hl7:patient/hl7:raceCode[not(@nullFlavor="OTH")]`` @code                                                                                            |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_code_sdtc                  | FIELD    |       | ``hl7:patient/sdtc:raceCode`` @code                                                                                                                   |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_code_translated            | FIELD    |       | ``hl7:patient/hl7:raceCode/hl7:translation`` @code                                                                                                    |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_id_direct                  | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=race_concept_code_direct, vocabulary_oid=race_concept_codeSystem_direct, default=None)``                   |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_id_sdtc                    | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=race_concept_code_sdtc, vocabulary_oid=race_concept_codeSystem_sdtc, default=None)``                       |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_concept_id_translated              | DERIVED  |       | ``VT.codemap_xwalk_concept_id(concept_code=race_concept_code_translated, vocabulary_oid=race_concept_codeSystem_translated, default=None)``           |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_source_value_direct                | FIELD    |       | ``hl7:patient/hl7:raceCode`` @code → priority ('race_source_value', 1)                                                                                |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_source_value_sdtc                  | FIELD    |       | ``hl7:patient/sdtc:raceCode`` @code → priority ('race_source_value', 2)                                                                               |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| race_source_value_translated            | FIELD    |       | ``hl7:patient/hl7:raceCode/hl7:translation`` @code → priority ('race_source_value', 3)                                                                |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| state                                   | FIELD    |       | ``hl7:addr/hl7:state`` @#text                                                                                                                         |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+
| zip                                     | FIELD    |       | ``hl7:addr/hl7:postalCode`` @#text                                                                                                                    |
+-----------------------------------------+----------+-------+-------------------------------------------------------------------------------------------------------------------------------------------------------+

Config type reference
---------------------

+-------------+----------------------------------------------------------------+
| config_type | Meaning                                                        |
+=============+================================================================+
| ROOT        | Defines the XPath root element for this config                 |
+-------------+----------------------------------------------------------------+
| FIELD       | Extracts an XML attribute value via XPath                      |
+-------------+----------------------------------------------------------------+
| DERIVED     | Computed by a Python function from other fields                |
+-------------+----------------------------------------------------------------+
| HASH        | MD5/hash of a set of fields, used as a surrogate key           |
+-------------+----------------------------------------------------------------+
| FK          | Foreign key copied from a joined dataset                       |
+-------------+----------------------------------------------------------------+
| CONSTANT    | Fixed literal value written to every row                       |
+-------------+----------------------------------------------------------------+
| PRIORITY    | Coalesces the first non-null value from prioritized candidates |
+-------------+----------------------------------------------------------------+
| FILENAME    | The source XML filename                                        |
+-------------+----------------------------------------------------------------+
| None        | Not populated (placeholder)                                    |
+-------------+----------------------------------------------------------------+