Input data and row decisions¶

Every analysis entry point accepts either DataFrame column names or one-dimensional array-like values. This page describes rules shared by the generic, binary, continuous, and correlation APIs.

DataFrame columns¶

When data= is a pandas DataFrame, a string-valued input selects a column:

import pandas as pd
import meta_analyze as ma

studies = pd.DataFrame(
    {
        "log_effect": [0.12, 0.35, -0.08, 0.21],
        "sampling_variance": [0.04, 0.06, 0.03, 0.05],
        "citation": ["A", "B", "C", "D"],
    }
)
result = ma.meta_analysis(
    data=studies,
    effect="log_effect",
    variance="sampling_variance",
)

If study= is omitted, the DataFrame index supplies study labels. To use a column instead:

result = ma.meta_analysis(
    studies,
    effect="log_effect",
    variance="sampling_variance",
    study="citation",
)

Column names must exist. Array-like inputs may be mixed with DataFrame columns, but every array must contain exactly one value for every DataFrame row. Generic analyses require exactly one uncertainty input: variance= or standard_error=.

Array-like inputs¶

Lists, tuples, pandas Series, and one-dimensional NumPy arrays are accepted:

result = ma.meta_analysis(
    effect=[0.1, 0.3, -0.2],
    standard_error=[0.14, 0.20, 0.17],
    study=["A", "B", "C"],
)

All outcome inputs must be one-dimensional and have equal lengths. Without data= or study=, labels are generated as integer row numbers beginning at zero.

Stable row identity¶

row_id is the zero-based input position. It is independent of the study label and remains stable through exclusion, subgroup, leave-one-out, and cumulative workflows. Use it when study labels are duplicated or not suitable as identifiers. Duplicate labels are accepted because several rows can legitimately originate from the same publication, but the result records the affected row positions in warnings so accidental duplication remains auditable.

The complete row table is available from:

result.study_results
result.to_dataframe()
result.excluded_studies

These properties return defensive copies. Editing a returned DataFrame does not mutate the fitted result.

Missing values¶

The default missing="raise" stops when a required outcome value is missing. missing="drop" retains the row in the result but excludes it from all model calculations:

incomplete = studies.rename(
    columns={"log_effect": "effect", "sampling_variance": "variance"}
)
incomplete.loc[1, "effect"] = float("nan")
result = ma.meta_analysis(
    incomplete,
    effect="effect",
    variance="variance",
    missing="drop",
)

result.excluded_studies[["row_id", "study", "exclusion_reason"]]

For Meta-regression, missingness is resolved across the outcome, uncertainty, study label, and every moderator before moderator values are validated. Consequently, a moderator value in an already excluded row is retained for audit but cannot abort or influence the fitted design matrix. Moderator values in included rows must still satisfy the declared numeric or categorical contract.

Dropped rows do not contribute to pooled estimates, Q, tau-squared, prediction intervals, or weights. Missing subgroup labels are always rejected because silently assigning or dropping them would change the subgroup definition.

Outcome validation¶

Input family	Required validation
Generic	finite effect; finite, strictly positive sampling variance large enough for a finite float64 inverse weight
Binary	integer event counts and totals; positive totals; 0 <= events <= total
Continuous	finite means/SDs; non-negative SDs; integer group sizes of at least 2
Correlation	finite -1 < correlation < 1; integer sample size n >= 4

Binary, continuous, and correlation APIs preserve their raw input columns in study_results. Derived effects, variances, correction indicators, and weights appear alongside them.

All numerical calculations use float64. Internally derived effects and variances must remain finite, and every included sampling variance must be large enough to produce a finite inverse-variance weight. Values outside that representable range raise InvalidStudyDataError instead of returning non-finite fitted results.

Exclusion is visible¶

Rows excluded by a configured rule remain present with:

• included=False;
• a human-readable exclusion_reason;
• NaN fitted weights;
• their original row_id and study label.

Relative-effect double-zero/double-all exclusions and the RD rd_zero_variance="exclude" policy follow this rule. See zero-event studies for the binary-specific behavior.

Provenance boundary¶

result.provenance records where each public input came from, which row IDs were included or excluded, and which configured transformations affected each row. It does not capture upstream data cleaning. Version the source data and preprocessing code separately.