Improved documentation of match_instruments and generate_crosswalk_table functions

Author: omtarful

R/generate_crosswalk_table.R

@@ -22,11 +22,22 @@
 
 #' Generate Crosswalk Table Function
 #'
-#' Generate a crosswalk table for a list of instruments, given the similarity matrix that came out of the match function.
-#' A crosswalk is a list of pairs of variables from different studies that can be harmonised.
+#' This function generates a crosswalk table using a list of instruments and a similarity matrix,
+#' produced by the \code{\link{match_instruments}} function.
 #'
+#' @description
+#' A crosswalk is a table that lists matched variables from different studies or instruments,
+#' enabling data harmonization across datasets.
+#'
+#' @details
+#' 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 \code{\link{match_instruments}}.
 #' @param 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.
-#' @param similarity The cosine similarity matrix from Harmony
+#' @param similarity The cosine similarity matrix that is outputed from the \code{\link{match_instruments}} function.
 #' @param 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.
 #' @param 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.
 #' @param 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.
@@ -61,6 +72,7 @@
 #'
 #' @export
 #' @author Alex Nikic
+#' @author Omar Hassoun
 
 
 generate_crosswalk_table <- function(

R/match_instruments.R

@@ -27,10 +27,19 @@
 #'
 #' @param instruments A list of instruments to be matched.
 #' @param topics A list of topics with which to tag the questions. Default is empty.
-#' @param is_negate A boolean value to toggle question negation. Default is TRUE.
+#' @param is_negate A boolean indicating whether to apply negation-based preprocessing. Default is TRUE.
+#'
+#' This option addresses a common limitation in large language model (LLM) embeddings, where antonyms (e.g., "happy" and "sad") may be treated as similar due to contextual overlap.
+#' When \code{is_negate = TRUE}, the function prepends negation terms such as "not" or "didn't" to the input sentences and evaluates whether this increases or decreases their cosine similarity.
+#' If the similarity increases after negation, the model interprets the sentences as antonyms and returns a negative similarity score.
+#'
+#' When \code{is_negate = FALSE}, negation is skipped and most similarity values returned will be positive.
+#'
+#' The Harmony API defaults to \code{is_negate = TRUE}, as some users prefer detecting antonymy through negative similarity values, while others may prefer only positive scores.'
+#'
 #' @param clustering_algorithm A string value to select the clustering algorithm to use. Must be one of: "affinity_propagation", "kmeans", "deterministic", "hdbscan". Default is "affinity_propagation".
 #'
-#' @return A list of matched instruments returned from the 'Harmony Data API'.
+#' @return A list containing the matched instruments retrieved from the Harmony Data API. The returned object includes attributes such as the similarity matrix, identified clusters, associated cluster topics, and other relevant metadata.
 #'
 #' @examples
 #' \donttest{