The ML.ADVANCED_WEIGHTS function

This document describes theML.ADVANCED_WEIGHTS function, which lets yousee the underlying weights that a linear or binary logistic regression modeluses during prediction, along with the associated p-values andstandard errors for that weight.ML.ADVANCED_WEIGHTS is an extended version ofML.WEIGHTS for linear and binary logistic regression models.

Usage requirements

You can only useML.ADVANCED_WEIGHTS on linear and binary logistic regressionmodels that are trained with the following option settings:

• TheCALCULATE_P_VALUESvalue isTRUE.
• TheCATEGORY_ENCODING_METHODvalue isDUMMY_ENCODING.
• TheL1_REGvalue is0.

It's common to require standard errors or p-values for either the regressioncoefficients or other estimated quantities for these penalized regressionmethods. In principle, such standard errors can be calculated—for example,using the bootstrap. In practice, this calculation isn't done for reasons thatthe authors of theR packageexplain as follows:

Multiclass logistic regression models aren't supported.

Syntax

ML.ADVANCED_WEIGHTS(  MODEL `PROJECT_ID.DATASET.MODEL`,  STRUCT(    [STANDARDIZE AS standardize]))

Arguments

ML.ADVANCED_WEIGHTS takes the following arguments:

• PROJECT_ID: your project ID.
• DATASET: the BigQuery dataset thatcontains the model.
• MODEL: the name of the model.
• STANDARDIZE: aBOOL value that specifies whether themodel weights should be standardized to assume that all features have a meanof zero and a standard deviation of one. Standardizing the weights allows theabsolute magnitude of the weights to be compared to each other. The defaultvalue isFALSE.

Output

ML.ADVANCED_WEIGHTS returns the following columns:

• processed_input: aSTRING value that contains the name of thefeature column. The value of this column is the name of the feature columnthat's provided in thequery_statement clauseused during model training. If the feature is non-numeric, then there aremultiple rows with the sameprocessed_input value, one for each category ofthe feature.
• category: aSTRING value that contains the category name if the columnidentified in theprocessed_input value is non-numeric. Returns aNULLvalue for numeric columns.
• weight: aFLOAT64 value that contains theweightof each feature.
• standard_error: aFLOAT64 value that contains thestandard error of the weight.

• p_value: aFLOAT64 value that contains thep-value that was tested againstthe null hypothesis. The p-value for feature $j$ is calculated using thefollowing formula:

  $$ p(j) = 2 * (1 - stats.norm.cdf(abs(\hat\beta_j), loc=0, scale=\sigma_j)) $$

  such that $\hat\beta_j$ is the weight of feature $j$ after trainingand $\sigma_j$ is its standard error.

If theTRANSFORM clausewas used in theCREATE MODEL statement that created the model,ML.ADVANCED_WEIGHTS outputs the weights of theTRANSFORM outputfeatures. The weights are denormalized by default, with the option to getnormalized weights, exactly like models that are created withoutTRANSFORM.

Permissions

You must have thebigquery.models.create andbigquery.models.getDataIdentity and Access Management (IAM) permissionsin order to runML.ADVANCED_WEIGHTS.

Limitations

The total cardinality of training features must be less than 1,000. Thislimitation is the result of thelimitations of computing p-values and standard errorwhen you set theCALCULATE_P_VALUES option toTRUE when trainingthe model.

Examples

The following examples demonstrateML.ADVANCED_WEIGHTS with and withoutstandardization.

Without standardization

The following example retrieves weight information frommymodel inmydataset where the dataset is in your default project.

The query returns the weights associated with each one-hot encoded category forthe input columninput_col.

SELECT*FROMML.ADVANCED_WEIGHTS(MODEL`mydataset.mymodel`,STRUCT(FALSEASstandardize))

SELECT*FROMML.ADVANCED_WEIGHTS(MODEL`mydataset.mymodel`,STRUCT(TRUEASstandardize))

• For information about Explainable AI, seeBigQuery Explainable AI overview.
• For more information about supported SQL statements and functions for MLmodels, seeEnd-to-end user journeys for ML models.