Result objects¶

Result objects are frozen dataclasses. Scalar outputs, method settings, diagnostics, warnings, provenance, and row-level data remain inspectable after fitting. DataFrame-returning properties provide defensive copies.

`TrimAndFillResult`¶

This immutable result exposes the source and adjusted fits, selected side and estimator, estimated missing-study count (k0), its standard error and R0 p-value where applicable, iteration metadata, original/adjusted estimates and tau-squared values, warnings, and a defensive augmented_studies table.

source_result aliases the immutable original fit. side_selection and side_selection_statistic distinguish explicit direction from the automatic standard-error meta-regression rule; iteration_trace records each successive missing-count estimate. funnel() draws observed markers solid and imputed markers hollow, and accepts the ordinary contour options.

The adjusted fit's provenance contains a trim_and_fill_imputation transformation whose affected rows identify the synthetic studies.

The augmented table contains included observed rows plus synthetic rows for both zero and nonzero fills. Observed row_id values retain source positions; new IDs start above every source row ID. mirror_source is a display label, while mirror_source_row_id uniquely identifies the observed row even with duplicate labels. Excluded inputs remain in original_result, not the augmented fit. Its transformation records reference only rows present in the adjusted fit.

If all included effects are identical, no studies are imputed and missing-count uncertainty is unavailable (k0_standard_error=NaN, k0_pvalue=None). Automatic direction records side_selection="symmetric_effects" with a display side of "left", no regression statistic and no iterations. A negative L0 variance approximation also produces an unavailable standard error rather than zero. converged=True means a successful return; non-convergence raises ConvergenceError and does not return a partial fit.

`MetaAnalysisResult`¶

Analysis identity¶

Attribute	Meaning
`k`	Number of included studies
`model`	Resolved `common` or `random` model
`measure`	`GENERIC`, `OR`, `RR`, `RD`, `MD`, `SMD`, or `ZCOR`
`effect_scale`	Scale used for model calculations
`display_scale`	Identity, exponentiating, or hyperbolic-tangent display transformation

Pooled estimates¶

Attribute	Meaning
`estimate`	Pooled estimate on the model scale
`standard_error`	Standard error used by the selected mean CI
`ci_low`, `ci_high`, `ci`	Confidence interval on the model scale
`prediction_interval`	Random-effects prediction interval, when available
`display_estimate`	Pooled estimate on the display scale
`display_ci`	Display-scale confidence interval
`display_prediction_interval`	Display-scale prediction interval

For OR and RR, estimate, ci, and prediction_interval are logarithmic; their display counterparts are exponentiated ratios. For ZCOR, model values are Fisher's z and display counterparts are correlations obtained with tanh. Other measures use the identity transformation.

Heterogeneity¶

Attribute	Meaning
`tau2`	Between-study variance; zero for common-effect fits
`q`, `q_df`, `q_pvalue`	Cochran Q statistic, degrees of freedom, and p-value
`i2`	I-squared as a proportion from 0 to 1
`h2`	H-squared
`i2_method`	`q_based` or `tau2_typical_variance`
`heterogeneity`	The underlying `HeterogeneityResult` record

The definition differs by model and is specified under statistical methods.

Random-effects inverse-variance results also provide:

import meta_analyze as ma

result = ma.meta_analysis(effect=[0.1, 0.3, 0.2], variance=[0.02, 0.03, 0.01])
interval = result.tau2_confidence_interval(
    confidence_level=None,
    atol=None,
    max_iter=None,
)

Omitted controls reuse the fitted result's confidence level, tolerance, and iteration limit. The returned immutable Tau2ConfidenceInterval contains the tau-squared estimate, ci_low, ci_high, and ci tuple plus the monotonic tau, i2, and h2 estimates and intervals. It also records method="q_profile", numerical iterations, warnings, and is_empty. to_dict() returns a detached nested mapping.

The method is not available for common-effect, Mantel-Haenszel, or Peto results. When is_empty=True, [0, 0] is a constrained display of the formal empty confidence set, not a claim of zero uncertainty.

Methods and diagnostics¶

result.method is a MethodConfig containing the settings actually used:

Field	Meaning
`model`	Resolved model
`pooling_method`	`inverse_variance`, `mantel_haenszel`, or `peto`
`tau2_method`	`REML`, `PM`, `DL`, or `None`
`ci_method`	Resolved mean confidence-interval method
`confidence_level`	Fitted confidence level
`prediction_interval_method`	`HTS` or `HK-PR` when an interval was calculated; otherwise `None`
`missing`	Resolved missing-value policy
`atol`, `max_iter`	Numerical controls
`options`	Immutable outcome-specific key/value pairs

Convert outcome options to a mapping with dict(result.method.options). For a Mantel-Haenszel risk difference, this mapping includes mh_rd_variance="Sato-Greenland-Robins"; correction values and scopes remain separate entries. For Peto, it includes peto_pooling_tables="raw" and peto_heterogeneity="O-minus-E", and the result warnings retain the approximation's applicability caveat.

result.diagnostics is a FitDiagnostics record:

Field	Meaning
`converged`	Whether the requested fit converged
`iterations`	Iterations used; zero for closed-form/boundary fits
`tau2_at_boundary`	Whether tau-squared reached zero; `None` if not applicable

Recoverable statistical and workflow notes are stored in the immutable warnings tuple.

Provenance¶

result.provenance is an AnalysisProvenance record containing:

PyMetaAnalysis and provenance-schema versions;
analysis type and DataFrame/array source kind;
one InputFieldProvenance per public input;
DataFrame column_mapping when columns were selected by name;
total row count plus included and excluded row IDs;
structured TransformationRecord values.

result.source_data returns a defensive copy of the supplied DataFrame, or None for array-only input. Provenance deliberately does not embed the source DataFrame in serialized output.

Study tables¶

All study tables contain:

Column	Meaning
`row_id`	Stable zero-based input position
`study`	Display label
`effect`	Study effect on the model scale
`variance`, `standard_error`	Study sampling uncertainty
`included`	Whether the row entered the fit
`exclusion_reason`	Reason for exclusion or `None`
`weight`	Raw fitted weight or `NaN` if excluded
`normalized_weight`	Weight divided by included-weight sum

Accessors are:

result.study_results
result.excluded_studies
result.to_dataframe()

Generic-specific columns¶

Generic tables contain only the common columns above.

Binary-specific columns¶

Binary tables additionally contain raw counts, effect_display, continuity_corrected, rd_zero_variance, and mh_continuity_corrected. For a Peto result, effect and variance are the one-step study values while the pooled fit and Q are recalculated from raw tables.

Continuous-specific columns¶

Continuous tables additionally contain raw group summaries, effect_display, pooled_sd, cohen_d, and smd_correction_factor. MD rows leave SMD-only intermediates unavailable.

Correlation-specific columns¶

Correlation tables additionally contain the raw correlation, sample size n, and effect_display. The model-scale effect is Fisher's z, effect_display is the original correlation, and variance is 1 / (n - 3).

Summaries¶

summary() returns MetaAnalysisSummary. Its string form is concise human- readable output. to_dict() contains analysis identity, pooled/display estimates, interval and heterogeneity outputs, numerical controls, warnings, and outcome-specific method options.

Reports¶

method_details() produces Methods-style prose from resolved configuration. report(include_studies=True) returns a detached ResultReport:

report = result.report()
report.to_dict()
report.to_json(indent=2)
report.to_markdown()

See report schema for the complete serialized structure.

Plotting¶

forest() and funnel() return Matplotlib axes without calling show(). Matplotlib is imported only when a plot is requested. Parameters and display- funnel(contour_levels=(0.90, 0.95, 0.99)) adds reference-centered two-sided significance regions and an optional legend without altering the result.

Begg-Mazumdar funnel-asymmetry diagnostic¶

begg_test(exact=None, continuity_correction=False) returns an immutable BeggTestResult. Its primary fields are:

Attribute	Meaning
`tau`	Kendall's tau-b between standardized centered effects and sampling variances
`statistic`, `statistic_name`, `distribution`, `pvalue`	Exact Kendall S or asymptotic normal test output
`inference_method`, `continuity_correction`	Resolved inference path and correction flag
`response`, `predictor`	Explicit standardized-response and variance definitions
`response_tied_pairs`, `variance_tied_pairs`, `joint_tied_pairs`	Explicit tie diagnostics
`k`, `measure`, `effect_scale`	Included studies and source effect metadata
`method`, `correlation_method`, `warnings`	Diagnostic identity and interpretation cautions

to_dict() returns a detached mapping. The diagnostic consumes only included study rows and neither modifies nor enters the source result report.

Egger funnel-asymmetry diagnostic¶

egger_test(confidence_level=None) returns an immutable EggerTestResult for the classical standard-error Egger regression. Its primary fields are:

Attribute	Meaning
`intercept`, `intercept_standard_error`, `intercept_ci`	Asymmetry intercept and t interval
`statistic`, `statistic_name`, `distribution`, `df`, `pvalue`	Distribution-explicit two-sided `t_(k-2)` test of a zero intercept
`limit_estimate`, `limit_standard_error`, `limit_ci`	Extrapolated effect as standard error tends to zero, on the model scale
`display_limit_estimate`, `display_limit_ci`	Limit estimate transformed like the source result
`k`, `confidence_level`	Included studies and interval level
`method`, `model`, `predictor`	Explicit diagnostic configuration
`condition_number`	Condition number of the scaled weighted regression design
`warnings`	Few-study, effect-measure, and interpretation cautions

intercept is the intercept in the standardized-normal-deviate-on-precision form, although the implementation uses its algebraically equivalent weighted effect-on-standard-error form. to_dict() returns a detached mapping. The diagnostic consumes only included study rows and does not modify or become part of the original result report. See small-study effects before interpretation.

Harbord binary-OR asymmetry diagnostic¶

harbord_test(confidence_level=None) returns an immutable HarbordTestResult for an eligible meta_binary(..., measure="OR") result. Its primary fields are:

Attribute	Meaning
`intercept`, `intercept_standard_error`, `intercept_ci`	Tested efficient-score asymmetry intercept and t interval
`statistic`, `statistic_name`, `distribution`, `df`, `pvalue`	Distribution-explicit two-sided `t_(k-2)` test of a zero intercept
`limit_estimate`, `limit_standard_error`, `limit_ci`	Efficient-score limit coefficient and interval
`display_limit_estimate`, `display_limit_ci`	Limit coefficient and interval exponentiated to the OR scale
`residual_dispersion`	Multiplicative residual dispersion in the standardized-score regression
`method`, `model`, `response`, `predictor`, `weight_method`	Explicit diagnostic configuration and equivalent weighting form
`uses_continuity_correction`	Always `False`; the score is calculated from raw counts
`condition_number`, `warnings`	Scaled-design conditioning and applicability cautions

The standardized regression of Z/sqrt(V) on sqrt(V) is equivalent to a V-weighted regression of Z/V on 1/sqrt(V). It is independent of source pooling and study-level continuity correction. to_dict() returns a detached mapping, and the diagnostic does not modify or enter the original result report. See small-study effects before interpretation.

Peters binary-OR asymmetry diagnostic¶

peters_test(confidence_level=None) returns an immutable PetersTestResult for an eligible meta_binary(..., measure="OR") result. Its primary fields are:

Attribute	Meaning
`slope`, `slope_standard_error`, `slope_ci`	Tested log-OR-on-`1/N` asymmetry slope and t interval
`statistic`, `statistic_name`, `distribution`, `df`, `pvalue`	Distribution-explicit two-sided `t_(k-2)` test of a zero slope
`limit_estimate`, `limit_standard_error`, `limit_ci`	Extrapolated log OR as total sample size tends to infinity
`display_limit_estimate`, `display_limit_ci`	Extrapolated estimate and interval on the OR scale
`residual_dispersion`	Multiplicative WLS residual dispersion using the canonical weights
`method`, `model`, `predictor`, `weight_method`	Explicit diagnostic configuration
`continuity_correction`, `correction_scope`, `corrected_studies`	Reused study-effect correction contract
`condition_number`, `warnings`	Scaled-design conditioning and applicability cautions

The diagnostic reconstructs conventional study log odds ratios from retained four-cell counts, even if the source result used Peto pooling. Raw marginal totals define its S*F/N weights. to_dict() returns a detached mapping, and the diagnostic does not modify or enter the original result report. See small-study effects before interpretation.

`MetaRegressionResult`¶

Meta-regression has no unique pooled effect, so this result deliberately omits the scalar estimate, ci, and top-level prediction_interval attributes of MetaAnalysisResult.

Model and coefficient outputs¶

Attribute	Meaning
`k`, `p`, `residual_df`	Included studies, fitted coefficients, and `k-p`
`model`	Resolved `common` or `mixed` model
`coefficients`	Defensive coefficient DataFrame
`coefficient_covariance`	Labeled defensive covariance DataFrame
`classic_coefficient_covariance`	Covariance before Hartung-Knapp scaling
`design_info`	Original moderators, categories, references, and terms
`design_matrix`	Included-study encoded matrix
`global_test`	Distribution-explicit joint test of all non-intercept terms
`test_moderator(name)`	Joint test of one original moderator's encoded terms

Coefficient columns are:

term, moderator, estimate, standard_error, statistic, statistic_name,
df, pvalue, ci_low, ci_high

df is unavailable for normal/z inference and equals k-p for Hartung-Knapp t inference. ModeratorTestResult records distribution, df_num, optional df_denom, and every tested term, so chi-squared and F results are not conflated.

Under normal inference, coefficient_covariance and classic_coefficient_covariance are equal. Under either Hartung-Knapp variant, the former contains the selected inference adjustment while the latter retains the unadjusted weighted-model covariance used by diagnostics such as VIF.

Residual heterogeneity¶

Attribute	Meaning
`tau2`	Residual between-study variance; zero for common models
`tau2_null`	Intercept-only tau-squared on the same rows, when applicable
`pseudo_r2`, `pseudo_r2_raw`	Truncated and raw reduction in tau-squared
`heterogeneity`	Residual QE, df, p-value, I-squared, H-squared, and definition

Common models use q_based_residual; mixed models use tau2_typical_variance_residual. Pseudo-R² is unavailable for common, no-intercept, or zero-null-tau-squared fits.

Row table and prediction¶

The row table contains the original moderators plus:

fitted_value, residual, precision_weight, normalized_precision_weight,
leverage

Excluded rows retain identifiers and reasons while fitted diagnostics remain unavailable. Precision weight is not a universal contribution percentage for all regression coefficients.

predict(new_data) returns estimates, standard errors, and mean-effect confidence intervals. Mixed models add pi_low/pi_high for a new true effect. The fitted method.prediction_interval_method records either normal_or_t_k_minus_p for the default rule or riley for the opt-in t_(k-p-1) rule. Prediction reuses fitted categorical encoding and rejects unknown levels.

bubble() returns a Matplotlib axes for an intercept-containing fit with exactly one numeric moderator. Bubble area represents normalized precision weight; fitted bands reuse predict(). Other design shapes are rejected rather than assigned an implicit marginalization rule.

leave_one_out() returns a MetaRegressionLeaveOneOutResult with exact deleted-model fits, a model-level table, and a long-form coefficient table. See sensitivity analysis for failure and minimum-study rules.

influence() returns a MetaRegressionInfluenceResult with externally standardized deleted residuals, Cook's distances, DFBETAS, explicit screening thresholds, and the same exact deletion fits. It does not mutate or filter the original result.

collinearity() returns a MetaRegressionCollinearityResult with metafor-compatible VIF/GVIF and weighted, column-scaled condition diagnostics. It inspects the fitted design without changing the coefficients, terms, or included studies.

contrast(...) returns a MetaRegressionContrastResult with individual and joint inference for explicitly supplied linear hypotheses. It uses the fitted coefficient covariance and inference method without refitting the model.

summary(), method_details(), report(), provenance, warnings, and defensive copy semantics follow the same audit principles as MetaAnalysisResult.

Diagnostic and sensitivity results¶

`MetaRegressionContrastResult`¶

Contains original, a LinearContrastTestResult in joint_test, pvalue_adjustment="none", warnings, and defensive table and contrast_matrix DataFrames. len(result) is the number of contrast rows; summary() and to_dataframe() return the individual table.

contrast_matrix has one named row per contrast and one column per fitted term, including the intercept when present. The inference table columns are:

contrast, estimate, rhs, estimate_minus_rhs, standard_error, statistic,
statistic_name, distribution, df, pvalue, ci_low, ci_high,
confidence_level, pvalue_adjustment

The confidence interval is for the estimated linear combination C beta; the test statistic is for C beta - rhs. Normal inference produces z statistics and a joint chi-squared test. Both Hartung-Knapp choices produce t statistics with k-p degrees of freedom and a joint F test.

LinearContrastTestResult records contrasts, statistic, statistic_name, distribution, df_num, optional df_denom, and pvalue, with a detached to_dict() view. Multi-row matrices must have full row rank. Individual p-values are unadjusted; the result warns rather than silently selecting a multiplicity procedure.

`MetaRegressionCollinearityResult`¶

Contains original, raw_condition_number, weighted_scaled_condition_number, condition_index_reference, variance_proportion_reference, warnings, and four defensive DataFrames.

term_vif has one row per encoded non-intercept term:

term, moderator, vif, sif

moderator_gvif groups the terms belonging to each original moderator:

moderator, kind, terms, term_count, gvif, gsif

condition_indices contains:

dimension, singular_value, eigenvalue, condition_index,
high_condition_index, high_variance_term_count, concerning

variance_proportions is a long-form table with:

dimension, condition_index, term, moderator, variance_proportion,
high_variance_proportion

concerning_dimensions filters the condition table to dimensions with a condition index above 30 and variance proportions above 0.5 for at least two terms. These are fixed heuristic references, not hypothesis tests or automatic variable-selection rules. VIF/GVIF has no automatic cutoff.

`MetaRegressionInfluenceResult`¶

Contains original, the underlying leave_one_out workflow, its omission-aligned results, workflow warnings, and defensive table, dfbetas, failed, and flagged DataFrames. The scalar studentized_residual_reference, cook_distance_threshold, and dfbetas_threshold attributes expose the applied screening references.

The case-level table columns are:

omitted_row_id, omitted_study, refit_success, error_type, error_message,
deleted_residual, deleted_residual_se, externally_standardized_residual,
studentized_residual_reference, potential_outlier, cook_distance,
cook_distance_threshold, cook_distance_flag, max_abs_dfbetas,
dfbetas_threshold, dfbetas_flag, potentially_influential, flagged,
leverage, normalized_precision_weight

The long-form DFBETAS table repeats omission identifiers, success state, term, and moderator, followed by:

dfbeta, standard_error_reference, dfbetas, threshold, exceeds_threshold

dfbeta is the full-model coefficient minus the deleted-model coefficient. Failed refits retain rows with unavailable numeric diagnostics. Screening flags are heuristic review aids and never remove studies.

`MetaRegressionLeaveOneOutResult`¶

Contains original, an omission-aligned results tuple, workflow warnings, and defensive table, coefficients, and failed DataFrames. A None result and refit_success=False retain a deletion whose reduced design could not be estimated.

The model table columns are:

omitted_row_id, omitted_study, refit_success, error_type, error_message,
k, tau2, residual_q, residual_q_df, residual_q_pvalue, residual_i2,
residual_h2, global_statistic, global_statistic_name, global_df_num,
global_df_denom, global_pvalue, condition_number, refit_warnings

The long-form coefficient table repeats omission identifiers and success state for each original term, followed by:

term, moderator, estimate, estimate_change, standard_error, statistic,
statistic_name, df, pvalue, ci_low, ci_high

`LeaveOneOutResult`¶

Contains:

original, the fitted source result;
results, one omission-aligned refit or None per included study;
warnings, workflow-level notes;
table, summary(), and to_dataframe() defensive tabular views;
failed, the attempted refits that could not be estimated.

The table columns are:

omitted_row_id, omitted_study, refit_success, error_type, error_message,
k, estimate, standard_error, ci_low, ci_high, display_estimate,
display_ci_low, display_ci_high, tau2, q, q_df, q_pvalue, i2, h2,
i2_method

Failed reduced models retain their omission row with unavailable numeric statistics and None in the corresponding results position.

`CumulativeMetaAnalysisResult`¶

Contains original, ordered results, warnings, the defensive table views, and final, the final all-included-studies fit.

The table columns are:

step, added_row_ids, added_studies, order_value, k, estimate,
standard_error, ci_low, ci_high, display_estimate, display_ci_low,
display_ci_high, tau2, q, q_df, q_pvalue, i2, h2, i2_method

Only estimable prefixes produce rows. An unestimable prefix is recorded in warnings, and its pending studies are carried into the next estimable step.

See sensitivity analysis for count and ordering rules.

Subgroup results¶

Supplying subgroup= returns a SubgroupMetaAnalysisResult.

Attribute	Meaning
`groups`	Read-only ordered mapping from label to group result
`overall`	Analysis of all eligible studies
`q_between`, `q_between_df`, `q_between_pvalue`	Formal subgroup-difference test
`i2_between`	Inconsistency statistic for subgroup differences
`method`	`SubgroupMethodConfig`
`warnings`	Subgroup-workflow notes
`study_results`	Combined study table with a `subgroup` column

SubgroupMethodConfig records model, tau2_strategy, test_method, and subgroup_missing. Random-effects subgroup fits currently use an independent tau-squared estimate within each estimable group and another for the overall result. A group with one included study is a MetaAnalysisResult with model="common", tau2=0, a normal interval, and an explicit fallback warning; this preserves the requested random-effects overall analysis without claiming that within-group heterogeneity was estimable.

summary().to_dict() returns nested group and overall summaries. method_details() and report() include subgroup assumptions and the formal test. forest() draws studies, subgroup subtotals, the overall result, prediction intervals when available, and the test for subgroup differences.

Subgroup sensitivity composites¶

SubgroupLeaveOneOutResult and SubgroupCumulativeMetaAnalysisResult expose read-only .groups mappings plus .overall. Their to_dataframe() and summary() methods combine group and overall paths with scope and subgroup columns.

These paths do not calculate a new subgroup-differences test at every repeated fit.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search