Rmonize

https://maelstrom-research.github.io/Rmonize-documentation/
Admin
Rmonize is an R package developed by Maelstrom Research that facilitates streamlined, reusable, and...
Tokens:19,382
Snippets:245
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example of generating a DataSchema

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/dataschema_extract.html

Demonstrates extracting a DataSchema from an example dataset and inspecting the result.

```R
{

# Use Rmonize_examples to run examples.
library(dplyr)

dataschema <- dataschema_extract(Rmonize_examples$`Data_Processing_Elements_no_errors`)
glimpse(dataschema)

}
```

--------------------------------

### Generate a visual report example

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmonized_dossier_visualize.html

Example demonstrating how to prepare a harmonized dossier and summary, then generate the visual report in a temporary directory.

```R
{

library(fs)

# Use Rmonize_examples to run examples.
# Perform data processing

harmonized_dossier <- Rmonize_examples$`harmonized_dossier`
harmonized_dossier_summary <- Rmonize_examples$`summary_report_harmonized_dossier`

# Create a folder where the visual report will be placed

if(dir_exists(tempdir())) dir_delete(tempdir())
bookdown_path <- tempdir()

# Generate the visual report
harmonized_dossier_visualize(
  harmonized_dossier = harmonized_dossier,
  bookdown_path = bookdown_path,
  harmonized_dossier_summary = harmonized_dossier_summary)
  
# To open the file in a browser, open 'bookdown_path/docs/index.html'.
# Or use bookdown_open(bookdown_path) function.

}
```

--------------------------------

### Example of using as_dataschema_mlstr

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_dataschema_mlstr.html

Demonstrates converting an example DataSchema object and inspecting the result using glimpse.

```R
{

# Use Rmonize_examples to run examples.
library(dplyr)

dataschema_mlstr <- as_dataschema_mlstr(Rmonize_examples$`DataSchema`)
glimpse(dataschema_mlstr)

}
```

--------------------------------

### Example usage of as_data_proc_elem

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_data_proc_elem.html

Demonstrates how to use the function with an example dataset provided by Rmonize.

```R
{

# Use Rmonize_examples to run examples.
library(dplyr)

data_proc_elem <- as_data_proc_elem(Rmonize_examples$`Data_Processing_Elements_no_errors`)

head(data_proc_elem)

}
```

--------------------------------

### Access Rmonize examples and templates

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/a-install-your-working-environment.html

Commands to list available example datasets or access downloadable templates provided by the package.

```R
# See available examples
names(Rmonize_examples)

# Downloadable templates are also available
Rmonize_templates()
```

--------------------------------

### Load input datasets

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Retrieve example input datasets from the Rmonize_examples object.

```R
# Get the input datasets
dataset_study1 <- Rmonize_examples$input_dataset_study1
dataset_study2 <- Rmonize_examples$input_dataset_study2
dataset_study3 <- Rmonize_examples$input_dataset_study3
dataset_study4 <- Rmonize_examples$input_dataset_study4
dataset_study5 <- Rmonize_examples$input_dataset_study5
```

--------------------------------

### Example: Inspecting a Data Processing Elements object

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/data_proc_elem_evaluate.html

Demonstrates loading an example Data Processing Elements object and inspecting its structure using glimpse.

```R
{
# Use Rmonize_examples to run examples.
library(dplyr)

data_proc_elem <- Rmonize_examples$`Data_Processing_Elements_no_errors`

glimpse(data_proc_elem)
}
```

--------------------------------

### Example usage of pooled_harmonized_dataset_create

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/pooled_harmonized_dataset_create.html

Demonstrates how to process a harmonized dossier using example data and inspect the resulting pooled dataset.

```R
{

# Use Rmonize_examples to run examples.
 
library(dplyr)

# Perform data processing
harmonized_dossier <- Rmonize_examples["harmonized_dossier"][[1]]

# create the pooled harmonized dataset from the harmonized dossier
pooled_harmonized_dataset <- pooled_harmonized_dataset_create(harmonized_dossier)
  
glimpse(pooled_harmonized_dataset)
  
}
#> Rows: 13,500
#> Columns: 9
#> $ adm_unique_id             <chr> "PID7216", "PID5380", "PID5531", "PID7612", …
#> $ adm_study_id              <chr+lbl> "1", "1", "1", "1", "1", "1", "1", "1", …
#> $ sdc_age_m                 <int> 27, 38, 27, 26, 33, 31, 32, 29, 29, 26, 33, …
#> $ sdc_marital_m             <int+lbl> 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1…
#> $ lsb_alc_binge_m_preg      <int+lbl> 0, 0, 0, 0, NA, 0, 0, 0, 0, 0, 0, 0, 0, …
#> $ lsb_alc_binge_m_first_tri <int+lbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, …
#> $ preg_gestational_age_del  <int> 41, 38, 39, 41, 40, 38, 38, 39, 41, 40, 41, …
#> $ sdc_sex_c                 <int+lbl> 1, 2, 1, 1, 1, 2, 1, 1, 1, 1, 1, 2, 1, 1…
#> $ pm_birthweight            <dbl> 2603.164, 3295.346, 3426.888, 3112.095, 2394…
```

--------------------------------

### Install and load Rmonize

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/a-install-your-working-environment.html

Commands to install the Rmonize package from CRAN or GitHub and load it into the current R session.

```R
# To install Rmonize from CRAN:
install.packages("Rmonize")

# To install Rmonize from Github:
remotes::install_github(
  repo = "https://github.com/maelstrom-research/Rmonize",
  ref = "main")

# Load the package
library(Rmonize)
```

--------------------------------

### Install the car package

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/a-install-your-working-environment.html

Command to install the 'car' package, which is required by Rmonize for variable recoding.

```R
# Install package car from CRAN
install.packages("car")
```

--------------------------------

### List available Rmonize examples

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Display the names of the synthetic datasets included with the package for testing and demonstration purposes.

```R
# See available examples
names(Rmonize_examples)
```

--------------------------------

### Example usage of as_harmonized_dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_harmonized_dossier.html

Demonstrates how to process a harmonized dossier object using the Rmonize_examples dataset.

```R
{

# Use Rmonize_examples to run examples.
 
library(dplyr)

harmonized_dossier <- Rmonize_examples[["harmonized_dossier"]]
harmonized_dossier <- as_harmonized_dossier(harmonized_dossier)

glimpse(harmonized_dossier$dataset_study1)

}
```

--------------------------------

### Perform data evaluation on a dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmonized_dossier_evaluate.html

Example demonstrating the evaluation process using Rmonize_examples data.

```R
{

# Use Rmonize_examples to run examples.
library(dplyr)

# Perform data processing
harmonized_dossier <- Rmonize_examples$`harmonized_dossier`

eval_harmo <- harmonized_dossier_evaluate(harmonized_dossier)

glimpse(eval_harmo)
```

--------------------------------

### Perform data processing with harmo_process

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmo_process.html

Example demonstrating the execution of the harmonization process using example datasets and schemas.

```R
{
# Use Rmonize_examples to run examples.

library(dplyr)
library(stringr)
library(lubridate)

# Perform data processing
dossier <- Rmonize_examples[str_detect(names(Rmonize_examples),"input_dataset_study")]
names(dossier) <- str_remove(names(dossier), "input_")
dataschema <- Rmonize_examples$`DataSchema`
data_proc_elem <- Rmonize_examples$`Data_Processing_Elements_no_errors`

harmonized_dossier <- harmo_process(
  dossier,
  dataschema,
  data_proc_elem,
  harmonized_col_dataset = 'adm_study_id')
  
glimpse(harmonized_dossier$dataset_study1)
}
```

--------------------------------

### Examples of is_dataschema usage

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/is_dataschema.html

Demonstrates testing various objects against the DataSchema validation criteria.

```R
{

# Use Rmonize_examples to run examples.

is_dataschema(Rmonize_examples$`DataSchema`)
is_dataschema(Rmonize_examples$`Data_Processing_Elements_no_errors`)
is_dataschema(iris)

}
#> [1] FALSE
```

--------------------------------

### Example of showing harmonization errors

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/show_harmo_error.html

Demonstrates how to use the function with an example dataset to output a status summary to the console.

```R
{
# Use Rmonize_examples to run examples.
library(dplyr)

# Perform data processing
harmonized_dossier <- Rmonize_examples$`harmonized_dossier`

# Show error(s) on the console
show_harmo_error(harmonized_dossier)
}
#> 
#> 
#> - STATUS SUMMARY: ----------------------------------------------------
#> 
#> # A tibble: 8 × 3
#>   `Mlstr_harmo::rule_category` `Total number of algorithms` success
#>   <chr>                        <chr>                        <chr>  
#> 1 case_when                    6                            100 %  
#> 2 direct_mapping               7                            100 %  
#> 3 id_creation                  5                            100 %  
#> 4 impossible                   5                            100 %  
#> 5 operation                    6                            100 %  
#> 6 other                        1                            100 %  
#> 7 paste                        5                            100 %  
#> 8 recode                       10                           100 %  
#> 
```

--------------------------------

### Validate a DataSchema object

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_dataschema.html

Example demonstrating the use of as_dataschema to process an example dataset and inspect the resulting structure.

```R
{

# Use Rmonize_examples to run examples.
library(dplyr)

dataschema <- as_dataschema(Rmonize_examples$`DataSchema`)
glimpse(dataschema)

}
```

--------------------------------

### Read input elements for processing

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/d-process-inputs-and-generate-harmonized-outputs.html

Retrieve example input datasets, the DataSchema, and a DPE containing potential processing errors from the Rmonize package.

```R
# Get the input datasets
dataset_study1 <- Rmonize_examples$input_dataset_study1
dataset_study2 <- Rmonize_examples$input_dataset_study2
dataset_study3 <- Rmonize_examples$input_dataset_study3
dataset_study4 <- Rmonize_examples$input_dataset_study4
dataset_study5 <- Rmonize_examples$input_dataset_study5

# Get the DataSchema
dataschema <- Rmonize_examples$DataSchema

# Get the Data Processing Elements
dpe_with_errors <- Rmonize_examples$Data_Processing_Elements_with_errors
# This version contains some examples of potential processing errors.
```

--------------------------------

### Access original study datasets

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Retrieve example datasets from different file formats provided within the Rmonize package.

```R
# Get original datasets that were read from different file formats

# Datasets from .sav files that contain variable metadata
original_dataset_study1 <- Rmonize_examples$original_dataset_study1
original_dataset_study2 <- Rmonize_examples$original_dataset_study2

# Dataset from .csv file, with no data dictionary
original_dataset_study3 <- Rmonize_examples$original_dataset_study3

# Datasets from .xlsx files, with data dictionaries in separate files
original_dataset_study4 <- Rmonize_examples$original_dataset_study4
original_dataset_study5 <- Rmonize_examples$original_dataset_study5
```

--------------------------------

### Examples of is_data_proc_elem usage

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/is_data_proc_elem.html

Demonstrates validation checks against various objects, including valid and invalid inputs.

```R
{

# Use Rmonize_examples to run examples.

is_data_proc_elem(Rmonize_examples$`Data_Processing_Elements_no_errors`)
is_data_proc_elem(Rmonize_examples$`DataSchema`)
is_data_proc_elem(iris)
}
#> [1] FALSE
```

--------------------------------

### Extract and Assign Data Dictionaries

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Demonstrates how to extract data dictionaries from datasets or assign them from existing Rmonize examples.

```R
original_dd_study1 <- data_dict_extract(original_dataset_study1)
original_dd_study2 <- data_dict_extract(original_dataset_study2)

# If data dictionaries are provided as separate files, assign them separately
original_dd_study4 <- Rmonize_examples$original_data_dictionary_study4
original_dd_study5 <- Rmonize_examples$original_data_dictionary_study5

# A minimal data dictionary can be extracted from any dataset, but it provides very limited information
extracted_dd_study3 <- data_dict_extract(original_dataset_study3)
```

--------------------------------

### Load Rmonize and supporting packages

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Initialize the environment by loading Rmonize, madshapR, fabR, and tidyverse packages.

```R
# Load relevant packages
library(Rmonize)
library(madshapR) # Additional functions to work with data dictionaries
library(fabR) # Additional functions to help with importing data

library(tidyverse) # Collection of R packages for data science
```

--------------------------------

### Load Rmonize packages

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/e-summarize-and-secure-harmonized-outputs.html

Initialize the environment by loading Rmonize, fabR, and tidyverse libraries.

```R
# Load relevant packages
library(Rmonize)
library(fabR) # Additional functions to help with importing data
library(tidyverse) # Collection of R packages for data science
```

--------------------------------

### Access Rmonize documentation and website

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/a-install-your-working-environment.html

Commands to retrieve help documentation within R or open the official Rmonize website.

```R
# Get package documentation in R
?Rmonize
help("Rmonize")

# Access the website with a function
Rmonize_website()
```

--------------------------------

### Create a dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Group multiple datasets into a dossier using dossier_create. Ensure dataset names in the dossier match the input_dataset column in the Data Processing Elements.

```R
# Group multiple datasets into a dossier.
# IMPORTANT: The names of the datasets in the dossier must match the column
# input_dataset in the Data Processing Elements.
# These will also be used in documentation of the harmonization outputs.

input_dossier <- dossier_create(list(
  dataset_study1,
  dataset_study2,
  dataset_study3,
  dataset_study4,
  dataset_study5))
```

--------------------------------

### Retrieve DataSchema

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Load the DataSchema object from the Rmonize_examples package.

```R
# Get a DataSchema
dataschema <- Rmonize_examples$DataSchema
```

--------------------------------

### Basic usage of harmonized_dossier_summarize

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmonized_dossier_summarize.html

Demonstrates how to generate a summary report for a harmonized dossier using the Rmonize_examples dataset.

```R
{
# Use Rmonize_examples to run examples.
library(dplyr)

# Perform data processing
harmonized_dossier <- Rmonize_examples$`harmonized_dossier`
summary_harmo <- harmonized_dossier_summarize(harmonized_dossier)

glimpse(summary_harmo)
}
```

--------------------------------

### Rmonize_website()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/Rmonize_website.html

Opens the Rmonize package website in the default web browser.

```APIDOC
## Rmonize_website()

### Description
Opens the official Rmonize package website, which contains an overview of the Rmonize process, vignettes, user guides, function references, and package updates.

### Usage
`Rmonize_website()`

### Value
Returns nothing. The function is used for its side effect of opening a web page.
```

--------------------------------

### Create and Open Visual Reports

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/e-summarize-and-secure-harmonized-outputs.html

Generates an interactive visual report in a specified folder and opens it in a browser. The target folder must not exist prior to execution.

```R
# Produce a visual report of the harmonized datasets and variables
# You must specify a folder to contain the visual report files, and the 
# folder name must not already exist.
# WARNING: This script creates a folder 'tmp'.
bookdown_path <- paste0('tmp/',basename(tempdir()))
if(dir.exists(bookdown_path)) file.remove(bookdown_path)

harmonized_dossier_visualize(
  harmonized_dossier,
  bookdown_path = bookdown_path,
  harmonized_dossier_summary = summary_report_harmonized_dossier
  )

# Open the visual report in a browser.
bookdown_open(bookdown_path)
```

--------------------------------

### Initialize and Evaluate Data Dictionary

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Converts a data dictionary into a list format and performs an initial evaluation to identify potential issues.

```R
# Make the data dictionary a list containing a data frame named 'Variables'
modified_dd_study4 <- list(
  "Variables" = original_dd_study4)

# Rename columns using standardized names
modified_dd_study4$Variables <- 
  modified_dd_study4$Variables %>%
  rename(name = Variable,
         label = Label,
         valueType = `Data type`)

# Evaluate data dictionary only
data_dict_evaluate(modified_dd_study4)
```

--------------------------------

### Inspect DataSchema structure

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/Rmonize_examples.html

Use glimpse to view the structure of the DataSchema object within the Rmonize_examples list.

```R
library(dplyr)
glimpse(Rmonize_examples$`DataSchema`)
```

--------------------------------

### Clean and Save Prepared Datasets

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Applies data cleaning, associates a data dictionary, and saves the resulting dataset as an R file.

```R
# Prepare a version of the cleaned validated input dataset (with associated data dictionary)
input_dd_study4 <- formatted_dd_study4
input_dataset_study4 <- formatted_dataset_study4 %>%
  # Erroneous values noted in summary reports can be removed
  mutate(age_v1 = ifelse(age_v1>100, NA, age_v1)) %>%
  # If desired, specify the column that provides unique IDs
  as_dataset(col_id = "ID") %>%
  # Associate the data dictionary
  data_dict_apply(data_dict = input_dd_study4)

# Prepare a version of the cleaned validated input dataset as an R file
saveRDS(input_dataset_study4, paste0(output_path,"/input_dataset_study4.rds"))
```

--------------------------------

### Rmonize_templates()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/Rmonize_templates.html

Opens the online documentation page where users can download templates.

```APIDOC
## Rmonize_templates()

### Description
Opens a web page in the default browser to allow users to download Rmonize templates.

### Usage
`Rmonize_templates()`

### Value
Returns nothing. The function is called for its side effect of opening a URL.

### Example
```r
Rmonize_templates()
```
```

--------------------------------

### Function signature for as_data_proc_elem

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_data_proc_elem.html

Basic syntax for calling the as_data_proc_elem function.

```R
as_data_proc_elem(object)
```

--------------------------------

### Open Rmonize website

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/Rmonize_website.html

Opens the official Rmonize package website in the default web browser.

```R
Rmonize_website()
```

```R
{

Rmonize_website()

}
```

--------------------------------

### Create and process a harmonized dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/d-process-inputs-and-generate-harmonized-outputs.html

Initializes a dossier from a list of datasets and executes the harmonization process using a specified DataSchema and DPE.

```R
input_dossier <- dossier_create(list(
  dataset_study1,
  dataset_study2,
  dataset_study3,
  dataset_study4,
  dataset_study5))

# Run processing function
harmonized_dossier_with_errors <- harmo_process(
  object = input_dossier,
  dataschema = dataschema,
  data_proc_elem = dpe_with_errors,
  harmonized_col_dataset = 'adm_study_id') # Identifies the harmonized variable 
                                           # to use as dataset identifiers
```

--------------------------------

### show_harmo_error(harmonized_dossier, show_warnings = TRUE)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/show_harmo_error.html

Prints a summary of data processing in the console, including errors and an overview of harmonization rules.

```APIDOC
## show_harmo_error(harmonized_dossier, show_warnings = TRUE)

### Description
Reads a harmonized dossier, which is the product of `harmo_process()`, to list processes, any errors, and an overview of each harmonization rule. The output is printed directly to the console.

### Arguments
- **harmonized_dossier** (list) - Required - A list containing the harmonized dataset(s).
- **show_warnings** (logical) - Optional - Whether the function should print warnings or not. Defaults to TRUE.

### Value
Nothing is returned. The function prints messages to the console.

### Example
```r
library(dplyr)
# Perform data processing
harmonized_dossier <- Rmonize_examples$`harmonized_dossier`

# Show error(s) on the console
show_harmo_error(harmonized_dossier)
```
```

--------------------------------

### Generate and Export Dataset Summaries

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Creates descriptive statistics for a dataset and exports the results to an Excel file. Note that this script creates a 'tmp' directory.

```R
# Summarize a dataset with an associated data dictionary
summary_dataset_with_dd_study4 <- dataset_summarize(
  dataset = dataset_with_dd_study4)

# View the summary outputs
View(summary_dataset_with_dd_study4)
summary_dataset_with_dd_study4$`Numerical variable summary` %>% View()

# WARNING: This script creates a folder 'tmp'.
output_path <- paste0('tmp/',basename(tempdir()))
dir.create(output_path)
write_excel_allsheets(
  summary_dataset_with_dd_study4, paste0(output_path,"/summary_dataset_with_dd_study4.xlsx"))
```

--------------------------------

### Evaluate Dataset and Data Dictionary

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Prepare a dataset and evaluate it against a data dictionary to identify potential issues.

```R
# Format the dataset
compatible_dataset_study4 <- 
  as_dataset(original_dataset_study4, col_id = "ID")

# Evaluate the dataset and data dictionary together, as separate objects
# Tip: Assign the output to an object for easier viewing.
dataset_evaluation_study4 <- dataset_evaluate(
  dataset = compatible_dataset_study4,
  data_dict = compatible_dd_study4)

# View the new informational messages in the RStudio viewer
View(dataset_evaluation_study4[["Dataset assessment"]])
```

--------------------------------

### Load Rmonize and dependencies

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/d-process-inputs-and-generate-harmonized-outputs.html

Load the Rmonize package along with tidyverse and lubridate for data manipulation and date-time handling.

```R
# Load relevant packages
library(Rmonize)
library(tidyverse) # Collection of R packages for data science
library(lubridate) # R package for working with date-times
```

--------------------------------

### harmo_process()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/index.html

Generates harmonized dataset(s) and associated metadata.

```APIDOC
## harmo_process()

### Description
Generates harmonized dataset(s) and associated metadata.
```

--------------------------------

### harmo_process(object, dataschema, data_proc_elem, harmonized_col_dataset, harmonized_col_id, .debug)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmo_process.html

Generates a harmonized dossier from input datasets based on a provided DataSchema and Data Processing Elements.

```APIDOC
## harmo_process

### Description
Generates a harmonized dossier from input dataset(s) and associated metadata using a DataSchema and Data Processing Elements.

### Signature
`harmo_process(object, dataschema, data_proc_elem, harmonized_col_dataset, harmonized_col_id, .debug = FALSE)`

### Parameters
- **object** (data frame or list of data frames) - Required - Input dataset(s).
- **dataschema** (DataSchema object) - Required - The DataSchema object defining core variables and metadata.
- **data_proc_elem** (Data Processing Elements object) - Required - The Data Processing Elements object specifying input elements and algorithms.
- **harmonized_col_dataset** (character string) - Optional - Identifying the column to use for dataset names.
- **harmonized_col_id** (character string) - Optional - Identifying the column present in every dataset to use as a participant identifier.
- **.debug** (boolean) - Optional - Allow user to test the inputs before processing harmonization.

### Returns
- **list** - A list of data frame(s) containing harmonized dataset(s) with DataSchema and Data Processing Elements preserved as attributes.
```

--------------------------------

### Summarize and visualize harmonized outputs

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Generates summary statistics and visual reports for harmonized dossiers. The visualization function requires a non-existent folder path to store output files.

```R
# Produce a summary report of the harmonized datasets and variables
summary_report_harmonized_dossier <- 
  harmonized_dossier_summarize(harmonized_dossier)

# Produce a visual report of the harmonized datasets and variables
# You must specify a folder to contain the visual report files, and the folder name must not already exist.
# WARNING: This script creates a folder 'tmp'.
bookdown_path <- paste0('tmp/',basename(tempdir()))
if(dir.exists(bookdown_path)) file.remove(bookdown_path)

harmonized_dossier_visualize(
  harmonized_dossier,
  bookdown_path = bookdown_path,
  harmonized_dossier_summary = summary_report_harmonized_dossier
    )

# Open the visual report in a browser.
bookdown_open(bookdown_path)
```

--------------------------------

### Call Rmonize_templates

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/Rmonize_templates.html

Executes the function to open the online template repository in a web browser.

```R
Rmonize_templates()
```

```R
{

Rmonize_templates()

}
```

--------------------------------

### Associate and Evaluate Datasets with Data Dictionaries

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Links a formatted dataset with its corresponding data dictionary and performs an evaluation to ensure data integrity.

```R
# Associate a dataset with its data dictionary (only possible when there are no
# errors in the previous evaluation)
dataset_with_dd_study4 <- data_dict_apply(
  dataset = formatted_dataset_study4,
  data_dict = formatted_dd_study4)

# If you want, evaluate the dataset and data dictionary together
# (confirms that there are no errors, but otherwise provides same information)
dataset_evaluate(dataset_with_dd_study4)
```

--------------------------------

### Update function parameters for Rmonize 2.0.0

Source: https://maelstrom-research.github.io/Rmonize-documentation/news/index.html

Comparison of function signatures between version 1.1.0 and 2.0.0, showing the consolidation of multiple arguments into a single 'dossier' parameter.

```R
harmonized_dossier_evaluate(
  harmonized_dossier,dataschema,taxonomy,as_dataschema_mlstr)

harmonized_dossier_summarize(
  harmonized_dossier,group_by,dataschema,data_proc_elem,
  taxonomy,valueType_guess)

harmonized_dossier_visualize(
  harmonized_dossier,bookdown_path,group_by,harmonized_dossier_summary,
  dataschema,data_proc_elem,valueType_guess,taxonomy)
```

```R
harmonized_dossier_evaluate(harmonized_dossier)
harmonized_dossier_summarize(harmonized_dossier)
harmonized_dossier_visualize(harmonized_dossier,bookdown_path)
```

--------------------------------

### Recode values in DPE

Source: https://maelstrom-research.github.io/Rmonize-documentation/dpe/index.html

Use this syntax in the algorithm column to map input values to harmonized outputs. Separate mappings with semicolons and use ELSE = NA for default values.

```R
recode(
0            = "low"   ;
c(1:10)      = "mid"   ;
c(-7, -99)   = NA    )
```

--------------------------------

### Function signature for harmo_process

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmo_process.html

The standard function signature for initiating the harmonization process.

```R
harmo_process(
  object,
  dataschema = attributes(object)$`Rmonize::DataSchema`,
  data_proc_elem = attributes(object)$`Rmonize::Data Processing Elements`,
  harmonized_col_dataset = attributes(object)$`Rmonize::harmonized_col_dataset`,
  harmonized_col_id = attributes(object)$`Rmonize::harmonized_col_id`,
  .debug = FALSE
)
```

--------------------------------

### pooled_harmonized_dataset_create()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/index.html

Generates a pooled harmonized dataset from a harmonized dossier.

```APIDOC
## pooled_harmonized_dataset_create()

### Description
Generates a pooled harmonized dataset from a harmonized dossier.
```

--------------------------------

### Define case_when conditions in DPE

Source: https://maelstrom-research.github.io/Rmonize-documentation/dpe/index.html

Use this syntax to define conditional logic for harmonization. Ensure all output values and NA types are consistent within the statement.

```R
case_when(
var_x == 1                 ~ 1L
var_x == 0 & !is.na(var_y) ~ 0L
ELSE                       ~ NA_integer_  )

case_when(
var_x == 1                 ~ "1"
var_x == 0 & !is.na(var_y) ~ "0"
ELSE                       ~ NA_character_)
```

--------------------------------

### is_data_proc_elem(object)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/is_data_proc_elem.html

Validates whether the input object is a properly formatted Data Processing Elements object.

```APIDOC
## is_data_proc_elem(object)

### Description
Tests if the input is a valid Data Processing Elements object. This function is used to validate input within other functions of the package or to check if an object is valid for use.

### Arguments
- **object** (any) - Required - A potential Data Processing Elements object to be evaluated.

### Value
- **logical** - Returns TRUE if the object is a valid Data Processing Elements object, FALSE otherwise.

### Examples
```r
is_data_proc_elem(Rmonize_examples$`Data_Processing_Elements_no_errors`)
is_data_proc_elem(Rmonize_examples$`DataSchema`)
is_data_proc_elem(iris)
```
```

--------------------------------

### Basic usage of show_harmo_error

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/show_harmo_error.html

Displays the function signature for printing harmonization process summaries.

```R
show_harmo_error(harmonized_dossier, show_warnings = TRUE)
```

--------------------------------

### BibTeX Citation for Rmonize

Source: https://maelstrom-research.github.io/Rmonize-documentation/authors.html

Use this BibTeX entry to cite the Rmonize package in academic publications.

```bibtex
@Manual{,
  title = {Rmonize: Tools for Data Harmonization},
  author = {Guillaume Fabre, Maelstrom Research},
  year = {2025},
  note = {R package version 2.0.0},
  url = {https://github.com/maelstrom-research/Rmonize/},
}
```

--------------------------------

### Function signature for pooled_harmonized_dataset_create

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/pooled_harmonized_dataset_create.html

The primary function signature showing required arguments and default attribute extraction from the harmonized dossier.

```R
pooled_harmonized_dataset_create(
  harmonized_dossier,
  harmonized_col_dataset =
    attributes(harmonized_dossier)$`Rmonize::harmonized_col_dataset`,
  harmonized_col_id = attributes(harmonized_dossier)$`Rmonize::harmonized_col_id`,
  dataschema = attributes(harmonized_dossier)$`Rmonize::DataSchema`,
  data_proc_elem = attributes(harmonized_dossier)$`Rmonize::Data Processing Elements`
)
```

--------------------------------

### Function signature for harmonized_dossier_visualize

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmonized_dossier_visualize.html

The basic function signature for generating a visual report from a harmonized dossier.

```R
harmonized_dossier_visualize(
  harmonized_dossier,
  bookdown_path,
  harmonized_dossier_summary = NULL
)
```

--------------------------------

### as_dataschema()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/index.html

Validates and coerces an object into a DataSchema object.

```APIDOC
## as_dataschema()

### Description
Validates and coerces an object as a DataSchema object.
```

--------------------------------

### data_proc_elem_evaluate(data_proc_elem, taxonomy = NULL)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/data_proc_elem_evaluate.html

Evaluates a Data Processing Elements object and returns a list of assessment reports.

```APIDOC
## data_proc_elem_evaluate

### Description
Assesses the content and structure of a Data Processing Elements object and generates reports of the results. This function evaluates data structure, presence of specific fields, coherence across elements, and data dictionary formats.

### Signature
`data_proc_elem_evaluate(data_proc_elem, taxonomy = NULL)`

### Parameters
- **data_proc_elem** (Data Processing Elements object) - Required - A Data Processing Elements object.
- **taxonomy** (data frame) - Optional - An optional data frame identifying a variable classification schema.

### Value
A list of data frames containing assessment reports.
```

--------------------------------

### Function signature for as_harmonized_dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_harmonized_dossier.html

The formal definition of the as_harmonized_dossier function and its parameters.

```R
as_harmonized_dossier(
  object,
  dataschema = attributes(object)$`Rmonize::DataSchema`,
  data_proc_elem = attributes(object)$`Rmonize::Data Processing Elements`,
  harmonized_col_id = attributes(object)$`Rmonize::harmonized_col_id`,
  harmonized_col_dataset = attributes(object)$`Rmonize::harmonized_col_dataset`,
  harmonized_data_dict_apply = FALSE
)
```

--------------------------------

### Generate and Export Harmonized Dossier Summaries

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/e-summarize-and-secure-harmonized-outputs.html

Produces a summary report of a harmonized dossier and exports it to an Excel file. Note that the script creates a 'tmp' directory.

```R
summary_report_harmonized_dossier <- 
  harmonized_dossier_summarize(harmonized_dossier)
# Note: This report is also provided in Rmonize_examples$summary_report_harmonized_dossier.

# Export to Excel
# WARNING: This script creates a folder 'tmp'.
output_path <- paste0('tmp/',basename(tempdir()))
dir.create(output_path)
write_excel_allsheets(
  summary_report_harmonized_dossier,
  paste0(output_path,"/summary_report_harmonized_dossier.xlsx"))
```

--------------------------------

### Correct Dataset and Data Dictionary Inconsistencies

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/c-explore-and-prepare-input-datasets-and-data-dictionaries.html

Update variable names in the data dictionary and adjust value types in the dataset to resolve compatibility issues.

```R
# Correct a variable name in the data dictionary to match the dataset
formatted_dd_study4 <- compatible_dd_study4
formatted_dd_study4$Variables <- 
  formatted_dd_study4$Variables %>%
  mutate(name = ifelse(name == "marital", "marital_v1", name))
formatted_dd_study4$Categories <- 
  formatted_dd_study4$Categories %>%
  mutate(variable = ifelse(variable == "marital", "marital_v1", variable))

# Adjust two variable valueTypes in the dataset to match the data dictionary
formatted_dataset_study4 <- compatible_dataset_study4 %>%
  mutate(
    # First convert "NA" strings to NA empty strings
    across(c(drink_four_preg_v1, drink_four_preg_v3), ~ na_if(.x, "NA")),
    # Convert the variables to integer
    across(c(drink_four_preg_v1, drink_four_preg_v3), as_any_integer))
```

--------------------------------

### Retrieve and filter Data Processing Elements

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Load the Data Processing Elements (DPE) and optionally filter for a specific study dataset.

```R
# Get the Data Processing Elements
dpe <- Rmonize_examples$Data_Processing_Elements_no_errors

# Get the Data Processing Elements for a single dataset (study1)
dpe_study1 <- dpe %>%
  filter(input_dataset == "dataset_study1")
```

--------------------------------

### Process datasets with Rmonize

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/b-simple-example-of-data-processing-with-Rmonize.html

Executes the harmonization process on either a full dossier or a single dataset using a DataSchema and Data Processing Elements (DPE).

```R
# Run processing function on all five datasets
harmonized_dossier <- harmo_process(
  object = input_dossier,
  dataschema = dataschema,
  data_proc_elem = dpe,
  harmonized_col_dataset = 'adm_study_id') # Identifies the harmonized variable to use as dataset identifiers

# Run processing function on a single dataset
harmonized_dossier_study1 <- harmo_process(
  object = dataset_study1,
  dataschema = dataschema,
  data_proc_elem = dpe_study1,
  harmonized_col_dataset = 'adm_study_id') # Identifies the harmonized variable to use as dataset identifiers
```

--------------------------------

### Function signature for harmonized_dossier_summarize

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/harmonized_dossier_summarize.html

The basic function call structure for assessing a harmonized dossier.

```R
harmonized_dossier_summarize(harmonized_dossier)
```

--------------------------------

### harmonized_dossier_visualize()

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/index.html

Generates a web-based visual report for a harmonized dossier.

```APIDOC
## harmonized_dossier_visualize()

### Description
Generates a web-based visual report for a harmonized dossier.
```

--------------------------------

### Basic usage of dataschema_extract

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/dataschema_extract.html

Syntax for calling the function with a Data Processing Elements object.

```R
dataschema_extract(data_proc_elem)
```

--------------------------------

### Evaluate Data Processing Elements

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/data_proc_elem_evaluate.html

Basic function signature for evaluating a Data Processing Elements object.

```R
data_proc_elem_evaluate(data_proc_elem, taxonomy = NULL)
```

--------------------------------

### Process DPEs and Validate Harmonization

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/d-process-inputs-and-generate-harmonized-outputs.html

Converts DPEs to the required format, executes the harmonization process, and checks for potential errors.

```R
# Get corrected DPEs with changes made based on error messages
dpe_no_errors <- 
  Rmonize_examples$Data_Processing_Elements_no_errors %>%
  as_data_proc_elem()

# Run processing function
harmonized_dossier <- harmo_process(
  object = input_dossier,
  dataschema = dataschema,
  data_proc_elem = dpe_no_errors,
  harmonized_col_dataset = 'adm_study_id' # Identifies the harmonized variable 
                                          # to use as dataset identifiers
)

# Confirm there are no errors
show_harmo_error(
  harmonized_dossier,
  show_warnings = TRUE
)
```

--------------------------------

### Identify processing errors

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/d-process-inputs-and-generate-harmonized-outputs.html

Extracts and displays specific processing errors from a harmonized dossier to facilitate debugging of DPE algorithms.

```R
# To identify processing errors to correct in the DPE
show_harmo_error(
  harmonized_dossier_with_errors,
  show_warnings = TRUE) # Can be informative, but can also be turned off, e.g., 
                        # if there are known warnings produced by processing algorithms
```

--------------------------------

### Create Pooled Harmonized Dataset

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/e-summarize-and-secure-harmonized-outputs.html

Combines individual harmonized datasets from a dossier into a single pooled dataset while preserving associated metadata.

```R
# Generate one pooled harmonized dataset from a harmonized dossier
pooled_harmonized_dataset <- 
  pooled_harmonized_dataset_create(
  harmonized_dossier = harmonized_dossier)
```

--------------------------------

### as_data_proc_elem(object)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_data_proc_elem.html

Validates if an object is a valid Data Processing Elements object and returns it with the appropriate Rmonize class attribute.

```APIDOC
## as_data_proc_elem(object)

### Description
Checks if an object is a valid Data Processing Elements object and returns it with the appropriate `Rmonize::class` attribute. This function is used to validate inputs to ensure they conform to the required structure for data harmonization.

### Arguments
- **object** (any) - A potential Data Processing Elements object to be coerced.

### Value
A data frame with `Rmonize::class` 'data_proc_elem'.

### Example
```r
library(dplyr)
data_proc_elem <- as_data_proc_elem(Rmonize_examples$`Data_Processing_Elements_no_errors`)
head(data_proc_elem)
```
```

--------------------------------

### Define as_dataschema function signature

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/as_dataschema.html

The function signature for as_dataschema, including the object to be coerced and an optional flag for Maelstrom Research software compatibility.

```R
as_dataschema(object, as_dataschema_mlstr = FALSE)
```

--------------------------------

### Access and inspect the harmonized dossier

Source: https://maelstrom-research.github.io/Rmonize-documentation/articles/e-summarize-and-secure-harmonized-outputs.html

Load the harmonized dossier object and inspect its structure and attributes using RStudio tools.

```R
# Load harmonized dossier
harmonized_dossier <- Rmonize_examples$harmonized_dossier

# See information about the harmonized dossier in the RStudio viewer
View(harmonized_dossier)

# See additional attributes associated with the harmonized dossier
summary(attributes(harmonized_dossier))
```

--------------------------------

### Sourcing external R scripts

Source: https://maelstrom-research.github.io/Rmonize-documentation/dpe/index.html

Execute complex data processing logic defined in an external R file.

```R
source("my_file.R")
```

--------------------------------

### is_dataschema(object)

Source: https://maelstrom-research.github.io/Rmonize-documentation/reference/is_dataschema.html

Checks if the provided object is a valid DataSchema object. A valid DataSchema must be a list containing a 'Variables' data frame (with a 'name' column) and optionally a 'Categories' data frame (with 'variable' and 'name' columns).

```APIDOC
## is_dataschema(object)

### Description
Tests if the input is a valid DataSchema object. This function is used to validate input objects to ensure they meet the structural requirements for harmonization processes.

### Signature
`is_dataschema(object)`

### Arguments
- **object** (any) - A potential DataSchema object to be evaluated.

### Value
- **logical** - Returns TRUE if the object is a valid DataSchema, FALSE otherwise.

### Details
A DataSchema object is a list of data frames. It must contain a 'Variables' element (required) and may contain a 'Categories' element. 'Variables' must contain a 'name' column with unique entries. 'Categories' must contain 'variable' and 'name' columns, where the combination of these two columns must be unique.
```
Tokens:
Raw