% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/foresttopr.R
\name{get_matching_genes}
\alias{get_matching_genes}
\title{Match association results across datasets by a key column}
\usage{
get_matching_genes(
  dfs,
  labels,
  gene_col = NULL,
  label_col = NULL,
  effect_type = c("OR", "beta")
)
}
\arguments{
\item{dfs}{A list of data frames containing association results. Each data
frame must contain a key column and effect size information.}

\item{labels}{A character vector of dataset labels of the same length as
\code{dfs}. These labels identify the source of each matched effect estimate.}

\item{gene_col}{Character scalar specifying the column name used to match
rows across datasets (e.g. gene identifier). If \code{NULL}, a suitable column
is inferred from common gene identifier names.}

\item{label_col}{Optional character scalar specifying the column name in the
reference dataset (the first element of \code{dfs}) to use as a human-readable
row label. If \code{NULL}, the matching key (\code{gene_col}) is used for labeling.}

\item{effect_type}{Character scalar specifying the effect scale to use.
Either \code{"OR"} (odds ratio) or \code{"beta"} (regression coefficient).
Matching is case-insensitive. Effect estimates are converted between
scales as needed.}
}
\value{
A data frame containing matched effect estimates with the following
columns:
\describe{
\item{key}{Matching key used to align rows across datasets.}
\item{label}{Row label used for display purposes.}
\item{set}{Dataset identifier corresponding to \code{labels}.}
\item{or}{Effect estimate on the requested scale.}
\item{p}{P-value associated with the effect estimate.}
\item{lcl}{Lower confidence interval bound.}
\item{ucl}{Upper confidence interval bound.}
}
}
\description{
\code{get_matching_genes()} aligns rows from multiple association result tables
using a shared key column (e.g. gene or feature identifier). Effect estimates
and confidence intervals are standardized across datasets, while row labels
are taken exclusively from the reference dataset (the first element of \code{dfs}).

This function is typically used internally by \code{\link{foresttopr}},
but may be useful on its own when preparing matched effect tables for
visualization or downstream analysis.
}
\details{
Rows are matched across datasets using the key column specified by
\code{gene_col}. The set of keys present in the reference dataset defines the
universe of rows retained. For each dataset, confidence intervals are
derived preferentially from explicit bounds, standard errors, or p-values,
depending on availability.

The returned table contains one row per matched key per dataset.
}
\seealso{
\code{\link{foresttopr}}
}
\keyword{internal}
