% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/functions_summary.R
\name{summary.metaConvert}
\alias{summary.metaConvert}
\title{Synthesize information of an object of class \dQuote{metaConvert} into a dataframe}
\usage{
\method{summary}{metaConvert}(
  object,
  digits = 3,
  flags = TRUE,
  flag_options = list(),
  guidance = TRUE,
  include_raw = TRUE,
  ...
)
}
\arguments{
\item{object}{an object of class \dQuote{metaConvert}}

\item{digits}{an integer value specifying the number of decimal places for the rounding of numeric values. Default is 3.}

\item{flags}{a logical value indicating whether quality/plausibility flags should be generated. Default is TRUE. The \code{es_flags} column includes both input validation flags (generated during \code{\link{convert_df}}) and post-computation quality flags.}

\item{flag_options}{a named list of thresholds overriding the defaults (and any options set in \code{\link{convert_df}}).
Available options:
\itemize{
\item \code{smd_max} (default 3): |SMD| above this value is flagged
\item \code{r_max} (default 0.95): same, for |r|
\item \code{log_or_max} (default 5): same, for |logOR| and |logRR|
\item \code{n_min} (default 10): flag sample sizes below this value
\item \code{iqr_mult} (default 3): IQR multiplier for the cross-row outlier detection
\item \code{dispersion_max_smd} / \code{dispersion_max_r} / \code{dispersion_max_logor} (defaults 0.5 / 0.15 / 1.0): maximum SD of the ES across estimation methods (SMD, correlation, logOR/logRR)
\item \code{diff_max_smd} / \code{diff_max_r} / \code{diff_max_logor} (defaults 1.0 / 0.3 / 2.0): maximum min-max ES difference across estimation methods
\item \code{overlap_min} (default 0.80): minimum CI overlap between the min/max estimates (0-1 scale)
\item \code{enable_cross_row} (default TRUE): enable/disable the cross-row checks
\item \code{direction_conflict_min} (default 2): number of significantly-positive and significantly-negative studies needed to raise the direction conflict flag (G1)
}}

\item{guidance}{a logical value indicating whether missing data guidance should be generated for rows where the effect size is NA. Default is TRUE. When enabled, a column \code{es_guidance} (or \code{es_guidance_crude}/\code{es_guidance_adjusted}) is appended, listing the closest estimation methods and which specific columns are missing.}

\item{include_raw}{a logical value indicating whether the raw input columns should be appended after the effect size columns in the returned dataframe. Default is TRUE.}

\item{...}{other arguments that can be passed to the function}
}
\value{
This function returns a dataframe with many columns. We present below the information stored in each column of the returned dataframe

\strong{1. Raw user information.}
The first columns placed at the left of the returned dataset are simply information provided
by the users to facilitate the identification of each row.
If the following columns are missing in the original dataset, these columns will not appear in
the returned dataset.

\tabular{ll}{
\code{row_id} \tab Row number in the original dataset.\cr
\tab \cr
\code{study_id} \tab Identifier of the study.\cr
\tab \cr
\code{author} \tab Name of the author of the study.\cr
\tab \cr
\code{year} \tab Year of publication of the study.\cr
\tab \cr
\code{predictor} \tab Name of the predictor (intervention, risk factor, etc.).\cr
\tab \cr
\code{outcome} \tab Name of the outcome.\cr
\tab \cr
\code{info_expected} \tab Types of input data users expect to be used to estimate their effect size measure.\cr
\tab \cr
}

\strong{2. Information on generated effect sizes.}
Then, the function returns information on calculations. For example, users can retrieve
the effect size measure estimated, the number and type(s) of input data allowing to estimate the
chosen effect size measure, and the method used to obtain a unique effect size if overlapping
input data were available.
These columns could have several suffix.
\itemize{
\item If users requested to separate crude and adjusted estimates,
then the following columns will be presented with both a "_crude" suffix and a "_adjusted" suffix.
\item If users did not request to separate the presentation of crude and adjusted estimates, the following columns
will have no suffix.
}

For example, let's take column "all_info". It can be "all_info_crude" (all input data used to estimate any crude effect size),
"all_info_adjusted" (all input data leading to estimate any adjusted effect size),
or "all_info" (all input data leading to estimate any crude or adjusted effect sizes).

To facilitate the presentation, we thus refer to these columns as \code{name_of_the_column*},
the \code{*} meaning that it could end by _crude, _adjusted or "".

\tabular{ll}{
\code{all_info*} \tab list of input data available in the dataset that was used to estimate any effect size measure.\cr
\tab \cr
\code{measure*} \tab effect size measure requested by the user.\cr
\tab \cr
\code{info_measure*} \tab input data available to estimate the requested effect size measure.\cr
\tab \cr
\code{n_estimations*} \tab number of input data available to estimate the requested effect size measure.\cr
\tab \cr
\code{es_selected*} \tab method chosen by users to estimate the main effect size when overlapping data are present.\cr
\tab \cr
\code{info_used*} \tab type of input data used to estimate the main effect size.\cr
\tab \cr
}

\strong{3. Main effect size.}
The following columns contain the key information, namely, the main effect size + standard error + 95\% CI.

Again, the suffix of these columns can vary depending on the separation of effect sizes
estimated from crude and adjusted input data.

\tabular{ll}{
\code{es*} \tab main effect size value.\cr
\tab \cr
\code{se*} \tab standard error of the effect size.\cr
\tab \cr
\code{es_ci_lo*} \tab lower bound of the 95\% CI around the effect size.\cr
\tab \cr
\code{es_ci_up*} \tab upper bound of the 95\% CI around the effect size.\cr
\tab \cr
}

\strong{4. Overlapping effect sizes}
These columns are useful ONLY if a given comparison (i.e., row) has multiple input data
enabling to compute the requested effect size measure.

These columns identify the smallest/largest effect size per comparison,
and some indicators of consistency.

Again, the suffix of these columns can vary depending on the separation of effect sizes
estimated from crude and adjusted input data.

\tabular{ll}{
\code{min_info*} \tab type of input data leading to the smallest effect size for the comparison.\cr
\tab \cr
\code{min_es_value*} \tab smallest effect size value for the comparison.\cr
\tab \cr
\code{min_es_se*} \tab standard error of the smallest effect size for the comparison.\cr
\tab \cr
\code{min_es_ci_lo*} \tab lower bound of the 95\% CI of the smallest effect size for the comparison.\cr
\tab \cr
\code{min_es_ci_up*} \tab upper bound of the 95\% CI of the smallest effect size for the comparison.\cr
\tab \cr
}

\tabular{ll}{
\code{max_info*} \tab type of input data leading to the largest effect size for the comparison.\cr
\tab \cr
\code{max_es_value*} \tab largest effect size value for the comparison.\cr
\tab \cr
\code{max_es_se*} \tab standard error of the largest effect size for the comparison.\cr
\tab \cr
\code{max_es_ci_lo*} \tab lower bound of the 95\% CI of the largest effect size for the comparison.\cr
\tab \cr
\code{max_es_ci_up*} \tab upper bound of the 95\% CI of the largest effect size for the comparison.\cr
\tab \cr
}

\tabular{ll}{
\code{diff_min_max*} \tab difference between the smallest and largest effect size for the comparison.\cr
\tab \cr
\code{overlap_min_max*} \tab \% of overlap between the 95\% CIs of the largest/smallest effect sizes for the comparison.\cr
\tab \cr
\code{dispersion_es*} \tab standard deviation of all effect sizes for the comparison.\cr
\tab \cr
}

\strong{5. Quality/plausibility flags}
When \code{flags = TRUE} (the default), a flags* column is added, containing
the semicolon-separated list of issues detected for the row (empty when none).

\tabular{ll}{
\code{flags*} \tab quality/plausibility flags for the effect size in this row.\cr
\tab \cr
}

Flag categories:
\itemize{
\item \strong{A (Numeric integrity)}: Inf/NaN values, negative SE, inverted CI, ES outside CI
\item \strong{B (Bounds violations)}: correlation outside \eqn{[-1,1]}, non-positive OR/RR, NNT in (-1,1), proportion outside \eqn{[0,1]}, RD outside \eqn{[-1,1]}
\item \strong{C (Plausibility)}: unusually large SMD, zero SE, high correlation, large logOR/logRR, small sample size
\item \strong{D (Cross-row outliers)}: ES or SE is an outlier relative to other rows (IQR method)
\item \strong{E (Internal consistency)}: high dispersion across estimation methods, low/zero CI overlap, large min-max difference
}

\strong{6. Missing data guidance}
When \code{guidance = TRUE} (the default), an es_guidance* column indicates,
for rows without an effect size, the closest estimation methods and which
input columns are missing (empty otherwise).

\tabular{ll}{
\code{es_guidance*} \tab guidance on which columns to add to obtain an effect size.\cr
\tab \cr
}
}
\description{
Synthesize information of an object of class \dQuote{metaConvert} into a dataframe
}
\details{
Summary method for objects of class \dQuote{metaConvert} produced by the \code{\link{convert_df}}
function. This function automatically:
\enumerate{
\item computes all effect sizes from all available input data
\item selects, if requested, a  main effect size for each association/comparison using the information passed by
the user in the \code{es_selected} argument of the \code{convert_df} function
\item identifies the smallest and largest effect size for each association/comparison
\item estimates the absolute difference between the smallest and largest effect size for each
association/comparison
\item estimates the percentage of overlap between the 95\% confidence intervals of the smallest and
largest effect size for each association/comparison
}
}
\examples{
### generate a summary of the results of an umbrella object
summary(
  convert_df(df.haza, measure = "g"),
  digits = 5)
}
\seealso{
\code{\link{metaConvert-package}} for the formatting of well-formatted datasets\cr
\code{\link{convert_df}} for estimating effect sizes from a dataset\cr
}
