modelmatrix 0.1.0__py3-none-any.whl

modelmatrix/model_spec.py

@@ -0,0 +1,1710 @@
+"""
+Model specification
+===================
+
+This module defines the basic object to represent regression
+formula: *ModelSpec*. 
+"""
+
+from collections import namedtuple
+from itertools import product
+from typing import NamedTuple, Any
+from copy import copy
+
+import numpy as np, pandas as pd
+import narwhals as nw
+from scipy import sparse as sp_sparse
+
+from sklearn.base import TransformerMixin, BaseEstimator, clone
+from sklearn.utils.validation import check_is_fitted
+from sklearn.preprocessing import (OneHotEncoder,
+                                   OrdinalEncoder,
+                                   StandardScaler)
+from sklearn.decomposition import PCA
+from sklearn.pipeline import make_pipeline, Pipeline
+from sklearn.exceptions import NotFittedError
+from joblib import hash as joblib_hash
+
+from .columns import (_get_column_info,
+                      Column,
+                      _categorical_from_df,
+                      _check_categories)
+
+from .transforms import (Poly,
+                         BSpline,
+                         NaturalSpline,
+                         Interaction)
+
+DOCACHE = False
+
+class Feature(NamedTuple):
+
+    """
+    An element in a model matrix that will build
+    columns from an array-like X.
+    """
+
+    variables: tuple
+    name: str
+    encoder: Any
+    use_transform: bool=True   # if False use the predict method
+    pure_columns: bool=False
+    override_encoder_colnames: bool=False
+    # how a helper such as ns() made this Feature: (helper, args, kwargs),
+    # so that it can be rebuilt with other parameters (ModelSpec.set_params)
+    spec: Any=None
+    
+
+#### contrast specific code
+
+def _as_series(X):
+    """
+    A single categorical feature as a `pd.Series`.
+    """
+    if isinstance(X, pd.DataFrame):
+        if X.shape[1] != 1:
+            raise ValueError(f'expecting a single column, got {X.shape[1]}')
+        X = X.iloc[:,0]
+    if not isinstance(X, pd.Series):
+        X = np.asarray(X)
+        if X.ndim > 2 or (X.ndim == 2 and X.shape[1] != 1):
+            raise ValueError(f'expecting a single column, got array of shape {X.shape}')
+        X = pd.Series(X.reshape(-1))
+    return X
+
+def _observed_levels(X):
+    """
+    Levels of `X` that are observed (missing values excluded),
+    in the order of `X.dtype.categories` for a categorical,
+    sorted otherwise.
+    """
+    observed = X.dropna().unique()
+    if isinstance(X.dtype, pd.CategoricalDtype):
+        observed = set(observed)
+        return [c for c in X.dtype.categories if c in observed]
+    return sorted(observed)
+
+def _level_codes(X, levels, during='transform'):
+    """
+    Position of each entry of `X` in `levels`, and a mask
+    of missing entries (whose codes are -1). Raises a `ValueError`
+    for entries that are neither missing nor in `levels`.
+    """
+    X = _as_series(X)
+    missing = np.asarray(X.isna())
+    codes = pd.Index(levels).get_indexer(np.asarray(X, dtype=object))
+    codes[missing] = -1
+    unknown = (codes < 0) & ~missing
+    if unknown.any():
+        raise ValueError('Found unknown categories {0} during {1}'.format(
+                         sorted(set(np.asarray(X)[unknown]), key=str), during))
+    return codes, missing
+
+class Contrast(TransformerMixin, BaseEstimator):
+
+    def __init__(self,
+                 method='drop',
+                 drop_level=None):
+        """
+        Contrast encoding for categorical variables.
+
+        Parameters
+        ----------
+        method : ['drop', 'sum', None, callable]
+            If 'drop', then a column of the one-hot
+            encoding will be dropped. If 'sum', then the sum of
+            coefficients is constrained to sum to 1.
+            If `None`, the full one-hot encoding is returned.
+            Finally, if callable, then it should take the number of
+            levels of the category as a single argument and return
+            an appropriate contrast of the full one-hot encoding.
+
+        drop_level : level identifier (optional)
+            If not None, this level of the category
+            will be dropped if `method` is 'drop' (or given
+            coefficient minus the sum of the others if 'sum').
+            Matched against the levels by value, then by `str`.
+
+        Levels are those observed when fit, in the order of
+        the categories for a categorical dtype and sorted
+        otherwise; unused categories are dropped. Missing
+        values give a row of `np.nan`, and a level not seen
+        when fit raises a `ValueError` on transform.
+
+        """
+
+        self.method = method
+        self.drop_level = drop_level
+        
+    def fit(self, X, y=None):
+
+        """
+        Construct contrast of categorical variable
+        for use in building a design matrix.
+
+        Parameters
+        ----------
+        X : array-like
+            X on which model matrix will be evaluated.
+            If a :py:class:`pd.DataFrame` or :py:class:`pd.Series`, variables that are of
+            categorical dtype will be treated as categorical.
+
+        Returns
+        -------
+        F : array-like
+            Columns of design matrix implied by the
+            categorical variable.
+
+        """
+
+        # validate before setting any fitted attribute, so a bad method
+        # does not leave a partially fitted encoder
+        if not (self.method in ['drop', 'sum', None] or callable(self.method)):
+            raise ValueError('method must be one of ["drop", "sum", None] or a callable ' +
+                             'that returns a contrast matrix given the number' +
+                             ' of levels')
+
+        levels = _observed_levels(_as_series(X))
+        column_names = [str(l) for l in levels]
+        nlevel = len(levels)
+
+        if self.method in ['drop', 'sum']:
+            if self.drop_level is None: # these defaults consistent with R
+                drop_idx = 0 if self.method == 'drop' else nlevel - 1
+            else:
+                drop_idx = _level_index(levels, self.drop_level)
+            keep = np.ones(nlevel, bool)
+            keep[drop_idx] = 0
+            columns = [n for n, k in zip(column_names, keep) if k]
+            contrast = sp_sparse.identity(nlevel, format='csc')[:,keep]
+            if self.method == 'sum':
+                contrast = contrast.tolil()
+                contrast[drop_idx] = -1
+        elif callable(self.method):
+            contrast = sp_sparse.csr_matrix(np.asarray(self.method(nlevel), float))
+            columns = ['C({})'.format(i) for i in range(contrast.shape[1])]
+        elif self.method is None:
+            contrast = sp_sparse.identity(nlevel, format='csr')
+            columns = column_names
+        else:
+            raise ValueError('method must be one of ["drop", "sum", None] or a callable' +
+                             'that returns a contrast matrix and column names given the number' +
+                             ' of levels')
+
+        self.levels_ = levels
+        self.n_features_in_ = 1
+        self.columns_ = columns
+        # stored sparse: a dense (levels x levels) matrix is large
+        # for a categorical with many levels
+        self._contrast = sp_sparse.csr_matrix(contrast)
+        return self
+
+    @property
+    def contrast_matrix_(self):
+        # rows are levels, columns are those of the encoding
+        return self._contrast.toarray()
+
+    def _islp_sparse_transform(self, X):
+        # the encoding as a sparse matrix, never forming the dense
+        # (n x levels) indicator matrix
+        check_is_fitted(self)
+        codes, missing = _level_codes(X, self.levels_)
+        rows = np.flatnonzero(~missing)
+        indicator = sp_sparse.csr_matrix((np.ones(rows.shape[0]), (rows, codes[rows])),
+                                         shape=(codes.shape[0], len(self.levels_)))
+        value = sp_sparse.csr_matrix(indicator @ self._contrast)
+        if missing.any():
+            value = value.tolil()
+            value[np.flatnonzero(missing)] = np.nan
+            value = value.tocsr()
+        return value
+
+    def transform(self, X):
+        value = self._islp_sparse_transform(X).toarray()
+
+        if isinstance(X, (pd.DataFrame, pd.Series)):
+            df = pd.DataFrame(value, columns=self.columns_, copy=False)
+            df.index = X.index
+            return df
+        return value
+
+def _level_index(levels, level):
+    """
+    Index of `level` in `levels`, matched by value then by `str`.
+    """
+    for match in [lambda l: l == level,
+                  lambda l: str(l) == str(level)]:
+        idx = [i for i, l in enumerate(levels) if match(l)]
+        if idx:
+            return idx[0]
+    raise ValueError('level {0!r} is not among the observed levels {1}'.format(
+                     level, [str(l) for l in levels]))
+
+class Ordinal(TransformerMixin, BaseEstimator):
+
+    def __init__(self, levels=None):
+        """
+        Ordinal encoding for categorical variables: each entry
+        is replaced by the position of its level.
+
+        Parameters
+        ----------
+        levels : sequence (optional)
+            The levels in order. If None, the order must be
+            unambiguous: the categories of an ordered categorical
+            dtype (unused categories keep their positions), or
+            the sorted values of a numeric or boolean column.
+            Other columns, e.g. strings or an unordered categorical,
+            raise a `ValueError` since their sorted (alphabetical)
+            order is rarely the intended one.
+
+        Missing values are encoded as `np.nan`, and a level not
+        among the levels raises a `ValueError`.
+        """
+        self.levels = levels
+
+    def fit(self, X, y=None):
+
+        """
+        Find the levels of the categorical variable.
+
+        Parameters
+        ----------
+        X : array-like
+            Single column on which the encoding will be evaluated.
+
+        """
+
+        X = _as_series(X)
+        if self.levels is not None:
+            levels = list(self.levels)
+            if len(set(levels)) != len(levels):
+                raise ValueError('levels should not contain duplicates')
+            _level_codes(X, levels, during='fit')   # raises if X has other levels
+        elif isinstance(X.dtype, pd.CategoricalDtype) and X.dtype.ordered:
+            levels = list(X.dtype.categories)
+        elif (pd.api.types.is_numeric_dtype(X.dtype) or
+              pd.api.types.is_bool_dtype(X.dtype)):
+            levels = _observed_levels(X)
+        else:
+            raise ValueError(
+                'the order of the levels {0} is ambiguous: give it '
+                'with `levels=[...]`, or use an ordered pd.Categorical, '
+                'e.g. `X[col].cat.as_ordered()` or '
+                '`pd.Categorical(..., categories=[...], ordered=True)`'.format(
+                    [str(l) for l in _observed_levels(X)]))
+        self.levels_ = levels
+        self.n_features_in_ = 1
+        return self
+
+    def transform(self, X):
+        check_is_fitted(self)
+        codes, missing = _level_codes(X, self.levels_)
+        value = codes.astype(float).reshape((-1,1))
+        value[missing] = np.nan
+        return value
+
+def _term_columns(terms):
+    """
+    The columns of X that `terms` (column identifiers, Columns,
+    Features and tuples of these) are built from.
+    """
+    found = set()
+    def visit(t):
+        if isinstance(t, Feature):
+            for v in t.variables:
+                visit(v)
+        elif isinstance(t, Column):
+            found.add(t.idx)
+        elif isinstance(t, tuple):
+            for v in t:
+                visit(v)
+        else:
+            try:
+                found.add(t)
+            except TypeError:   # not a column identifier: an error later
+                pass
+    for t in terms:
+        visit(t)
+    return found
+
+def _native_columns(X):
+    # the column names of a non-pandas dataframe, else None
+    if (isinstance(X, (pd.DataFrame, pd.Series, np.ndarray)) or
+        sp_sparse.issparse(X)):
+        return None
+    try:
+        X_nw = nw.from_native(X, eager_only=True)
+    except TypeError:
+        return None
+    return list(X_nw.columns)
+
+def _from_native(X, columns=None):
+    """
+    Convert a dataframe (or series) of any eager backend supported by
+    narwhals, e.g. polars or pyarrow, to pandas. Returns the converted
+    `X` and a function converting a `pd.DataFrame` model matrix back to
+    that backend, or None if `X` was not converted.
+
+    If `columns` is given, only those columns of a dataframe are
+    converted (the copy is of the columns a model matrix uses).
+
+    Conversion through pandas keeps categoricals, including the order
+    of a polars Enum or an ordered pyarrow dictionary (as an ordered
+    `pd.Categorical`). The levels of an unordered categorical, e.g. a
+    polars Categorical, are stored in order of appearance; they are
+    sorted, as pandas does when it infers categories, so that the
+    model matrix does not depend on the order of the rows.
+    """
+    if (isinstance(X, (pd.DataFrame, pd.Series, np.ndarray)) or
+        sp_sparse.issparse(X)):
+        return X, None
+    try:
+        X_nw = nw.from_native(X, allow_series=True)
+    except TypeError:   # not a dataframe, e.g. a list: left to _check_X
+        return X, None
+    if isinstance(X_nw, nw.LazyFrame):
+        raise TypeError('Lazy frames are not supported by ModelSpec; '
+                        'collect them first, e.g. X.collect()')
+    backend = nw.get_native_namespace(X_nw)
+    if columns is not None and isinstance(X_nw, nw.DataFrame):
+        keep = [c for c in X_nw.columns if c in columns]
+        X_nw = X_nw.select(keep or X_nw.columns[:1])
+
+    def to_native(D):
+        duplicated = list(D.columns[D.columns.duplicated()])
+        if duplicated:
+            raise ValueError(f'the model matrix has duplicated column names {duplicated}, '
+                             'which this dataframe backend cannot hold')
+        return nw.from_dict({str(c): D[c].to_numpy() for c in D.columns},
+                            backend=backend).to_native()
+
+    X = X_nw.to_pandas()
+    if isinstance(X_nw, nw.Series):
+        dtypes = {X.name: X_nw.dtype}
+    else:
+        dtypes = dict(X_nw.schema)
+    for name, dtype in dtypes.items():
+        col = X if isinstance(X, pd.Series) else X[name]
+        if not isinstance(col.dtype, pd.CategoricalDtype):
+            continue
+        # some versions of polars convert an Enum to an unordered
+        # pd.Categorical: its categories are in the declared order
+        if dtype == nw.Enum:
+            col = col.cat.as_ordered()
+        elif not col.dtype.ordered:
+            col = col.cat.reorder_categories(sorted(col.dtype.categories))
+        else:
+            continue
+        if isinstance(X, pd.Series):
+            X = col
+        else:
+            X[name] = col
+    return X, to_native
+
+class ModelSpec(TransformerMixin, BaseEstimator):
+
+    '''Parameters
+    ----------
+
+    terms : sequence (optional)
+
+        Sequence of sets whose
+        elements are columns of *X* when fit.
+        For :py:class:`pd.DataFrame` these can be column
+        names.
+
+    intercept : bool, default=False
+
+        Include a column of ones named `'intercept'` as the first
+        column of the design? Pass `True` for statsmodels' models
+        (`OLS`, `GLM`, ...), which need the column; most scikit-learn
+        estimators, and glmstar's, fit the intercept themselves.
+
+    categorical_features : array-like of {bool, int} of shape (n_features) 
+            or shape (n_categorical_features,), default=None.
+
+        Indicates the categorical features. Will be ignored if *X* is a :py:class:`pd.DataFrame`
+        or :py:class:`pd.Series`.
+
+        - None : no feature will be considered categorical for :py:class:`np.ndarray`.
+        - boolean array-like : boolean mask indicating categorical features.
+        - integer array-like : integer indices indicating categorical
+          features.
+
+    categorical_encoders : dict (optional)
+
+        Encoders for the categorical columns of *X*, i.e. the columns of
+        categorical dtype of a :py:class:`pd.DataFrame` or those given by
+        *categorical_features* for an :py:class:`np.ndarray`. Its keys are
+        either:
+
+        - `'categorical'` : the encoder of every categorical column, ordered
+          or not, without its own entry, cloned for each column. Defaults
+          to `Contrast(method='drop')`, which drops the first level.
+        - `'ordinal'` : if present, used instead for the ordered
+          `pd.Categorical` columns, e.g. `{'ordinal': Ordinal()}` to
+          score each by the position of its level. No default.
+        - a column of *X* (a name for a :py:class:`pd.DataFrame`, an integer
+          for an :py:class:`np.ndarray`) : the encoder of that column.
+          Like the others it is cloned, and the clone is fit, so the
+          dictionary's encoders are not modified.
+
+        For an encoder of a single term, see :py:func:`contrast`
+        and :py:func:`ordinal`.
+
+    sparse_output : bool (optional)
+
+        If True, the model matrix is a `scipy.sparse.csr_matrix`.
+        Categorical encodings and their interactions are then built
+        sparse throughout, so a design with categoricals of many levels
+        never forms its dense columns; other columns (numeric, splines,
+        etc.) are dense blocks stored sparsely. Not compatible with
+        `set_output`.
+
+    '''
+
+    def __init__(self,
+                 terms=(),
+                 intercept=False,
+                 categorical_features=None,
+                 categorical_encoders=None,
+                 sparse_output=False
+                 ):
+
+        self.intercept = intercept
+        self.terms = terms
+        self.categorical_features = categorical_features
+        self.categorical_encoders = categorical_encoders
+        self.sparse_output = sparse_output
+
+    def _check_X(self, X, reset):
+        """
+        Validate `X`, returning a `pd.DataFrame` or 2-d `np.ndarray`.
+
+        If `reset`, record `n_features_in_` (and `feature_names_in_`
+        for a `pd.DataFrame`), else check an `np.ndarray` has
+        `n_features_in_` columns. Columns of a `pd.DataFrame` are
+        matched by name, so it may have other columns, in any order.
+        """
+        if isinstance(X, pd.Series):
+            X = X.to_frame()
+        if sp_sparse.issparse(X):
+            raise TypeError('Sparse data is not supported by ModelSpec; '
+                            'convert it with X.toarray()')
+        if not isinstance(X, pd.DataFrame):
+            X = np.asarray(X)
+            if X.ndim != 2:
+                raise ValueError('Expected a 2-dimensional array or a pd.DataFrame, '
+                                 f'got an array with {X.ndim} dimension(s). '
+                                 'Reshape your data either using array.reshape(-1, 1) '
+                                 'if your data has a single feature or array.reshape(1, -1) '
+                                 'if it contains a single sample.')
+            if np.iscomplexobj(X):
+                raise ValueError('Complex data not supported')
+        if X.shape[0] == 0:
+            raise ValueError(f'Found array with 0 sample(s) (shape={X.shape}) '
+                             'while a minimum of 1 is required.')
+        if X.shape[1] == 0:
+            raise ValueError(f'Found array with 0 feature(s) (shape={X.shape}) '
+                             'while a minimum of 1 is required.')
+        if reset:
+            self.n_features_in_ = X.shape[1]
+            if (isinstance(X, pd.DataFrame) and
+                all(isinstance(c, str) for c in X.columns)):
+                self.feature_names_in_ = np.asarray(X.columns, dtype=object)
+            elif hasattr(self, 'feature_names_in_'):
+                del self.feature_names_in_
+        elif (not isinstance(X, pd.DataFrame) and
+              X.shape[1] != self.n_features_in_):
+            raise ValueError(f'X has {X.shape[1]} features, but ModelSpec '
+                             f'is expecting {self.n_features_in_} features as input.')
+        return X
+
+    # the parameters of the terms, e.g. for GridSearchCV
+
+    def get_params(self, deep=True):
+        """
+        Get parameters of this ModelSpec.
+
+        With `deep`, these include the parameters of each term, as
+        `'terms__<i>__<parameter>'` for the term at position `i` of
+        `terms` (`'terms__<i>__<j>__<parameter>'` for part `j` of an
+        interaction), e.g. `'terms__0__df'` for `ns('x', df=4)`.
+        """
+        params = super().get_params(deep=deep)
+        # parameters are only validated at fit, so terms may be anything here
+        if deep and isinstance(self.terms, (list, tuple)):
+            for i, term in enumerate(self.terms):
+                for key, value in _term_params(term).items():
+                    params[f'terms__{i}__{key}'] = value
+        return params
+
+    def set_params(self, **params):
+        """
+        Set parameters of this ModelSpec.
+
+        A parameter of a term is set with `'terms__<i>__<parameter>'`,
+        where `i` is the position of the term in `terms` or the name
+        given to it, e.g. `'terms__price__df'` for
+        `ns('Price', df=4, name='price')`. A term made by `poly()`,
+        `ns()`, `bs()` or `pca()` is made again with the new parameter,
+        so its name (if not given) and its columns' names follow it.
+        `terms` itself is not modified: it is replaced by a copy, in
+        which every occurrence of the changed term (e.g. also in an
+        interaction) is changed.
+        """
+        term_params = {k: v for k, v in params.items() if k.startswith('terms__')}
+        rest = {k: v for k, v in params.items() if not k.startswith('terms__')}
+        if 'terms' in rest:   # a new terms first, then its parameters
+            super().set_params(terms=rest.pop('terms'))
+        if term_params:
+            terms = list(self.terms)
+            for key, value in term_params.items():
+                path = key.split('__')[1:]
+                i = _term_position(terms, path[0])
+                new_term, (old, new) = _set_term_param(terms[i], path[1:], value)
+                terms[i] = new_term
+                terms = [_substitute(t, old, new) for t in terms]
+            container = list if isinstance(self.terms, list) else tuple
+            super().set_params(terms=container(terms))
+        if rest:
+            super().set_params(**rest)
+        return self
+
+    # missing values in X propagate to the model matrix
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.input_tags.allow_nan = True
+        return tags
+
+    def _more_tags(self):   # scikit-learn < 1.6
+        return {'allow_nan': True}
+
+    def _include_intercept(self):
+        return bool(self.intercept)
+
+    def fit(self, X, y=None):
+
+        """
+        Fit the encoders of each term, determining
+        the columns of the model matrix.
+
+        Parameters
+        ----------
+        X : array-like
+            X on which model matrix will be evaluated.
+            If a :py:class:`pd.DataFrame` or :py:class:`pd.Series`, variables that are of
+            categorical dtype will be treated as categorical. Dataframes of other
+            backends supported by `narwhals`, such as `polars` or `pyarrow`, are
+            converted to `pandas`; `transform` then returns the model matrix
+            in the backend of its input.
+
+        y : None
+            Ignored. This parameter exists only for compatibility with
+            :py:class:`sklearn.pipeline.Pipeline`.
+
+        """
+        
+        if not isinstance(self.sparse_output, (bool, np.bool_)):
+            raise ValueError(f'sparse_output should be True or False, got {self.sparse_output!r}')
+        native_columns = _native_columns(X)
+        X, _ = _from_native(X, _term_columns(self.terms))
+        X = self._check_X(X, reset=True)
+        if native_columns is not None:   # describe all of X, not only the columns used
+            self.n_features_in_ = len(native_columns)
+            self.feature_names_in_ = np.asarray(native_columns, dtype=object)
+
+        # built at fit, not in __init__, so set_params(categorical_encoders=...)
+        # takes effect; update(dict) as the keys may be integers
+        self.categorical_encoders_ = {'categorical': Contrast(method='drop')}
+        if self.categorical_encoders is not None:
+            self.categorical_encoders_.update(self.categorical_encoders)
+
+        if isinstance(X, (pd.DataFrame, pd.Series)):
+            (categorical_features,
+             self.is_ordinal_) = _categorical_from_df(X)
+            (self.is_categorical_,
+             self.known_categories_) = _check_categories(categorical_features,
+                                                         X)
+            self.columns_ = X.columns
+            if self.is_categorical_ is None:
+                self.is_categorical_ = np.zeros(X.shape[1], bool)
+            self.is_ordinal_ = pd.Series(self.is_ordinal_,
+                                         index=self.columns_)
+            self.is_categorical_ = pd.Series(self.is_categorical_,
+                                             index=self.columns_)
+        else:
+            categorical_features = self.categorical_features
+            (self.is_categorical_,
+             self.known_categories_) = _check_categories(categorical_features,
+                                                         X)
+            if self.is_categorical_ is None:
+                self.is_categorical_ = np.zeros(X.shape[1], bool)
+            self.is_ordinal_ = np.zeros(self.is_categorical_.shape,
+                                        bool)
+            self.columns_ = np.arange(X.shape[1])
+
+        self.features_ = {}
+        self.encoders_ = {}
+
+        # encoders are fit on clones so that `self.terms` is never
+        # mutated and the spec can be refit (or cloned and refit)
+        clone_memo = {}
+
+        self.column_info_ = _get_column_info(X,
+                                             self.columns_,
+                                             np.asarray(self.is_categorical_),
+                                             np.asarray(self.is_ordinal_),
+                                             categorical_encoders=self.categorical_encoders_)
+
+        # include each column as a Feature
+        # so that their columns are built if needed
+
+        for col_ in self.columns_:
+            self.features_[col_] = Feature((col_,), str(col_), None, pure_columns=True) 
+
+        # find possible interactions and other features
+
+        tmp_cache = {}
+
+        # the encoders are fit on all of X, but the names and number of
+        # the columns of each term only need its fitted encoders: they are
+        # found by evaluating the terms on the first rows of X, so that
+        # fit does not build the model matrix
+        X_head = X.iloc[:2] if isinstance(X, pd.DataFrame) else X[:2]
+
+        for term in self.terms:
+            if isinstance(term, Feature):
+                term_ = _clone_term(term, clone_memo)
+                self.features_[term] = term_
+                build_columns(self.column_info_,
+                              X,
+                              term_,
+                              encoders=self.encoders_,
+                              col_cache=tmp_cache,
+                              fit=True, sparse=self.sparse_output,
+                              fit_only=True) # these encoders won't have been fit yet
+                for var, var_ in zip(term.variables, term_.variables):
+                    if var not in self.features_ and isinstance(var, Feature):
+                            self.features_[var] = var_
+            elif term not in self.column_info_:
+                # a tuple of features represents an interaction
+                if type(term) == type((1,)): 
+                    names = []
+                    column_map = {}
+                    column_names = {}
+                    idx = 0
+                    variables_ = []
+                    for var in term:
+                        if var in self.features_:   # already fit
+                            var_ = self.features_[var]
+                        else:
+                            var_ = _clone_term(var, clone_memo)
+                            if isinstance(var_, Column):
+                                var_.fit_encoder(X)
+                            else:
+                                build_columns(self.column_info_,
+                                              X,
+                                              var_,
+                                              encoders=self.encoders_,
+                                              col_cache=tmp_cache,
+                                              fit=True, sparse=self.sparse_output,
+                                              fit_only=True)
+                        # column identifiers are kept as is, Features and
+                        # Columns are replaced by their fitted copies
+                        variables_.append(var_ if isinstance(var, (Feature, Column)) else var)
+                        var = var_
+                        cols, cur_names = build_columns(self.column_info_,
+                                                        X_head,
+                                                        var,
+                                                        encoders=self.encoders_,
+                                                        sparse=self.sparse_output)
+                        column_map[var.name] = range(idx, idx + cols.shape[1])
+                        column_names[var.name] = cur_names
+                        idx += cols.shape[1]                 
+                        names.append(var.name)
+                    encoder_ = Interaction(names, column_map, column_names)
+                    self.features_[term] = Feature(tuple(variables_), ':'.join(n for n in names), encoder_)
+                elif isinstance(term, Column):
+                    term_ = _clone_term(term, clone_memo)
+                    self.features_[term] = Feature((term_,), term.name, None, pure_columns=True)
+                    term_.fit_encoder(X)
+                else:
+                    raise ValueError('each element in a term should be a Feature, Column or identify a column')
+                
+        # build the mapping of terms to columns and column names
+
+        self.column_names_ = {}
+        self.column_map_ = {}
+        self.terms_ = [self.features_[t] for t in self.terms]
+        
+        idx = 0
+        if self._include_intercept():
+            self.column_map_['intercept'] = slice(0, 1)
+            idx += 1 # intercept will be first column
+        
+        for term, term_ in zip(self.terms, self.terms_):
+            term_df, term_names = build_columns(self.column_info_,
+                                                X_head,
+                                                term_,
+                                                encoders=self.encoders_, sparse=self.sparse_output)
+            self.column_names_[term] = term_names
+            self.column_map_[term] = slice(idx, idx + term_df.shape[1])
+            idx += term_df.shape[1]
+    
+        return self
+    
+    def transform(self, X, y=None):
+        """
+        Build design on X after fitting.
+
+        Parameters
+        ----------
+        X : array-like
+
+        y : None
+            Ignored. This parameter exists only for compatibility with
+            :py:class:`sklearn.pipeline.Pipeline`.
+        """
+        check_is_fitted(self)
+        X, to_native = _from_native(X, _term_columns(self.terms_))
+        X = self._check_X(X, reset=False)
+        D = build_model(self.column_info_,
+                        X,
+                        self.terms_,
+                        intercept=self._include_intercept(),
+                        encoders=self.encoders_,
+                        sparse=self.sparse_output,
+                        order='C' if to_native is None else 'F')
+        return self._to_output(D, to_native)
+
+    def _to_output(self, D, to_native):
+        # a model matrix for a non-pandas dataframe is returned in its
+        # backend, unless an output container was chosen with set_output
+        config = getattr(self, '_sklearn_output_config', {}).get('transform', 'default')
+        if to_native is None or config != 'default' or sp_sparse.issparse(D):
+            return D
+        return to_native(D)
+
+    def get_feature_names_out(self, input_features=None):
+        """
+        Names of the columns of the model matrix.
+
+        Parameters
+        ----------
+        input_features : None
+            Ignored. This parameter exists only for compatibility with
+            :py:class:`sklearn.pipeline.Pipeline`.
+
+        Returns
+        -------
+        names : np.ndarray of str
+        """
+        check_is_fitted(self)
+        names = ['intercept'] if self._include_intercept() else []
+        for term in self.terms:
+            names.extend(str(n) for n in self.column_names_[term])
+        if not names:   # build_model returns a 'zero' column
+            names = ['zero']
+        return np.asarray(names, dtype=object)
+
+    # ModelSpec specific methods
+
+    @property
+    def names(self, help='Name for each term in model specification.'):
+        names = []
+        if self._include_intercept():
+            names = ['intercept']
+        return names + [t.name for t in self.terms_]
+        
+
+    def build_submodel(self,
+                       X,
+                       terms):
+        """
+        Build design on X after fitting.
+
+        Parameters
+        ----------
+        X : array-like
+            X on which columns are evaluated.
+
+        terms : [Feature]
+            Sequence of features. Elements of `self.terms`
+            are replaced by their fitted versions in `self.terms_`.
+
+        Returns
+        -------
+        D : array-like
+            Design matrix created with `terms`
+        """
+
+        check_is_fitted(self)
+        X, to_native = _from_native(X, _term_columns(terms))
+        X = self._check_X(X, reset=False)
+        terms = [self.features_.get(t, t) for t in terms]
+        D = build_model(self.column_info_,
+                        X,
+                        terms,
+                        intercept=self._include_intercept(),
+                        encoders=self.encoders_,
+                        sparse=self.sparse_output,
+                        order='C' if to_native is None else 'F')
+        return self._to_output(D, to_native)
+
+    def build_sequence(self,
+                       X,
+                       anova_type='sequential'):
+        """
+        Build implied sequence of submodels 
+        based on successively including more terms.
+
+        Parameters
+        ----------
+        X : array-like
+            X on which columns are evaluated.
+
+        anova_type: str
+            One of "sequential" or "drop".
+
+        Returns
+        -------
+
+        models : generator
+            Generator for sequence of models for ANOVA.
+
+        """
+
+        check_is_fitted(self)
+        X, to_native = _from_native(X, _term_columns(self.terms_))
+        X = self._check_X(X, reset=False)
+
+        if anova_type not in ['sequential', 'drop']:
+            raise ValueError('anova_type must be one of ["sequential", "drop"]')
+
+        if self.sparse_output:
+            blocks = [np.ones((X.shape[0], 1)) if self._include_intercept() else
+                      np.zeros((X.shape[0], 1))]
+            for term_ in self.terms_:
+                blocks.append(build_columns(self.column_info_,
+                                            X,
+                                            term_,
+                                            encoders=self.encoders_,
+                                            fit=False,
+                                            sparse=True)[0])
+            if anova_type == 'sequential':
+                return (_stack_sparse(blocks[:i], X.shape[0]) for i in range(1, len(blocks)+1))
+            return (_stack_sparse([b for j, b in enumerate(blocks) if j != i], X.shape[0])
+                    for i in range(len(blocks)))
+
+        col_cache = {}  # avoid recomputing the same columns
+
+        dfs = []
+
+        if self._include_intercept():
+            df_int = pd.DataFrame({'intercept':np.ones(X.shape[0])})
+            if isinstance(X, (pd.Series, pd.DataFrame)):
+                df_int.index = X.index
+            dfs.append(df_int)
+        else:
+            df_int = pd.DataFrame({'zero':np.zeros(X.shape[0])})
+            if isinstance(X, (pd.Series, pd.DataFrame)):
+                df_int.index = X.index
+            dfs.append(df_int)
+
+        for term_ in self.terms_:
+            term_df, _  = build_columns(self.column_info_,
+                                        X,
+                                        term_,
+                                        col_cache=col_cache,
+                                        encoders=self.encoders_,
+                                        fit=False)
+            if isinstance(X, (pd.Series, pd.DataFrame)):
+                term_df.index = X.index
+            # as in build_model, make boolean columns float
+            for i, col in enumerate(term_df.columns):
+                if term_df.iloc[:,i].dtype == bool:
+                    term_df[col] = term_df.iloc[:,i].astype(float)
+
+            dfs.append(term_df)
+
+        if anova_type == 'sequential':
+            if isinstance(X, (pd.Series, pd.DataFrame)):
+                seq = (pd.concat(dfs[:i], axis=1) for i in range(1, len(dfs)+1))
+            else:
+                seq = (np.column_stack(dfs[:i]) for i in range(1, len(dfs)+1))
+        elif anova_type == 'drop':
+            if isinstance(X, (pd.Series, pd.DataFrame)):
+                seq = (pd.concat([dfs[j] for j in range(len(dfs)) if j != i], axis=1) for i in range(len(dfs)))
+            else:
+                seq = (np.column_stack([dfs[j] for j in range(len(dfs)) if j != i]) for i in range(len(dfs)))
+        else:
+            raise ValueError('anova_type must be one of ["sequential", "drop"]')
+        return (self._to_output(D, to_native) for D in seq)
+
+def _clone_term(term, memo):
+    """
+    Copy a Feature or Column, replacing each encoder
+    (recursively) with an unfitted clone.
+
+    `memo` maps `id()` of terms and encoders already copied
+    to their copies, so a Feature or encoder that appears
+    in several places is copied (and later fit) only once.
+    """
+
+    if not isinstance(term, (Feature, Column)):
+        return term   # a column identifier
+    if id(term) in memo:
+        return memo[id(term)]
+
+    encoder = term.encoder
+    if encoder is not None:
+        if id(encoder) not in memo:
+            memo[id(encoder)] = clone(encoder, safe=False)
+        encoder = memo[id(encoder)]
+
+    if isinstance(term, Feature):
+        variables = tuple(_clone_term(v, memo) for v in term.variables)
+        term_ = term._replace(variables=variables, encoder=encoder)
+    else:
+        term_ = term._replace(encoder=encoder)
+    memo[id(term)] = term_
+    return term_
+
+def fit_encoder(encoders, var, X):
+    """
+    Fit an encoder if not already registered
+    in `encoders`.
+
+    Parameters
+    ----------
+
+    encoders : dict
+        Dictionary of encoders for each feature.
+
+    var : Feature
+        Feature whose encoder will be fit.
+
+    X : array-like
+        X on which encoder will be fit.
+
+    """
+
+    if var.encoder not in encoders:
+        encoders[var] = var.encoder.fit(X)
+            
+def build_columns(column_info, X, var, encoders={}, col_cache={}, fit=False, sparse=False,
+                  fit_only=False, as_array=False):
+    """
+    Build columns for a Feature from X.
+
+    Parameters
+    ----------
+
+    column_info: dict
+        Dictionary with values specifying sets of columns to
+        be concatenated into a design matrix.
+
+    X : array-like
+        X on which columns are evaluated.
+
+    var : Feature
+        Feature whose columns will be built, typically a key in `column_info`.
+
+    encoders : dict
+        Dict that stores encoder of each Feature.
+    
+    col_cache: dict
+        Dict where columns will be stored --
+        if `var.name` in `col_cache` then just
+        returns those columns.
+
+    fit : bool (optional)
+        If True, then try to fit encoder.
+        Will raise an error if encoder has already been fit.
+
+    sparse : bool (optional)
+        If True, return the columns as a `scipy.sparse` matrix or
+        `np.ndarray` (not a `pd.DataFrame`), keeping categorical
+        encodings and their interactions sparse.
+
+    fit_only : bool (optional)
+        With `fit`, fit the encoders of a Feature (and of the features
+        and columns it is built from) without evaluating its columns:
+        returns `(None, None)`.
+
+    as_array : bool (optional)
+        If True, return the columns as a 2-d `np.ndarray` rather than
+        a `pd.DataFrame`.
+
+    """
+
+    if var in column_info:
+        var = column_info[var]
+
+    docache = DOCACHE and not sparse
+    if docache and joblib_hash([var, X]) in col_cache:
+        return col_cache[joblib_hash([var, X])]
+
+    if isinstance(var, Column):
+        if docache:
+            if joblib_hash([var, X]) not in col_cache:
+                cols, names = var.get_columns(X, fit=fit)
+                col_cache[joblib_hash([var, X])] = cols, names
+            cols, name = col_cache[joblib_hash([var, X])]
+        else:
+            cols, names = var.get_columns(X, fit=fit, sparse=sparse)
+    elif isinstance(var, Feature):
+        if fit and fit_only and not var.encoder:
+            # nothing to fit here: only the variables need fitting
+            for v in var.variables:
+                if v in column_info:
+                    continue
+                if isinstance(v, Feature):
+                    build_columns(column_info, X, v, encoders=encoders,
+                                  col_cache=col_cache, fit=True, sparse=sparse,
+                                  fit_only=True)
+                elif isinstance(v, Column):
+                    v.fit_encoder(X)
+            return None, None
+        cols = []
+        names = []
+        for v in var.variables:
+            cur, cur_names = build_columns(column_info,
+                                           X,
+                                           v,
+                                           encoders=encoders,
+                                           col_cache=col_cache,
+                                           fit=fit,
+                                           sparse=sparse,
+                                           as_array=True)
+            cols.append(cur)
+            names.extend(cur_names)
+        if any(sp_sparse.issparse(c) for c in cols):
+            cols = sp_sparse.hstack([c if sp_sparse.issparse(c) else
+                                     sp_sparse.csc_matrix(_as_2d(c)) for c in cols],
+                                    format='csc')
+        elif len(cols) == 1:   # np.column_stack would copy it
+            cols = _as_2d(cols[0])
+        else:
+            cols = np.column_stack(cols)
+        if len(names) != cols.shape[1]:
+            names = ['{0}[{1}]'.format(var.name, j) for j in range(cols.shape[1])]
+        if var.encoder:
+            if sp_sparse.issparse(cols) and isinstance(var.encoder, Interaction):
+                df_cols = cols   # products of sparse columns stay sparse
+            else:
+                df_cols = pd.DataFrame(_dense(cols),
+                                       columns=names,
+                                       copy=False)
+            try:
+                check_is_fitted(var.encoder)
+                # ModelSpec.fit clones encoders, so one that is already fit
+                # was kept by clone(), e.g. a sklearn.frozen.FrozenEstimator:
+                # use it as is
+                if fit and var not in encoders:
+                    encoders[var] = var.encoder
+            except NotFittedError as e:
+                if fit:
+                    fit_encoder(encoders,
+                                var,
+                                df_cols)
+                # known issue with Pipeline
+                # https://github.com/scikit-learn/scikit-learn/issues/18648
+                elif isinstance(var.encoder, Pipeline):  
+                    check_is_fitted(var.encoder, 'n_features_in_') 
+                else:
+                    raise(e)
+            except Exception as e:  # was not the NotFitted
+                raise ValueError(e)
+            if fit_only:
+                return None, None
+            if var.use_transform:
+                cols = var.encoder.transform(df_cols)
+            else:
+                cols = var.encoder.predict(df_cols)
+            if not sparse:
+                cols = _dense(cols)
+            elif not sp_sparse.issparse(cols):
+                cols = np.asarray(cols)
+            if hasattr(var.encoder, 'columns_') and not var.override_encoder_colnames:
+                names = var.encoder.columns_
+            else:
+                if cols.ndim > 1 and cols.shape[1] > 1:
+                    names = ['{0}[{1}]'.format(var.name, j) for j in range(cols.shape[1])]
+                else:
+                    names = [var.name]
+
+
+    else:
+        raise ValueError('expecting either a column or a Feature')
+    if sparse:
+        return (cols if sp_sparse.issparse(cols) else _as_2d(cols)), names
+    if as_array:
+        return _as_2d(_dense(cols)), names
+    val = pd.DataFrame(_dense(cols), columns=names, copy=False)
+
+    if isinstance(X, (pd.DataFrame, pd.Series)):
+        val.index = X.index
+
+    if docache:
+        col_cache[joblib_hash([var.name, X])] = (val, names)
+    return val, names
+
+def _fill_model(column_info, X, terms, intercept, encoders, order='C'):
+    # the dense model matrix, as float: its columns are allocated once
+    # (their number found from the first rows of X) and each term's
+    # block is copied in and freed, so the peak memory is the model
+    # matrix and its largest block. order='F' stores each column
+    # contiguously, so that e.g. polars can take them without a copy
+    X_head = X.iloc[:2] if isinstance(X, pd.DataFrame) else X[:2]
+    names, widths = (['intercept'], [1]) if intercept else ([], [])
+    for term_ in terms:
+        head, head_names = build_columns(column_info, X_head, term_,
+                                         encoders=encoders, as_array=True)
+        names.extend(head_names)
+        widths.append(head.shape[1])
+    D = np.empty((X.shape[0], sum(widths)), order=order)
+    start = 0
+    if intercept:
+        D[:, 0] = 1
+        start = 1
+    for term_, width in zip(terms, widths[1:] if intercept else widths):
+        block = build_columns(column_info, X, term_, encoders=encoders,
+                              as_array=True)[0]
+        D[:, start:start + width] = block
+        start += width
+        del block
+    if isinstance(X, (pd.DataFrame, pd.Series)):
+        return pd.DataFrame(D, columns=names, index=X.index, copy=False)
+    return D
+
+def _dense(cols):
+    return cols.toarray() if sp_sparse.issparse(cols) else np.asarray(cols)
+
+def _as_2d(cols):
+    cols = np.asarray(cols)
+    return cols.reshape((cols.shape[0], -1))
+
+def _stack_sparse(blocks, n):
+    # blocks (sparse or dense) as one CSR matrix of floats
+    if not blocks:
+        blocks = [np.zeros((n, 1))]
+    return sp_sparse.hstack([b if sp_sparse.issparse(b) else
+                             sp_sparse.csr_matrix(_as_2d(b).astype(float))
+                             for b in blocks], format='csr', dtype=float)
+
+def build_model(column_info,
+                X,
+                terms,
+                intercept=True,
+                encoders={},
+                sparse=False,
+                order='C'):
+
+    """
+    Construct design matrix on a
+    sequence of terms and X after 
+    fitting.
+
+    Parameters
+    ----------
+    column_info: dict
+        Dictionary with values specifying sets of columns to
+        be concatenated into a design matrix.
+
+    X : array-like
+        X on which columns are evaluated.
+
+    terms : [Feature]
+        Sequence of features
+
+    encoders : dict
+        Dict that stores encoder of each Feature.
+
+    sparse : bool
+        If True, return a `scipy.sparse.csr_matrix`.
+
+    order : 'C' or 'F'
+        The memory layout of a dense model matrix.
+
+    Returns
+    -------
+    df : np.ndarray, pd.DataFrame or scipy.sparse.csr_matrix
+        Design matrix.
+    """
+
+    if sparse:
+        blocks = [np.ones((X.shape[0], 1))] if intercept else []
+        for term_ in terms:
+            blocks.append(build_columns(column_info,
+                                        X,
+                                        term_,
+                                        encoders=encoders,
+                                        fit=False,
+                                        sparse=True)[0])
+        return _stack_sparse(blocks, X.shape[0])
+
+    if terms or intercept:
+        return _fill_model(column_info, X, terms, intercept, encoders, order=order)
+
+    dfs = []
+
+    col_cache = {}  # avoid recomputing the same columns
+
+    if intercept:
+        df = pd.DataFrame({'intercept':np.ones(X.shape[0])})
+        if isinstance(X, (pd.Series, pd.DataFrame)):
+            df.index = X.index
+        dfs.append(df)
+
+    for term_ in terms:
+        term_df = build_columns(column_info,
+                                X,
+                                term_,
+                                col_cache=col_cache,
+                                encoders=encoders,
+                                fit=False)[0]
+        dfs.append(term_df)
+
+    if len(dfs):
+        if isinstance(X, (pd.Series, pd.DataFrame)):
+            df = pd.concat(dfs, axis='columns')
+            df.index = X.index
+        else:
+            return np.column_stack(dfs).astype(float)
+    else:  # return a 0 design
+        zero = np.zeros(X.shape[0])
+        if isinstance(X, (pd.Series, pd.DataFrame)):
+            df = pd.DataFrame({'zero': zero})
+            df.index = X.index
+        else:
+            return zero
+
+    # if we reach here, we will be returning a DataFrame
+    # make sure all columns are floats
+    
+    for i, col in enumerate(df.columns):
+        if df.iloc[:,i].dtype == bool:
+            df[col] = df.iloc[:,i].astype(float)
+    return df
+
+def derived_feature(variables, encoder=None, name=None, use_transform=True):
+    """
+    Create a Feature, optionally
+    applying an encoder to the stacked columns.
+    
+    Parameters
+    ----------
+
+    variables : [column identifier, Column, Feature]
+        Variables to apply transform to. Could be
+        column identifiers or variables: all columns
+        will be stacked before encoding.
+
+    name : str (optional)
+        Defaults to `str(encoder)`.
+
+    encoder :  transform-like (optional)
+        Transform obeying sklearn fit/transform convention.
+
+    Returns
+    -------
+
+    var : Feature
+    """
+
+    if name is None:
+        name = str(encoder)
+    var = Feature(tuple([v for v in variables]),
+                   name,
+                   encoder,
+                   use_transform=use_transform,
+                   override_encoder_colnames=True)
+    return var
+
+def contrast(col,
+             method='drop',
+             drop_level=None):
+    """
+    Create encoding of categorical feature.
+    
+    Parameters
+    ----------
+
+    col: column identifier
+
+    method: 'drop', 'sum', None or callable
+
+    drop_level: level identifier
+
+    Returns
+    -------
+
+    var : Feature
+
+    """
+
+    if isinstance(col, Column):
+        name = col.name
+        col = col.idx
+    else:
+        name = str(col)
+    encoder = Contrast(method,
+                       drop_level=drop_level)
+    return Column(col,
+                  name,
+                  is_categorical=True,
+                  encoder=encoder)
+
+def ordinal(col, name=None, levels=None):
+    """
+    Create ordinal encoding of categorical feature: a single
+    column holding the position of each entry's level (see `Ordinal`).
+
+    Parameters
+    ----------
+
+    col: column identifier
+
+    name: str (optional)
+        Defaults to `'ordinal(col)'`.
+
+    levels: sequence (optional)
+        The levels in order. Needed unless `col` is an ordered
+        categorical, or numeric.
+
+    Returns
+    -------
+
+    var : Column
+
+    """
+
+    if isinstance(col, Column):
+        colname = col.name
+        col = col.idx
+    else:
+        colname = str(col)
+    if name is None:
+        name = f'ordinal({colname})'
+    return Column(col,
+                  name,
+                  is_categorical=True,
+                  is_ordinal=True,
+                  columns=(name,),
+                  encoder=Ordinal(levels=levels))
+
+def poly(col,
+         degree=1,
+         intercept=False,
+         raw=False,
+         name=None):
+
+    """
+    Create a polynomial Feature
+    for a given column.
+    
+    Additional `args` and `kwargs`
+    are passed to `Poly`.
+
+    Parameters
+    ----------
+
+    col : column identifier or Column
+        Column to transform.
+
+    degree : int, default=1
+        Degree of polynomial.
+
+    intercept : bool, default=False
+        Include a column for intercept?
+
+    raw : bool, default=False
+        If False, perform a QR decomposition on the resulting
+        matrix of powers of centered and / or scaled features.
+
+    name : str (optional)
+        Defaults to one derived from col.
+
+    Returns
+    -------
+
+    var : Feature
+    """
+    shortname, klass = 'poly', Poly
+    spec = _spec('poly', (col,), degree=degree, intercept=intercept, raw=raw, name=name)
+    encoder = klass(degree=degree,
+                    raw=raw,
+                    intercept=intercept) 
+    if name is None:
+        if isinstance(col, Column):
+            name = col.name
+        else:
+            name = str(col)
+
+        kwargs = {}
+        if intercept:
+            kwargs['intercept'] = True
+        if raw:
+            kwargs['raw'] = True
+
+        _args = _argstring(degree=degree,
+                           **kwargs)
+        if _args:
+            name = ', '.join([name, _args])
+
+        name = f'{shortname}({name})'
+
+    return derived_feature([col],
+                            name=name,
+                            encoder=encoder)._replace(spec=spec)
+
+def ns(col, intercept=False, name=None, **spline_args):
+    """
+    Create a natural spline Feature
+    for a given column.
+    
+    Additional *spline_args*
+    are passed to :py:class:`NaturalSpline` along with *intercept*.
+
+    Parameters
+    ----------
+
+    col : column identifier or Column
+
+    intercept : bool
+        Include an intercept column.
+
+    name : str (optional)
+        Defaults to one derived from col.
+
+    Returns
+    -------
+
+    var : Feature
+
+    """
+    shortname, klass = 'ns', NaturalSpline
+    spec = _spec('ns', (col,), intercept=intercept, name=name, **spline_args)
+    if name is None:
+        if isinstance(col, Column):
+            name = col.name
+        else:
+            name = str(col)
+
+        _args = _argstring(**spline_args)
+        if _args:
+            name = ', '.join([name, _args])
+
+        name = f'{shortname}({name})'
+    encoder = klass(intercept=intercept,
+                    **spline_args) 
+    return derived_feature([col],
+                            name=name,
+                            encoder=encoder)._replace(spec=spec)
+
+def bs(col, intercept=False, name=None, **spline_args):
+    """
+    Create a B-spline Feature
+    for a given column.
+    
+    Additional args and *spline_args*
+    are passed to :py:class:`modelmatrix.transforms.BSpline`
+    along with *intercept*.
+
+    Parameters
+    ----------
+
+    col : column identifier or Column
+
+    intercept : bool
+        Include an intercept column.
+
+    name : str (optional)
+        Defaults to one derived from col.
+
+    Returns
+    -------
+
+    var : Feature
+
+    """
+    shortname, klass = 'bs', BSpline
+    spec = _spec('bs', (col,), intercept=intercept, name=name, **spline_args)
+    if name is None:
+        if isinstance(col, Column):
+            name = col.name
+        else:
+            name = str(col)
+
+        _args = _argstring(**spline_args)
+        if _args:
+            name = ', '.join([name, _args])
+
+        name = f'{shortname}({name})'
+    encoder = klass(intercept=intercept,
+                    **spline_args) 
+    return derived_feature([col],
+                            name=name,
+                            encoder=encoder)._replace(spec=spec)
+
+def pca(variables, name, scale=False, **pca_args):
+    """
+    Create PCA encoding of features
+    from a sequence of variables.
+    
+    Additional args and *pca_args*
+    are passed to :py:class:`modelmatrix.transforms.PCA`.
+
+    Parameters
+    ----------
+
+    variables : [column identifier, Column or Feature]
+        Sequence whose columns will be encoded by PCA.
+
+    Returns
+    -------
+
+    var : Feature
+
+    """
+    shortname, klass = 'pca', PCA
+    spec = _spec('pca', (variables, name), scale=scale, **pca_args)
+    encoder = klass(**pca_args) 
+    if scale:
+        scaler = StandardScaler(with_mean=True,
+                                with_std=True)
+        encoder = make_pipeline(scaler, encoder)
+
+    _args = _argstring(**pca_args)
+
+    if _args:
+        name = ', '.join([name, _args])
+
+    return derived_feature(variables,
+                            name=f'{shortname}({name})',
+                            encoder=encoder)._replace(spec=spec)
+
+
+def _argstring(*args, **kwargs):
+    _args = ', '.join([str(a) for a in args])
+    _kwargs = ', '.join([f'{k}={v}' for k, v in kwargs.items()])
+
+    if args and kwargs:
+        return ', '.join([_args, _kwargs])
+    elif args:
+        return _args
+    elif kwargs:
+        return _kwargs
+    else:
+        return ''
+
+#### parameters of the terms of a ModelSpec, e.g. for GridSearchCV
+
+def _freeze(v):
+    # a hashable version of a parameter value, so that Features stay hashable
+    if isinstance(v, np.ndarray):
+        return tuple(_freeze(x) for x in v.tolist())
+    if isinstance(v, (list, tuple)) and not isinstance(v, (Feature, Column)):
+        return tuple(_freeze(x) for x in v)
+    return v
+
+def _spec(helper, args, **kwargs):
+    # how `helper` was called; a name is kept only if one was given
+    if kwargs.get('name') is None:
+        kwargs.pop('name', None)
+    return (helper, tuple(_freeze(a) for a in args),
+            tuple(sorted((k, _freeze(v)) for k, v in kwargs.items())))
+
+def _rebuild(feature, **changes):
+    # the Feature made again by its helper, with some parameters changed
+    helper, args, kwargs = feature.spec
+    kwargs = dict(kwargs)
+    kwargs.update(changes)
+    if helper == 'pca':
+        args = (list(args[0]),) + tuple(args[1:])
+    return {'poly': poly, 'ns': ns, 'bs': bs, 'pca': pca}[helper](*args, **kwargs)
+
+def _encoder_params(encoder):
+    if encoder is None or not hasattr(encoder, 'get_params'):
+        return {}
+    if isinstance(encoder, Pipeline):   # pca(..., scale=True): the PCA's parameters
+        encoder = encoder.steps[-1][1]
+    return encoder.get_params(deep=False)
+
+def _term_params(term):
+    """
+    The parameters of a term that `ModelSpec.set_params` can change,
+    e.g. {'df': 4, 'intercept': False, ...} for ns('x', df=4).
+    """
+    if isinstance(term, Feature):
+        params = _encoder_params(term.encoder)
+        if term.spec is not None:
+            params.update((k, v) for k, v in term.spec[2] if k != 'name')
+        return params
+    if isinstance(term, Column):
+        return _encoder_params(term.encoder)
+    if isinstance(term, tuple):   # an interaction: the parameters of its parts
+        return {f'{j}__{k}': v for j, part in enumerate(term)
+                for k, v in _term_params(part).items()}
+    return {}
+
+def _set_term_param(term, path, value):
+    """
+    A copy of `term` with the parameter at `path` (e.g. ['df'], or
+    ['0', 'degree'] for a part of an interaction) set to `value`, and the
+    (old, new) pair of the Feature or Column that was replaced.
+    """
+    if isinstance(term, tuple) and not isinstance(term, (Feature, Column)):
+        if not path or not path[0].isdigit() or int(path[0]) >= len(term):
+            raise ValueError(f'expecting the position of a part of the interaction {term!r}, '
+                             f'got {"__".join(path)!r}')
+        j = int(path[0])
+        part, replaced = _set_term_param(term[j], path[1:], value)
+        return term[:j] + (part,) + term[j+1:], replaced
+    if not isinstance(term, (Feature, Column)):
+        raise ValueError(f'the term {term!r} has no parameters to set')
+    valid = _term_params(term)
+    if len(path) != 1 or path[0] not in valid:
+        raise ValueError(f'invalid parameter {"__".join(path)!r} for the term {term.name!r}; '
+                         f'valid parameters are {sorted(valid)}')
+    param = path[0]
+    if isinstance(term, Feature) and term.spec is not None:
+        new = _rebuild(term, **{param: value})
+    else:
+        encoder = term.encoder
+        if isinstance(encoder, Pipeline):
+            encoder = clone(encoder).set_params(**{f'{encoder.steps[-1][0]}__{param}': value})
+        else:
+            encoder = clone(encoder).set_params(**{param: value})
+        new = term._replace(encoder=encoder)
+    return new, (term, new)
+
+def _substitute(term, old, new):
+    # `term` with every occurrence of the object `old` replaced by `new`
+    if term is old:
+        return new
+    if isinstance(term, Feature):
+        variables = tuple(_substitute(v, old, new) for v in term.variables)
+        if any(a is not b for a, b in zip(variables, term.variables)):
+            return term._replace(variables=variables)
+        return term
+    if isinstance(term, tuple) and not isinstance(term, Column):
+        parts = tuple(_substitute(v, old, new) for v in term)
+        return parts if any(a is not b for a, b in zip(parts, term)) else term
+    return term
+
+def _term_position(terms, key):
+    # the position in `terms` of the term named by `key`: a position, or a name
+    if key.isdigit():
+        if int(key) >= len(terms):
+            raise ValueError(f'there is no term at position {key}: there are {len(terms)} terms')
+        return int(key)
+    found = [i for i, t in enumerate(terms) if getattr(t, 'name', None) == key]
+    if len(found) != 1:
+        raise ValueError(f'expecting a position in terms, or the name of exactly one term, '
+                         f'got {key!r} ({len(found)} terms have that name)')
+    return found[0]