Harmonization sheet

The harmonization sheet will serve as a set of instructions. It lists the source datasets, source variables (columns), and what modifications (if any) you will require.

head(harmonization_sheet_example) %>%
  kable()

It contains the following columns:

Cohort data

Three sample datasets have been provided with the psHarmonize package.

head(cohort_a) %>%
  kable()

head(cohort_b) %>%
  kable()

head(cohort_c) %>%
  kable()

Harmonization process

If we want to be able to pool data from these disparate cohorts together we will have to convert or recode some of the values in the original datasets.

For example, since the cohorts all have different units for continuous measurements (like height and weight), we will have to convert these values so they have the similar units across cohorts (cm and kg respectively). This will be handed with the function code type in the harmonization function.

Categorical values will have to be collapsed into similar values. Education will have to be recoded into groupings that appropriate account for the original values. This will be handed with the recode category code type in the harmonization function.

Creating harmonization sheet

The harmonization sheet is the input to the harmonization function. It is essentially a set of directions on how to modify data in order to create a harmonized dataset. This modification can be in the form of a function, recode, or no modification.

Calling harmonization function

When the harmonization function is called, the current cohort, subdomain, and visit is printed to the console.

harmonization_object <- harmonization(harmonization_sheet = harmonization_sheet_example, 
                          long_dataset = TRUE, 
                          wide_dataset = TRUE,
                          error_log = TRUE, 
                          source_variables = TRUE)
#> Currently on item: age; cohort: Cohort A; visit 1 / 1.
#> Currently on item: age; cohort: Cohort B; visit 1 / 1.
#> Currently on item: age; cohort: Cohort C; visit 1 / 1.
#> Currently on item: height; cohort: Cohort A; visit 1 / 3.
#> Currently on item: height; cohort: Cohort A; visit 2 / 3.
#> Currently on item: height; cohort: Cohort A; visit 3 / 3.
#> Currently on item: height; cohort: Cohort B; visit 1 / 1.
#> Currently on item: height; cohort: Cohort C; visit 1 / 1.
#> Currently on item: weight; cohort: Cohort A; visit 1 / 3.
#> Currently on item: weight; cohort: Cohort A; visit 2 / 3.
#> Currently on item: weight; cohort: Cohort A; visit 3 / 3.
#> Currently on item: weight; cohort: Cohort B; visit 1 / 1.
#> Currently on item: weight; cohort: Cohort C; visit 1 / 1.
#> Currently on item: education; cohort: Cohort A; visit 1 / 1.
#> Currently on item: education; cohort: Cohort B; visit 1 / 1.
#> Currently on item: education; cohort: Cohort C; visit 1 / 1.
#> [1] "Finished!"
#> 
#> # Harmonization status ----------------------------
#> 
#> 
#> ## Successfully harmonized ------------------------ 
#> 
#> Number of rows in harmonization sheet successfully harmonized:  
#>  16 / 16 
#> 
#> 
#> ## NOT successfully harmonized -------------------- 
#> 
#> Number of rows in harmonization sheet NOT successfully harmonized:  
#>  0 / 16 
#> 
#> 
#> # Values outside of range -------------------------
#> 
#> 
#> ## Numeric variables ------------------------------ 
#> 
#> Number of numeric rows with values set to NA:  
#>  0 / 0 
#> 
#> 
#> ## Categorical variables -------------------------- 
#> 
#> Number of categorical rows with values set to NA:  
#>  0 / 0

Extracting harmonization objects

The function will return multiple items in a list. You can extract data frames from the list with the $ operator and by referring to them by their name.

Possible items include:

• long_dataset
• wide_dataset
• error_log

Long dataset

The long dataset will have one row per participant, visit, and cohort.

harmonized_long_dataset <- harmonization_object$long_dataset

head(harmonized_long_dataset) %>%
  kable()

The column ID is the participant id. If the source data is longitudinal and has multiple visits per patient, that participant ID will have multiple rows of data in the long dataset.

For example the patients in cohort_a have multiple visits, so they will have multiple rows in the long dataset.

harmonized_long_dataset %>%
  filter(cohort == 'cohort_a') %>%
  arrange(visit) %>%
  head() %>%
  kable()

Wide dataset

The wide dataset will have one row per participant. The visit number will be added to the variable name as a suffix after an underscore.

harmonized_wide_dataset <- harmonization_object$wide_dataset

head(harmonized_wide_dataset) %>%
  kable()

Error log

The error log will have a status that indicates whether a specific variable was successfully harmonized.

error_log <- harmonization_object$error_log

table(error_log$completed_status)
#> 
#> Completed 
#>        16

Note: The error log will only be able to detect “processing” errors, and not “content” errors. For example, if the user enters coding instructions that are nonsensical or incorrect, but are still able to be executed, this function will not be able to detect it.

Creating reports

create_error_log_report(harmonized_object, path = './output/', file = 'Error_log.html')

Summary report

---

The summary report will create an html report showing summary statistics of your harmonized dataset. The harmonized object will be the input.

create_summary_report(harmonization_object = harmonization_object, path = './output/', file = 'Summary_report')

The output of the summary report should look like the following:

Summary output example.