harmonydata (version 0.3.1)

generate_crosswalk_table: Generate Crosswalk Table Function

Description

A crosswalk is a table that lists matched variables from different studies or instruments, enabling data harmonization across datasets.

Usage

generate_crosswalk_table(
  instruments,
  similarity,
  threshold,
  is_allow_within_instrument_matches = FALSE,
  is_enforce_one_to_one = FALSE
)

Value

A crosswalk table as a DataFrame.

Arguments

instruments

The original list of instruments, each containing a question. The sum of the number of questions in all instruments is the total number of questions which should equal both the width and height of the similarity matrix.

similarity

The cosine similarity matrix that is outputed from the match_instruments function.

threshold

The minimum threshold that we consider a match. This is applied to the absolute match value. So if a question pair has similarity 0.2 and threshold = 0.5, then that question pair will be excluded. Leave as None if you don't want to apply any thresholding.

is_allow_within_instrument_matches

Defaults to False. If this is set to True, we include crosswalk items that originate from the same instrument, which would otherwise be excluded by default.

is_enforce_one_to_one

Defaults to False. If this is set to True, we force all variables in the crosswalk table to be matched with exactly one other variable.

Author

Alex Nikic

Omar Hassoun

Details

This function generates a crosswalk table using a list of instruments and a similarity matrix, produced by the match_instruments function.

A crosswalk is a mapping between conceptually similar items (e.g., survey questions or variables) from different instruments. It is used to identify and align comparable variables across datasets that use different formats or wordings. This is especially useful in meta-analysis, data integration, and comparative research, where consistent constructs need to be analyzed across multiple sources.

The similarity matrix passed to this function is usually obtained from match_instruments.

Examples

# \donttest{
instrument_A = create_instrument_from_list(list(
  "How old are you?",
  "What is your gender?"
))

instrument_B = create_instrument_from_list(list(
  "Do you smoke?"
))

instruments = list(instrument_A, instrument_B)

match_response = match_instruments(instruments)
instrument_list = match_response$instruments
similarity_matrix = match_response$matches

crosswalk_table.df = generate_crosswalk_table(
  instrument_list, similarity_matrix, threshold = 0.7,
  is_allow_within_instrument_matches = FALSE, is_enforce_one_to_one = TRUE
)

# }