Registry / data / formulaic-contrasts

formulaic-contrasts

library1.0.0pypypi✓ verified 29d ago

Formulaic Contrasts (version 1.0.0) is a Python library designed to build contrast vectors for statistical models defined using the `formulaic` library. It provides tools for conveniently constructing design matrices and specifying comparisons between categorical levels. The library released its 1.0.0 version, declaring the API as stable, and is part of the scverse project. Its release cadence is irregular but indicates movement towards stability.

data

pip install formulaic-contrasts

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · FORMULAIC-CONTRAST

formulaic-contrasts

datapythonv1.0.0

Install

12.3s avg

Import

2238ms

Disk

314MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 12.3s

py 3.11

✓ —

✓ 11.8s

py 3.12

✓ —

✓ 12.7s

py 3.13

✓ —

✓ 12.5s

py 3.9

✕ build_error

314MB installed

● package 314MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FormulaicContrasts

✓ from formulaic_contrasts import FormulaicContrasts

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)

Debug

Known issues

breakingWhen 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.

affects: <1.0.0

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.

affects: All

gotchaThe 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.

affects: All

breakingAs `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.

affects: Users upgrading `formulaic` to `1.0.0` or later (while using `formulaic-contrasts`)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'formulaic_contrasts'

The 'formulaic-contrasts' package is not installed in the current Python environment, or there is a typo in the import statement.

fix

Ensure the library is correctly installed using pip: `pip install formulaic-contrasts` or, if part of a larger scverse installation, via conda: `conda install -c conda-forge formulaic-contrasts`.

ValueError: Retrieving variables is only supported for design matrices that have a single column per factor level or are in simple sparse form.

This error occurs when attempting to retrieve variables from a design matrix generated with `formulaic-contrasts` if the underlying `formulaic` design specification results in complex, multi-column representations for factor levels that the contrast utility cannot unambiguously interpret.

fix

Simplify the formulaic design specification, particularly for categorical variables, to ensure that each factor level corresponds to a single, identifiable column in the design matrix, or adjust the approach to retrieving variables if complex designs are necessary.

TypeError: 'numpy.ndarray' object cannot be interpreted as an integer

This generic TypeError might arise if an array-like object is passed where an integer (e.g., for indexing or shape specification) is expected, possibly when constructing or applying contrasts to data not in the expected format (e.g., pandas DataFrame columns with mixed types or unexpected shapes).

fix

Ensure all input data to `formulaic-contrasts` functions, especially those defining categorical levels or numerical values, are of the correct and consistent data types (e.g., pandas Series for factors, numerical arrays for continuous variables) and shapes.

KeyError: 'level_name'

This error can occur if a specified factor level name (e.g., when defining a contrast or accessing metadata) does not exist in the actual categorical data used to build the design matrix. This often happens due to typos or inconsistencies between the specified contrasts and the actual data levels.

fix

Verify that all factor level names used in the contrast specification exactly match the levels present in the categorical data used to create the design matrix. Inspect the unique values of your categorical columns.

Upgrade

Version history

1.0.0latest on PyPI · released Dec 15, 2024

Audit

Dependencies

formulaicrequiredCore dependency for defining models and generating design matrices.

pandasoptionalCommonly used for data handling in examples and internal operations.

Agent activity

7 hits · last 30 days

node

Resources

githubhttps://github.com/scverse/formulaic-contrasts ↗

packagehttps://pypi.org/project/formulaic-contrasts/ ↗

docshttps://formulaic-contrasts.readthedocs.io/ ↗