TensorTerm

class pygam.terms.TensorTerm(*args, **kwargs)

Bases: SplineTerm, MetaTermMixin

Creates an instance of a Tensor Term.

This is useful for creating interactions between features or other terms.

Note

te(...) is preferred over TensorTerm(...)

although they are equivalent.

Parameters:

*argsTerms or Indices of features to combine into a tensorm product.

For example, we can create a tensor term from marginal spline terms on features 0 and 1:

>>> te(0, 1)

Or we can do it more explicitly by first instantiating the splines on each feature:

>>> te(s(0), s(1))

This representation is useful in order to control specific arguments individual marginal terms:

>>> te(s(0), s(1, n_splines=20))

Note

This is the preferred way to specify marginal terms.

Marginal terms can alternatively be specified via the kwarg feature=... but not both.

featurelist of Terms or list of integers to use for marginal terms, default=None

If None, then must be specified via *args

Note

This is not the preferred way to specify marginal terms.

The preferred way is via *args

This format exists mostly for symmetry, since it can be easier to align arguments of terms

For example we can build as follows:

>>> te(feature=(0, 1), n_splines=(10,20))

which is equivalent to

>>> te(s(0, n_splines=10), s(1, n_splines=20))

n_splinesint or list of integers, one per maginal term, default=10

Number of splines to use for each marginal term.

If single value is passed, it will be repeated for every marginal term.

If iterable is passed, it must be of same length as feature.

spline_orderint or list of integers, one per marginal term, default=3

Order of spline to use for the feature function.

If iterable is passed, it must be of same length as feature.

lamfloat or iterable of floats, default=0.6

Strength of smoothing penalty. Must be a positive float.

Larger values enforce stronger smoothing.

If a single value is passed, it will be repeated for every penalty.

If an iterable is passed, the length of lam must equal the length of feature

Multiple smoothing penalties are allowed per merginal term.

In this case, lam should be an iterable of iterables of floats, where the outer length matches the length of feature and the length of each inner iterable matches the number of penalties per term.

penalties{‘auto’, ‘derivative’, ‘l2’, ‘periodic’, None} or callable, or iterable of these, default=’auto’

Type of smoothing penalty to apply to the term.

If ‘auto’, then 2nd derivative smoothing for ‘numerical’ dtypes, and L2/ridge smoothing for ‘categorical’ dtypes.

If an iterable is passed, the length of penalties must match the length of feature.

Multiple smoothing penalties can be applied to each marginal term.

In this case, penalties should be an iterable of iterables of penalties. The outer length must match the length of feature and the length of each inner iterable should match the number of penalties per term.

Custom penalties can be passed as callables.

constraints{None, ‘convex’, ‘concave’, ‘monotonic_inc’, ‘monotonic_dec’} or callable, or iterable of these, default=None

Type of constraint to apply to the term.

If an iterable is passed, the length of constraints must match the length of feature.

Multiple constraints can be applied to each term.

In this case, constraints should be an iterable of iterables of constraints. The outer length must match the length of feature and the length of each inner iterable should match the number of constraints per term.

Custom constraints can be passed as callables.

dtypelist of {‘numerical’, ‘categorical’}

String describing the data-type of the feature.

Must be of same length as feature.

basislist of {‘ps’, ‘cp’}

Type of basis function to use in the term.

ps :

p-spline basis

cp :

cyclic p-spline basis, useful for building periodic functions. by default, the maximum and minimum of the feature values are used to determine the function’s period. To specify a custom period use argument edge_knots

Must be of same length as feature.

edge_knotsoptional, array-like of floats of length 2, iterable of array-like, default=None

These values specify minimum and maximum domain of the marginal term spline functions.

In the case that basis="cp", edge_knots determines the period of the cyclic function.

When edge_knots=None these values are inferred from the data.

byint, optional

Feature to use as an overall by-variable in the complete Tensor Term.

For example, if feature = [1, 2] by = 0, then the term will produce:

>>> x0 * te(x1, x2)

In order to apply a by-variable to a marginal term, then it must be added explicitly to the marginal term before building the Tensor Term.

Attributes:

n_coefsint

Number of coefficients contributed by the term to the model.

istensorbool

whether the term is a tensor product of sub-terms

isinterceptbool

whether the term is an intercept

hasconstraintbool

bool, whether the term has any constraints.

infodict

Get information about this term.

Methods

build_columns(X[, verbose])	Construct the model matrix columns for the term.
build_constraints(coef, constraint_lam, ...)	Builds the GAM block-diagonal constraint matrix in quadratic form out of constraint matrices specified for each feature.
build_from_info(info)	Build a TensorTerm instance from a dict.
build_penalties()	Builds the GAM block-diagonal penalty matrix in quadratic form out of penalty matrices specified for each feature.
compile(X[, verbose])	Method to validate and prepare data-dependent parameters.
get_params([deep])	Returns a dict of all of the object's user-facing parameters.
set_params([deep, force])	Sets an object's parameters.

Examples

We can build a tensor term where each marginal term has a by-variable

>>> te(s(0, by=2), s(1, by=3))

build_columns(X, verbose=False)

Construct the model matrix columns for the term.

Parameters:

Xarray-like

Input dataset with n rows

verbosebool

whether to show warnings

Returns:

scipy sparse array with n rows

build_constraints(coef, constraint_lam, constraint_l2)

Builds the GAM block-diagonal constraint matrix in quadratic form out of constraint matrices specified for each feature.

Parameters:

coefsarray-like containing the coefficients of a term

constraint_lamfloat,

penalty to impose on the constraint.

typically this is a very large number.

constraint_l2float,

loading to improve the numerical conditioning of the constraint matrix.

typically this is a very small number.

Returns:

Csparse CSC matrix containing the model constraints in quadratic form

classmethod build_from_info(info)

Build a TensorTerm instance from a dict.

Parameters:

clsclass

infodict

contains all information needed to build the term

build_penalties()

Builds the GAM block-diagonal penalty matrix in quadratic form out of penalty matrices specified for each feature.

each feature penalty matrix is multiplied by a lambda for that feature.

so for m features: P = block_diag[lam0 * P0, lam1 * P1, lam2 * P2, … , lamm * Pm]

Parameters:

None

Returns:

Psparse CSC array containing the model penalties in quadratic form

compile(X, verbose=False)

Method to validate and prepare data-dependent parameters.

Parameters:

Xarray-like

Input dataset

verbosebool

whether to show warnings

Returns:

None

get_params(deep=False)

Returns a dict of all of the object’s user-facing parameters.

Parameters:

deepboolean, default: False

when True, also gets non-user-facing parameters

Returns:

dict

set_params(deep=False, force=False, **parameters)

Sets an object’s parameters.

Parameters:

deepboolean, default: False

when True, also sets non-user-facing parameters

forceboolean, default: False

when True, also sets parameters that the object does not already have

**parametersparameters to set

Returns:

self