Formulaic Contrasts

Warnings

• breaking When upgrading from `formulaic-contrasts` versions `v0.x.x` to `v1.0.0`, be aware that the API is now considered stable. While explicit breaking changes from previous versions were not extensively documented for `formulaic-contrasts` itself, it's prudent to review your code for compatibility with the stabilized API.
  Fix: Consult the official documentation for `formulaic-contrasts` to ensure compatibility with the `v1.0.0` stable API. Update your usage patterns for `FormulaicContrasts`, `cond()`, and `contrast()` methods if necessary.
• gotcha `formulaic-contrasts` is solely a tool for constructing contrast vectors for models defined with `formulaic`. It does not implement any statistical tests or perform model fitting itself. Users must integrate the generated contrast vectors with a separate statistical modeling library to perform analysis.
  Fix: Understand that the output of `formulaic-contrasts` (contrast vectors) needs to be passed to a statistical package (e.g., `statsmodels`, `scanpy`'s `lm.ols`) that can interpret these vectors in the context of a fitted model to perform hypothesis testing or derive interpretations.
• gotcha The behavior of `FormulaicContrasts.cond()` and `FormulaicContrasts.contrast()` differs. `cond()` is a general method for defining specific conditions which can then be combined arithmetically to form complex contrasts. `contrast()` is a convenience method for simple pairwise comparisons between two levels of a single categorical variable. For more complex comparisons, `cond()` should be preferred.
  Fix: Use `model.cond(variable='level') - model.cond(variable='baseline_level')` for arbitrary or complex contrasts, and reserve `model.contrast(column='variable', baseline='baseline_level', group_to_compare='level')` for straightforward pairwise comparisons.
• breaking As `formulaic-contrasts` depends on `formulaic`, be aware of breaking changes introduced in `formulaic`'s `v1.0.x` series. These include changes to canonical formatting of Python tokens, removal of previously deprecated methods, and potential alterations to column names associated with categorical factors in the generated design matrix. Such changes in the underlying `formulaic` library can indirectly affect how contrast vectors are interpreted or how `formulaic-contrasts` interacts with the design matrix.
  Fix: When upgrading `formulaic`, consult its changelog. Specifically, be cautious about how categorical factor column names might have changed, as this could impact the interpretation of `formulaic-contrasts` output. For example, `feature[T.A]` naming might have been modified.

Install

• pip install formulaic-contrasts Install latest version

Imports

• FormulaicContrasts

  from formulaic_contrasts import FormulaicContrasts

Quickstart

This quickstart demonstrates how to initialize `FormulaicContrasts` with a pandas DataFrame and a formulaic design string. It then shows two ways to build contrast vectors: using the flexible `cond()` method for arbitrary conditions and arithmetic combinations, and the `contrast()` method for simple pairwise comparisons between levels of a single variable.

import pandas as pd
from formulaic_contrasts import FormulaicContrasts
from formulaic_contrasts.datasets import treatment_response

# Load example data
df = treatment_response()

# Initialize FormulaicContrasts with data and a formulaic design string
model = FormulaicContrasts(df, '~ response + treatment')

# Build a contrast for 'responder' vs 'non_responder'
# using the more general .cond() method
contrast_vector = model.cond(response='responder') - model.cond(response='non_responder')

print("Contrast Vector (responder vs non_responder):")
print(contrast_vector)

# Build a simple pairwise contrast using .contrast()
simple_contrast = model.contrast(
    column='treatment',
    baseline='drugA',
    group_to_compare='drugB'
)

print("\nSimple Contrast Vector (drugB vs drugA):")
print(simple_contrast)