Continuous outcomes

Gaussian mean differences and method-specific uncertainty.

fit(y, exposures, covariates=None, *, q=4, breaks=None, alpha=0.05, weights=None)

Estimate a joint exposure effect for a continuous outcome.

Fits additive Gaussian regression: exposure-score effects enter a linear model and are added together. An intercept is always included.

Parameters:
  • y ((array - like, shape(n))) –

    Outcome values for n observations. Values must be real, finite and complete, with one value per row of exposures.

  • exposures ((array - like, shape(n, d) or (n,))) –

    The d exposure columns whose coefficients form the joint effect. A vector represents one exposure. Grouping follows quantize.

  • covariates ((array - like, shape(n, c) or (n,)), default: None ) –

    Numeric adjustment variables, with c columns. Their coefficients are fitted but not included in the joint effect. Encode categorical variables before fitting. Do not supply another intercept column.

  • q (int or None, default: 4 ) –

    Number of quantile groups. Use None for already grouped integer scores. See quantize for input limits and tie handling.

  • breaks (array-like or sequence of array-like, default: None ) –

    Complete category boundaries per exposure. Takes priority over q.

  • alpha (float, default: 0.05 ) –

    Significance level strictly between zero and one. Confidence limits have nominal coverage 1 - alpha; 0.05 requests a 95% interval.

  • weights ((array - like, shape(n)), default: None ) –

    Positive finite case weights for the Gaussian regression. One weight is required per training row. Exposure quantiles remain unweighted. These are not the descriptive sign weights in the result.
Returns:
  • QGCompResult –

    Fitted coefficients and covariance, the joint estimate psi, its standard error and confidence limits, sign summaries, residuals and diagnostics. Coefficients are ordered as intercept, exposures, then covariates. Result arrays and mappings are read-only. predict returns fitted mean outcomes using the saved exposure boundaries.
Raises:
  • ValueError –

    If inputs are invalid, model columns are linearly dependent, there are too few observations for residual variance, or finite coefficient, covariance and joint-effect estimates cannot be calculated.
Warns:
  • QGCompWarning –

    If coefficients are sensitive to small numerical changes, or variation is too small for inference. At numerical-zero variation, the standard error is zero and the interval is a single point; the test statistic and p-value are NaN (undefined), with inference_degenerate set in diagnostics. These undefined values are intentional, not test evidence.
Notes

The joint estimate is the sum of exposure-score coefficients. Its variance includes covariance between those coefficients. Model-based uncertainty assumes independent observations and constant conditional residual variance. A causal interpretation needs further study assumptions.

Confidence limits use normal critical values, as in R qgcomp 2.19.6. The reference p-value uses a Student t distribution with n - 1 - d degrees of freedom; residual variance instead uses n - 1 - d - c. The interval and test therefore need not agree exactly at a significance threshold.

Rows and variables are not silently removed. Nonlinear terms, interactions, other outcome families, clustered observations, penalization and bootstrap inference are not supported by this interface. Case weights use the R reference's model-based Gaussian covariance. They do not provide complex-survey or cluster-robust inference. Zero weights and missing rows are not supported.

fit_formula(formula, data, exposures, *, q=4, breaks=None, alpha=0.05, weights=None, missing='raise')

Fit the additive Gaussian model from named columns.

Supports only an intercept and additive main effects. Use simple names for the outcome and exposures, and C(name) for a categorical adjustment term. Categories use sorted observed text levels; the first is the reference. The same levels are retained for :meth:QGCompResult.predict_data. missing='raise' requires complete inputs. missing='drop' removes rows with missing model values or weights. Automatic cutpoints use all observed exposure values before row removal, as in R qgcomp 2.19.6. Interactions and transformations are not supported.

fit_bootstrap(y, exposures, covariates=None, *, q=4, breaks=None, alpha=0.05, B=200, seed=None, weights=None)

Estimate a Gaussian joint mean contrast with fixed-cut row bootstrap.

Exposure cutpoints are computed once on all training rows, then held fixed. Each of B replicates samples n independent rows with replacement. Positive case weights stay attached to their rows in each replicate. They also weight the covariate distribution used for intervention means. This is not complex-survey or cluster bootstrap inference. The local NumPy generator leaves global random state unchanged. A failed replicate raises an error with its one-based position; no draw is replaced.

fit_bootstrap_formula(formula, data, exposures, *, q=4, breaks=None, alpha=0.05, B=200, seed=None, missing='raise', weights=None)

Fit the additive Gaussian fixed-cut row bootstrap from named columns.

The formula allows additive main effects and C(name) text adjustment. missing='drop' removes incomplete model rows before resampling, while automatic exposure cutpoints use observed exposure values before removal. The retained row positions and formula are available on point_fit. Rows must be independent. Positive case weights remain with sampled rows.

fit_gaussian_ee(y, exposures, cluster_ids, covariates=None, *, q=4, breaks=None, alpha=0.05, weights=None)

Fit an additive Gaussian joint response with a cluster sandwich.

Use complete numeric rows and integer cluster IDs. Exposure cuts are estimated once; no nonlinear terms or time structure are inferred. Positive weights affect both estimating equations and cluster scores, but not exposure cuts. At least two clusters and two joint levels are required.

fit_quadratic_bootstrap(y, exposures, covariates=None, *, q=4, breaks=None, alpha=0.05, B=200, seed=None, pairwise_interactions=False, covariate_interactions=False)

Fit all exposure squares and a degree-two marginal joint response.

Complete numeric rows only. Cutpoints are fixed before independent-row bootstrap resampling. Set pairwise_interactions=True to include every distinct exposure-score product. Set covariate_interactions=True to include every exposure score by numeric covariate product. Marginalization then averages over the observed covariates in each original or resampled dataset. Clusters and weights remain unsupported.

fit_quadratic_gaussian_ee(y, exposures, cluster_ids, covariates=None, *, q=4, breaks=None, alpha=0.05, weights=None, pairwise_interactions=False, covariate_interactions=False)

Fit a degree-two Gaussian joint-response curve with clustered uncertainty.

Rows must be complete and numeric. Each exposure has a linear and squared score term. Optional products add every exposure pair or every exposure by numeric covariate. cluster_ids must contain exact integer IDs, with at least two clusters. Positive case weights enter both estimating equations and the cluster sandwich, but exposure cutpoints stay unweighted.

The two entries of psi multiply the joint score and its square. Thus effect_at(0) gives the change from joint level zero to one; the change varies by starting level when the quadratic coefficient is nonzero.

Parameters:
  • y ((array - like, shape(n_rows))) –

    Continuous outcome.

  • exposures ((array - like, shape(n_rows, n_exposures))) –

    Exposure measurements or, with q=None, integer scores.

  • cluster_ids ((array - like, shape(n_rows))) –

    Exact integer cluster IDs. At least two clusters are required.

  • covariates (array - like, default: None ) –

    Numeric adjustment columns with one row per outcome.

  • q (optional, default: 4 ) –

    Quantile count or explicit category boundaries. q=None accepts already scored exposures. At least three joint levels are required.

  • breaks (optional, default: 4 ) –

    Quantile count or explicit category boundaries. q=None accepts already scored exposures. At least three joint levels are required.

  • alpha (float, default: 0.05 ) –

    Error probability for two-sided confidence intervals.

  • weights (array - like, default: None ) –

    Positive case weights. Exposure cutpoints remain unweighted.

  • pairwise_interactions (bool, default: False ) –

    Add every exposure-pair or exposure-by-covariate product, respectively.

  • covariate_interactions (bool, default: False ) –

    Add every exposure-pair or exposure-by-covariate product, respectively.
Returns:
Raises:
  • ValueError –

    If input shapes, scores, cluster IDs, weights or design rank are invalid.
Notes

R qgcomp 2.19.6 agrees on the fixed point fits but may report a different nonlinear cluster covariance because its cluster-meat calculation reuses precomputed formula columns after changing exposure scores. This function rebuilds every derived column under each intervention. See the nonlinear estimating-equation validation report for the fixed comparison.