{"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":"python","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,"search_vec":"'1.0.0':6,42 'analysi':67 'api':46 'build':13,70 'cadenc':58 'categor':36 'comparison':34 'construct':29 'contrast':2,4,14,71 'conveni':28 'data':66 'declar':44 'defin':19 'design':11,30 'formula':1,3,22,72 'indic':62 'irregular':60 'level':37 'librari':10,23,39 'matric':31 'model':18,69 'movement':63 'part':51 'project':55 'provid':25 'python':9 'releas':40,57 'scvers':54,73 'specifi':33 'stabil':65 'stabl':48 'statist':17,68 'tool':26 'toward':64 'use':20 'vector':15 'version':5,43","created_at":"2026-04-12T03:37:27.065686+00:00","updated_at":"2026-04-16T15:10:47.999197+00:00","problems":[{"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`.","cause":"The 'formulaic-contrasts' package is not installed in the current Python environment, or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'formulaic_contrasts'"},{"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.","cause":"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.","error":"ValueError: Retrieving variables is only supported for design matrices that have a single column per factor level or are in simple sparse form."},{"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.","cause":"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).","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as an integer"},{"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.","cause":"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.","error":"KeyError: 'level_name'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/scverse/formulaic-contrasts","docs":"https://formulaic-contrasts.readthedocs.io/","changelog":null,"pypi":"https://pypi.org/project/formulaic-contrasts/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}