models.model_spec#
Module: models.model_spec#
Inheritance diagram for ISLP.models.model_spec:
Model specification#
This module defines the basic object to represent regression formula: ModelSpec.
Classes#
Contrast#
- class ISLP.models.model_spec.Contrast(method='drop', drop_level=None)#
Bases:
TransformerMixin,BaseEstimator- Attributes:
- contrast_matrix_
Methods
fit(X[, y])Construct contrast of categorical variable for use in building a design matrix.
fit_transform(X[, y])Fit to data, then transform it.
Get metadata routing of this object.
get_params([deep])Get parameters for this estimator.
set_output(*[, transform])Set output container.
set_params(**params)Set the parameters of this estimator.
transform
- __init__(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_levellevel 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.
- property contrast_matrix_#
- fit(X, y=None)#
Construct contrast of categorical variable for use in building a design matrix.
- Parameters:
- Xarray-like
X on which model matrix will be evaluated. If a
pd.DataFrameorpd.Series, variables that are of categorical dtype will be treated as categorical.
- Returns:
- Farray-like
Columns of design matrix implied by the categorical variable.
- fit_transform(X, y=None, **fit_params)#
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
- Parameters:
- Xarray-like of shape (n_samples, n_features)
Input samples.
- yarray-like of shape (n_samples,) or (n_samples, n_outputs), default=None
Target values (None for unsupervised transformations).
- **fit_paramsdict
Additional fit parameters. Pass only if the estimator accepts additional params in its fit method.
- Returns:
- X_newndarray array of shape (n_samples, n_features_new)
Transformed array.
- get_metadata_routing()#
Get metadata routing of this object.
Please check User Guide on how the routing mechanism works.
- Returns:
- routingMetadataRequest
A
MetadataRequestencapsulating routing information.
- get_params(deep=True)#
Get parameters for this estimator.
- Parameters:
- deepbool, default=True
If True, will return the parameters for this estimator and contained subobjects that are estimators.
- Returns:
- paramsdict
Parameter names mapped to their values.
- set_output(*, transform=None)#
Set output container.
Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.
- Parameters:
- transform{“default”, “pandas”, “polars”}, default=None
Configure output of transform and fit_transform.
“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged
Added in version 1.4: “polars” option was added.
- Returns:
- selfestimator instance
Estimator instance.
- set_params(**params)#
Set the parameters of this estimator.
The method works on simple estimators as well as on nested objects (such as
Pipeline). The latter have parameters of the form<component>__<parameter>so that it’s possible to update each component of a nested object.- Parameters:
- **paramsdict
Estimator parameters.
- Returns:
- selfestimator instance
Estimator instance.
- transform(X)#
Feature#
- class ISLP.models.model_spec.Feature(variables: tuple, name: str, encoder: Any, use_transform: bool = True, pure_columns: bool = False, override_encoder_colnames: bool = False, spec: Any = None)#
Bases:
NamedTupleAn element in a model matrix that will build columns from an array-like X.
Methods
count(value, /)Return number of occurrences of value.
index(value[, start, stop])Return first index of value.
- __init__(*args, **kwargs)#
- count(value, /)#
Return number of occurrences of value.
- index(value, start=0, stop=sys.maxsize, /)#
Return first index of value.
Raises ValueError if the value is not present.
ModelSpec#
- class ISLP.models.model_spec.ModelSpec(terms=(), intercept=None, categorical_features=None, categorical_encoders=None, sparse_output=False)#
Bases:
TransformerMixin,BaseEstimator- Parameters:
- termssequence (optional)
Sequence of sets whose elements are columns of X when fit. For
pd.DataFramethese can be column names.- interceptbool or None (optional)
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, and False for estimators that fit the intercept themselves (glmstar’s estimators and most scikit-learn estimators). The default, None, behaves as True but issues a FutureWarning at fit: the default will change to False in ISLP 0.7, when ModelSpec moves to its own package.
- categorical_featuresarray-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
pd.DataFrameorpd.Series.None : no feature will be considered categorical for
np.ndarray.boolean array-like : boolean mask indicating categorical features.
integer array-like : integer indices indicating categorical features.
- categorical_encodersdict (optional)
Encoders for the categorical columns of X, i.e. the columns of categorical dtype of a
pd.DataFrameor those given by categorical_features for annp.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
pd.DataFrame, an integer for annp.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
contrast()andordinal().- sparse_outputbool (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.
- Attributes:
- names
Methods
build_sequence(X[, anova_type])Build implied sequence of submodels based on successively including more terms.
build_submodel(X, terms)Build design on X after fitting.
fit(X[, y])Fit the encoders of each term, determining the columns of the model matrix.
fit_transform(X[, y])Fit to data, then transform it.
get_feature_names_out([input_features])Names of the columns of the model matrix.
Get metadata routing of this object.
get_params([deep])Get parameters of this ModelSpec.
set_output(*[, transform])Set output container.
set_params(**params)Set parameters of this ModelSpec.
transform(X[, y])Build design on X after fitting.
- __init__(terms=(), intercept=None, categorical_features=None, categorical_encoders=None, sparse_output=False)#
- build_sequence(X, anova_type='sequential')#
Build implied sequence of submodels based on successively including more terms.
- Parameters:
- Xarray-like
X on which columns are evaluated.
- anova_type: str
One of “sequential” or “drop”.
- Returns:
- modelsgenerator
Generator for sequence of models for ANOVA.
- build_submodel(X, terms)#
Build design on X after fitting.
- Parameters:
- Xarray-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:
- Darray-like
Design matrix created with terms
- fit(X, y=None)#
Fit the encoders of each term, determining the columns of the model matrix.
- Parameters:
- Xarray-like
X on which model matrix will be evaluated. If a
pd.DataFrameorpd.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.- yNone
Ignored. This parameter exists only for compatibility with
sklearn.pipeline.Pipeline.
- fit_transform(X, y=None, **fit_params)#
Fit to data, then transform it.
Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.
- Parameters:
- Xarray-like of shape (n_samples, n_features)
Input samples.
- yarray-like of shape (n_samples,) or (n_samples, n_outputs), default=None
Target values (None for unsupervised transformations).
- **fit_paramsdict
Additional fit parameters. Pass only if the estimator accepts additional params in its fit method.
- Returns:
- X_newndarray array of shape (n_samples, n_features_new)
Transformed array.
- get_feature_names_out(input_features=None)#
Names of the columns of the model matrix.
- Parameters:
- input_featuresNone
Ignored. This parameter exists only for compatibility with
sklearn.pipeline.Pipeline.
- Returns:
- namesnp.ndarray of str
- get_metadata_routing()#
Get metadata routing of this object.
Please check User Guide on how the routing mechanism works.
- Returns:
- routingMetadataRequest
A
MetadataRequestencapsulating routing information.
- get_params(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).
- property names#
- set_output(*, transform=None)#
Set output container.
Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.
- Parameters:
- transform{“default”, “pandas”, “polars”}, default=None
Configure output of transform and fit_transform.
“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged
Added in version 1.4: “polars” option was added.
- Returns:
- selfestimator instance
Estimator instance.
- set_params(**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.
- transform(X, y=None)#
Build design on X after fitting.
- Parameters:
- Xarray-like
- yNone
Ignored. This parameter exists only for compatibility with
sklearn.pipeline.Pipeline.
Functions#
- ISLP.models.model_spec.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
ISLP.transforms.BSplinealong with intercept.- Parameters:
- colcolumn identifier or Column
- interceptbool
Include an intercept column.
- namestr (optional)
Defaults to one derived from col.
- Returns:
- varFeature
- ISLP.models.model_spec.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.
- Xarray-like
X on which columns are evaluated.
- varFeature
Feature whose columns will be built, typically a key in column_info.
- encodersdict
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.
- fitbool (optional)
If True, then try to fit encoder. Will raise an error if encoder has already been fit.
- sparsebool (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_onlybool (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_arraybool (optional)
If True, return the columns as a 2-d np.ndarray rather than a pd.DataFrame.
- ISLP.models.model_spec.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.
- Xarray-like
X on which columns are evaluated.
- terms[Feature]
Sequence of features
- encodersdict
Dict that stores encoder of each Feature.
- sparsebool
If True, return a scipy.sparse.csr_matrix.
- order‘C’ or ‘F’
The memory layout of a dense model matrix.
- Returns:
- dfnp.ndarray, pd.DataFrame or scipy.sparse.csr_matrix
Design matrix.
- ISLP.models.model_spec.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:
- varFeature
- ISLP.models.model_spec.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.
- namestr (optional)
Defaults to str(encoder).
- encodertransform-like (optional)
Transform obeying sklearn fit/transform convention.
- Returns:
- varFeature
- ISLP.models.model_spec.fit_encoder(encoders, var, X)#
Fit an encoder if not already registered in encoders.
- Parameters:
- encodersdict
Dictionary of encoders for each feature.
- varFeature
Feature whose encoder will be fit.
- Xarray-like
X on which encoder will be fit.
- ISLP.models.model_spec.ns(col, intercept=False, name=None, **spline_args)#
Create a natural spline Feature for a given column.
Additional spline_args are passed to
NaturalSplinealong with intercept.- Parameters:
- colcolumn identifier or Column
- interceptbool
Include an intercept column.
- namestr (optional)
Defaults to one derived from col.
- Returns:
- varFeature
- ISLP.models.model_spec.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:
- varColumn
- ISLP.models.model_spec.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
ISLP.transforms.PCA.- Parameters:
- variables[column identifier, Column or Feature]
Sequence whose columns will be encoded by PCA.
- Returns:
- varFeature
- ISLP.models.model_spec.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:
- colcolumn identifier or Column
Column to transform.
- degreeint, default=1
Degree of polynomial.
- interceptbool, default=False
Include a column for intercept?
- rawbool, default=False
If False, perform a QR decomposition on the resulting matrix of powers of centered and / or scaled features.
- namestr (optional)
Defaults to one derived from col.
- Returns:
- varFeature