QuantileMix

Quantile g-computation transforms exposures into ordinal quantile scores and estimates the joint effect of increasing all exposures simultaneously by one quantile. The package supports selected models for continuous, binary, count, and survival outcomes, with more limited support for censored, multicategory, and zero-inflated outcomes. Each API entry documents the effect scale, required inputs, and methodological limitations.

Quantile cutpoints estimated during model fitting are reused for prediction. Sign-specific weights summarize fitted exposure coefficients rather than causal importance. Successful model fitting does not establish the validity of model assumptions or identify a causal effect without additional causal identification assumptions.

The method follows Keil et al. (2020). Selected calculations were checked against Alexander Keil's R qgcomp. This is an unofficial Python package; the original authors have not endorsed it.

Documentation · API

Install

Install from PyPI:

pip install quantilemix

Or install the latest source from GitHub with Git installed:

python -m pip install "git+https://github.com/nilson01/quantilemix.git@main"

Or run this in a local checkout containing pyproject.toml:

python -m pip install .

Use quantilemix for installation and imports. NumPy and SciPy install as dependencies. For an isolated Python environment, see the Python Packaging User Guide.

First example

These two exposures already have scores 0–3. q=None tells fit to use those scores directly. Omit it when the columns contain raw measurements; the default groups each exposure into four quantiles.

import numpy as np
from quantilemix import fit

x1, x2 = np.meshgrid(np.arange(4), np.arange(4))
X = np.column_stack([x1.ravel(), x2.ravel()])
y = 1 + 2*X[:, 0] - 0.5*X[:, 1] + 0.2*(X[:, 0] - 1.5)*(X[:, 1] - 1.5)

result = fit(y, X, q=None)
print(result.summary())
print(result.psi, result.se, result.ci)
predicted_means = result.predict(X)

Joint-effect row from result.summary() (excerpt):

Term  Estimate  SE         CI lower  CI upper  t        p-value
psi   1.5       0.0877058  1.3281    1.6719    17.1026  2.70924e-10

The plot shows a * result.psi against the common exposure score a, relative to all scores set to zero. Shading is a pointwise 95% normal confidence interval for the mean contrast, not an individual prediction interval. Plot code.

Here psi is the fitted change in the mean outcome when both exposure scores rise by one category. The two exposure coefficients are 2 and −0.5, so their sum is 1.5. se is its standard error, and ci contains the confidence limits. These are changes in scores, not in the original measurement units. A causal interpretation needs assumptions about the study that the package cannot check.

Choose a method

The reference manual gives signatures, examples and limits for every supported function. The coverage map distinguishes implemented methods from open features.

For named data, fit_formula accepts additive terms such as y ~ x1 + x2 + C(group). C(group) encodes a text adjustment category. Use missing="drop" only when you want incomplete training rows removed; the default rejects them. Array inputs require complete numeric values. Fitted exposure boundaries and category levels are reused for prediction.

Case weights give training rows different influence in supported fits. They are different from the positive and negative sign weights in a result: sign weights describe fitted exposure coefficients, not causal importance. Neither kind of weight automatically accounts for a complex survey design.

Evidence and limits

The validation record links fixed comparisons and repeated-dataset studies. The checks apply to their stated inputs and models:

The confidence intervals describe uncertainty under each fitted model and study design. Software agreement with R does not establish general interval coverage or a causal effect.

Further information

• Short tutorials and common questions
• Markdown manual and reference PDF
• Method and numerical conventions
• Contributing and development checks
• Attribution and GPL-2.0-or-later license

Citation

Chapagain, N. QuantileMix: quantile g-computation in Python [Computer software]. https://github.com/nilson01/quantilemix

@software{chapagain_quantilemix,
  author = {Chapagain, Nilson},
  title = {QuantileMix: quantile g-computation in Python},
  url = {https://github.com/nilson01/quantilemix}
}

Record the version or commit used and cite the statistical method used in the analysis. Machine-readable metadata is in CITATION.cff.