{"id":4017,"library":"formulaic-contrasts","title":"Formulaic Contrasts","description":"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.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/scverse/formulaic-contrasts","tags":["data analysis","statistics","model building","contrasts","formulaic","scverse"],"install":[{"cmd":"pip install formulaic-contrasts","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for defining models and generating design matrices.","package":"formulaic"},{"reason":"Commonly used for data handling in examples and internal operations.","package":"pandas","optional":true}],"imports":[{"symbol":"FormulaicContrasts","correct":"from formulaic_contrasts import FormulaicContrasts"}],"quickstart":{"code":"import pandas as pd\nfrom formulaic_contrasts import FormulaicContrasts\nfrom formulaic_contrasts.datasets import treatment_response\n\n# Load example data\ndf = treatment_response()\n\n# Initialize FormulaicContrasts with data and a formulaic design string\nmodel = FormulaicContrasts(df, '~ response + treatment')\n\n# Build a contrast for 'responder' vs 'non_responder'\n# using the more general .cond() method\ncontrast_vector = model.cond(response='responder') - model.cond(response='non_responder')\n\nprint(\"Contrast Vector (responder vs non_responder):\")\nprint(contrast_vector)\n\n# Build a simple pairwise contrast using .contrast()\nsimple_contrast = model.contrast(\n    column='treatment',\n    baseline='drugA',\n    group_to_compare='drugB'\n)\n\nprint(\"\\nSimple Contrast Vector (drugB vs drugA):\")\nprint(simple_contrast)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":"Users upgrading `formulaic` to `1.0.0` or later (while using `formulaic-contrasts`)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}