NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #1043 most downloaded on PyPI
An implementation of Wilkinson formulas.
Latest stable
1.2.2
Last release 5 months ago
02 Jun 2026
Ships fairly regularly
a new release about every 3 months
Nearly every release is documented
notes for 29 of 32 stable releases
Nothing withdrawn
no release was ever pulled
7 years old
32 releases · first in 2019
Drag across the ruler to compare, or tap a release to open it.
This is a minor release that fixes issues related to extracting required_variables from formulae. In particular, we now properly support `` escaped-na
This is a minor release that fixes issues related to extracting required_variables from formulae. In particular, we now properly support `escaped-names` and Q('quoted-names').
This is a minor release with only one change: fixing compatibility with the new string dtype in the upcoming release of Pandas 3.
This is a minor release with only one change: fixing compatibility with the new string dtype in the upcoming release of Pandas 3. (#261)
Formulaic now targets Python 3.9+ (dropping support for 3.7 and 3.8).
Breaking changes:
ModelSpec.required_variables (and all other .required_variables
implementations) now only include the root variable name (e.g. a.fillna ->
a), since this is expected to be used to validate that dataframes have the
expected columns. The full variable usage is still exposed via .variables
and related attributes. You can lookup the the root variable using the .root
property of each Variable instance. (#254)New features and enhancements:
narwhals for all non-pandas dataframe types supported by narwhals
(including polars dataframes and pyarrow tables). This should substantially
improve performance for these types since historically the relevant parts of
these dataframes were converted lazily to pandas objects. (#189)Bugfixes and cleanups:
Factor instances no longer include backticks around factors evaluated using
Python so that string representations can be interpreted correctly when
parsed anew. (#256)FactorValue types are now always unwrapped during categorical encoding due
to issues with wrapped numpy arrays.Special thanks to @MarcoGorelli for his help in implementing Narwhals support.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Formula.differentiate() is now considered stable, with ModelMatrix.differentiate() to follow in a future release.
New features and enhancements:
Formula.differentiate() is now considered stable, with
ModelMatrix.differentiate() to follow in a future release. (#236)Bugfixes and cleanups:
Many thanks to @bashtage for driving those invasive changes forward. There are some semantic breaking changes, but unless you are deep in the internal…
This is a major feature release that was motivated in many aspects by the migration of statstmodels from patsy to formulaic. Many thanks to @bashtage for driving those invasive changes forward. There are some semantic breaking changes, but unless you are deep in the internals of formulaic (which I do not believe to be the case for any external library) these are not expected to break common usage.
Breaking changes:
Formula is no longer always "structured" with special cases to handle the
case where it has no structure. Legacy shims have been added to support old
patterns, with DeprecationWarnings raised when they are used. It is not
expected to break anyone not explicitly checking whether the Formula.root is
a list instance (which formerly should have been simply assumed) [it is a now
SimpleFormula instance that acts like an ordered sequence of Term
instances].feature[T.A], whether nor not the encoding will result in that term acting
as a contrast. Now, in keeping with patsy, we only add the prefix if the
categorical factor is encoded with reduced rank. Otherwise, feature[A] will
be used instead.formulaic.parsers.types.structured has been promoted to
formulaic.utils.structured.New features and enhancements:
Formula now instantiates to SimpleFormula or StructuredFormula, the
latter being a tree-structure of SimpleFormula instances (as compared to
List[Term]) previously. This simplifies various internal logic and makes the
propagation of formula metadata more explicit. (#222)dict and recarray types are no associated with the pandas materializer
by default (rather than raising), simplifying some user workflows. (#225). operator (which is replaced with all variables not
used on the left-hand-side of formulae). (#216)[ ... ~ ... ].
This is useful for (e.g.) generating formulae for IV 2SLS. (#108)ModelSpec[s] based on an arbitrary
strictly reduced FormulaSpec. (#208)Formula.required_variables to more easily surface the expected data
requirements of the formula. (#205)cc) and natural (cr). See
formulaic.materializers.transforms.cubic_spline.cubic_spline for
more details.lag() transform.LinearConstraints can now be done from a list of strings (for
increased parity with patsy). (#201)T. when they actully
describe contrasts (i.e. when they are encoded with reduced rank). (#220)encode_categorical;
which is surfaced via ModelSpec.factor_contrasts. (#204)Operator instances now received context which is optionally specified by
the user during formula parsing, and updated by the parser. This is what makes
the . implementation possible. (#216)Structured, it has been promoted to
formulaic.utils. (#223)Bugfixes and cleanups:
Formula instance. (#200)Structured
instances. (#200)ModelMatrix and FactorValues instances (whenever wrapped
objects are picklable). (#209; thanks @bashtage)basis_spline: Fixed evaluation involving datasets with null values, and
disallow out-of-bounds knots. (#217; thanks @bashtage)ruff for linting, and updated mypy and pre-commit tooling.ruff are automatically applied when using
hatch run lint:format.Documentation:
Fix compatibility with pandas >=3.
Bugfixes and cleanups:
pandas >=3.mypy type inference in materializer subclasses.Documentation:
sklearn integration example.This is identical to v1.0.0, but with the package status marked to production/stable rather than beta [facepalm].
This is identical to v1.0.0, but with the package status marked to production/stable rather than beta [facepalm].
Methods deprecated during the 0.x series have been removed: Formula.terms, ModelSpec.feature_names, and ModelSpec.feature_indices.
This is the first officially stable release of formulaic, with a relatively small diff from the 0.6.x series.
Breaking changes:
Formula.terms,
ModelSpec.feature_names, and ModelSpec.feature_indices.New features and enhancements:
patsy.hashed transform for categorically encoding deterministically
hashed representations of a dataset. [Contributed by @rishi-kulkarni]Bugfixes and cleanups:
astor for Python 3.9 and newer.Documentation:
This is minor release with one important bugfix.
This is minor release with one important bugfix.
Bugfixes and cleanups:
This is a minor release with several important bugfixes.
This is a minor release with several important bugfixes.
Bugfixes and cleanups:
poly() transforms operating on datasets that include null values. #155hatch run tests.This is a minor release with several new features and cleanups.
This is a minor release with several new features and cleanups.
New features and enhancements:
ModelSpec documentation for more details.Bugfixes and cleanups:
OrderedDict usage, since Python guarantees the orderedness of
dictionaries in Python 3.7+.None.This is a minor release with a bugfix.
This is a minor release with a bugfix.
Bugfixes and cleanups:
This is a minor release with several bugfixes.
This is a minor release with several bugfixes.
Bugfixes and cleanups:
This is a minor release with one new feature.
This is a minor release with one new feature.
New features and enhancements:
Although there are some internal changes to API, as documented below, there are no breaking changes to user-facing APIs.
This is a major release with some important consistency and completeness improvements. It should be treated as almost being the first release candidate of 1.0.0, which will land after some small amount of further feature extensions and documentation improvements.
Breaking changes:
Although there are some internal changes to API, as documented below, there are no breaking changes to user-facing APIs.
New features and enhancements:
_ordering keyword to
the Formula constructor.standardize, Q and treatment contrasts shims.cluster_by='numerical_factors option to ModelSpec to enable
patsy style clustering of output columns by involved numerical factors.^ and %in%.Structured instances, and use this functionality during
AST evaluation where relevant.ModelSpec.term_indices is now a list rather than a tuple, to allow direct use when
indexing pandas and numpy model matrices.Bugfixes and cleanups:
Structured instances for non-sequential iterable values.poly unit tests.PandasMaterializer. #122 (thanks @effigies)Factor.EvalMethod.UNKNOWN was removed, defaulting instead to LOOKUP.sympy version constraint now that a bug has been fixed upstream.Documentation:
This is a minor patch releases that fixes one bug.
This is a minor patch releases that fixes one bug.
Bugfixes and cleanups:
Structured instance and iteration
over this instance (including Formula instances). Formerly the length would
only count the number of keys in its structure, rather than the number of
objects that would be yielded during iteration.This is a minor patch release that fixes two bugs.
This is a minor patch release that fixes two bugs.
Bugfixes and cleanups:
Formula objects.formulaic.__version__ during package build.This is a major new release with some minor API changes, some ergonomic improvements, and a few bug fixes.
This is a major new release with some minor API changes, some ergonomic improvements, and a few bug fixes.
Breaking changes:
Formula objects (e.g. formula.lhs) no
longer returns a list of terms; but rather a Formula object, so that the
helper methods can remain accessible. You can access the raw terms by
iterating over the formula (list(formula)) or looking up the root node
(formula.root).New features and improvements:
ModelSpec object is now the source of truth in all ModelMatrix
generations, and can be constructed directly from any supported specification
using ModelSpec.from_spec(...). Supported specifications include formula
strings, parsed formulae, model matrices and prior model specs..get_model_matrix() helper methods across Formula,
FormulaMaterializer, ModelSpec and model_matrix objects/helpers
functions are now consistent, and all use ModelSpec directly under the hood.Formula objects (e.g. formula.lhs), the
term lists will be wrapped as trivial Formula instances rather than returned
as raw lists (so that the helper methods like .get_model_matrix() can still
be used).FormulaSpec is now exported from the top-level module.Bugfixes and cleanups:
ModelSpec specifications being overriden by default arguments to
FormulaMaterializer.get_model_matrix.Structured._flatten() now correctly flattens unnamed substructures.…formulae, matrices and specs, and a few small breaking changes (most with backward compatibility shims). All users are encouraged to upgrade.
This is a major new release with some new features, greatly improved ergonomics for structured formulae, matrices and specs, and a few small breaking changes (most with backward compatibility shims). All users are encouraged to upgrade.
Breaking changes:
include_intercept is no longer an argument to FormulaParser.get_terms;
and is instead an argument of the DefaultFormulaParser constructor. If you
want to modify the include_intercept behaviour, please use:Formula("y ~ x", _parser=DefaultFormulaParser(include_intercept=False))
Formula.terms is deprecated since Formula became a
subclass of Structured[List[Terms]]. You can directly iterate over, and/or
access nested structure on the Formula instance itself. Formula.terms
has a deprecated property which will return a reference to itself in order to
support legacy use-cases. This will be removed in 1.0.0.ModelSpec.feature_names and ModelSpec.feature_columns are deprecated in
favour of ModelSpec.column_names and ModelSpec.column_indices. Deprecated
properties remain in-place to support legacy use-cases. These will be removed
in 1.0.0.New features and enhancements:
Formula has been refactored as a subclass of
Structured[List[Terms]], and can be incrementally built and modified. The
matrix and spec outputs now have explicit subclasses of Structured
(ModelMatrices and ModelSpecs respectively) to expose convenience methods
that allow these objects to be largely used interchangeably with their
singular counterparts.ModelMatrices and ModelSpecs arenow surfaced as top-level exports of the
formulaic module.Structured (and its subclasses) gained improved integration of nested tuple
structure, as well as support for flattened iteration, explicit mapping
output types, and lots of cleanups.ModelSpec was made into a dataclass, and gained several new
properties/methods to support better introspection and mutation of the model
spec.FormulaParser was renamed DefaultFormulaParser, and made a subclass of the
new formula parser interface FormulaParser. In this process
include_intercept was removed from the API, and made an instance attribute
of the default parser implementation.Bugfixes and cleanups:
ModelSpecs are provided by the user during
materialization, they are updated to reflect the output-type chosen by the
user, as well as whether to ensure full rank/etc.pylint was added to the CI testing.Documentation:
.materializer submodule, most code now has inline
documentation and annotations.This is a backward compatible major release that adds several new features.
This is a backward compatible major release that adds several new features.
New features and enhancements:
ModelMatrix
instances (see ModelMatrix.model_spec.get_linear_constraints).ModelMatrix, ModelSpec and other formula-like
objects to the model_matrix sugar method so that pre-processed formulae can
be used.0 with -1 to avoid substitutions in quoted contexts.Bugfixes and cleanups:
bs(`my|feature%is^cool`).C(x, {"a": [1,2,3]}).astor to >=0.8 to fix issues with ast-generation in
Python 3.8+ when numerical constants are present in the parsed python
expression (e.g. "bs(x, df=10)").This is a minor patch release that migrates the package tooling to poetry; solving a version inconsistency when packaging for conda.
This is a minor patch release that migrates the package tooling to poetry; solving a version inconsistency when packaging for conda.
This is a minor patch release that fixes an attempt to import numpy.typing when numpy is not version 1.20 or later. (thanks for noticing this and fixi
This is a minor patch release that fixes an attempt to import numpy.typing when numpy is not version 1.20 or later. (thanks for noticing this and fixing it @bashtage ).
This is a minor patch release that fixes the maintaining of output types, NA-handling, and assurance of full-rank for factors that evaluate to pre-enc
This is a minor patch release that fixes the maintaining of output types, NA-handling, and assurance of full-rank for factors that evaluate to pre-encoded columns when constructing a model matrix from a pre-defined ModelSpec. The benchmarks were also updated.
This is a relatively massive release bringing lots of new features and bugfixes. All users are encouraged to upgrade. The full changelog can be viewed
This is a relatively massive release bringing lots of new features and bugfixes. All users are encouraged to upgrade. The full changelog can be viewed in the documentation website. The highlights include:
Breaking changes:
formulaic.materializers.transforms to
the top-level formulaic.transforms module, and ported all existing
transforms to output FactorValues types rather than dictionaries.
FactorValues is an object proxy that allows output types like
pandas.DataFrames to be used as they normally would, with some additional
metadata for formulaic accessible via the __formulaic_metadata__
attribute. This makes non-formula direct usage of these transforms much more
pleasant.~ is no longer a generic formula separator, and can only be used once in a
formula. Please use the newly added | operator to separate a formula into
multiple parts.New features and enhancements:
~ operator to use
them. Structured formulas can have named substructures, for example: lhs
and rhs for the ~ operator. The representation of formulas has been
updated to show this structure.| operator which splits formulas into multiple parts).formulaic.model_matrix syntactic sugar function now accepts ModelSpec
and ModelMatrix instances as the "formula" spec, making generation of
matrices with the same form as previously generated matrices more
convenient.poly transform (compatible with R and patsy).numpy is now always available in formulas via np, allowing formulas like
np.sum(x). For convenience, log, log10, log2, exp, exp10 and
exp2 are now exposed as transforms independent of user context.formulaic.utils.context.capture_context().
This can be used by libraries that wrap Formulaic to capture the variables
and/or transforms available in a users' environment where appropriate.This is a minor release that fixes an issue whereby the ModelSpec instances attached to ModelMatrix objects would keep reference to the original data,
This is a minor release that fixes an issue whereby the ModelSpec instances attached to ModelMatrix objects would keep reference to the original data, greatly inflating the size of the ModelSpec. (Many thanks to @mmacpherson for reporting!)
This release is identical to v0.2.2, except that the source distribution now includes the docs, license, and tox configuration.
This release is identical to v0.2.2, except that the source distribution now includes the docs, license, and tox configuration.
This is a minor release with one bugfix.
This is a minor release with one bugfix.
This is a minor patch release that brings in some valuable improvements.
This is a minor patch release that brings in some valuable improvements.
DataFrame. (issue noted by @CamDavidsonPilon)This is major release that brings in a large number of improvements. The API is still not finalised (that will happen with the 1.0) release, and so be
This is major release that brings in a large number of improvements. The API is still not finalised (that will happen with the 1.0) release, and so be careful of API breakages brought in by subsequent major releases (e.g. v0.3.x). Many thanks to those who have contributed by testing or code submissions (including @bashtage, @griffiri, and @CamDavidsonPilon).
New Features and Improvements:
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.