# Formula


A parsed model formula: the structured representation of a [GAM](GAM.md#whittaker.GAM)'s right-hand side.


Usage

``` python
Formula(
    response,
    terms,
    intercept=True,
)
```


A [Formula](Formula.md#whittaker.Formula) is what [whittaker.formula.parser.parse](parse_formula.md#whittaker.parse_formula) produces from a formula string such as `"y ~ s(x1) + s(x2, bs='cr', k=15) + te(x3, x4) + group"`, and is what `GAM.__init__` accepts either as that raw string or as an already-parsed [Formula](Formula.md#whittaker.Formula) object. It separates the response column name from an ordered list of `Term` objects ([LinearTerm](LinearTerm.md#whittaker.LinearTerm), [SmoothTerm](SmoothTerm.md#whittaker.SmoothTerm), [InteractionTerm](InteractionTerm.md#whittaker.InteractionTerm), [OffsetTerm](OffsetTerm.md#whittaker.OffsetTerm)) describing the right-hand side, plus whether an intercept is included. Downstream code ([whittaker.model_matrix.build_model_matrix](build_model_matrix.md#whittaker.build_model_matrix)) consumes a [Formula](Formula.md#whittaker.Formula) to construct the actual numeric design matrix and penalty structure used for fitting.


## Parameters


`response: str`  
Name of the response variable (the left-hand side, before `~`).

`terms: list[Term]`  
Ordered list of model terms (the right-hand side, after `~`), where `Term` is a union of [LinearTerm](LinearTerm.md#whittaker.LinearTerm), [SmoothTerm](SmoothTerm.md#whittaker.SmoothTerm), [InteractionTerm](InteractionTerm.md#whittaker.InteractionTerm), and [OffsetTerm](OffsetTerm.md#whittaker.OffsetTerm).

`intercept: bool = ``True`  
Whether the model includes an intercept column. `True` by default; suppress it by including `0 +` or `- 1` on the right-hand side of the formula string (e.g. `"y ~ 0 + s(x)"`).


## Methods

| Name | Description |
|----|----|
| [required_columns()](#required_columns) | Return every data column name referenced by the formula, in first-seen order. |

------------------------------------------------------------------------


### required_columns()


Return every data column name referenced by the formula, in first-seen order.


Usage

``` python
required_columns()
```


Walks the response name and every term, collecting the response, each `LinearTerm.variable`, each [SmoothTerm](SmoothTerm.md#whittaker.SmoothTerm)'s `variables` (and its `by` column, if any), and both sides of each [InteractionTerm](InteractionTerm.md#whittaker.InteractionTerm). [OffsetTerm](OffsetTerm.md#whittaker.OffsetTerm) is skipped because its `expression` may be an arbitrary expression string rather than a bare column name. Names are deduplicated while preserving the order in which they were first encountered.


#### Returns


`list of str`  
Column names that must be present in a data dictionary passed to `~whittaker.model_matrix.build_model_matrix`.