plotLocalEffects
Syntax
Description
plotLocalEffects(
creates a bar graph showing the local effects of the terms in the generalized additive model
Mdl
,queryPoint
)Mdl
on the prediction at the specified query point
queryPoint
.
plotLocalEffects(
specifies additional options using one or more name-value arguments. For example,
Mdl
,queryPoint
,Name,Value
)'IncludeIntercept',true
specifies to include an intercept term in the
bar graph.
returns
a bar graph object b
= plotLocalEffects(___)b
. Use b
to query or modify
Bar Properties of the bar graph after you
create it.
Examples
Plot Local Effects
Train a univariate generalized additive classification model, which contains linear terms for predictors. Classify a new observation using a memory-efficient model object. Then, interpret the prediction for a specified data instance by using the plotLocalEffects
function.
Load the ionosphere
data set. This data set has 34 predictors and 351 binary responses for radar returns, either bad ('b'
) or good ('g'
).
load ionosphere
Train a univariate GAM that identifies whether the radar return is bad ('b'
) or good ('g'
).
Mdl = fitcgam(X,Y);
Mdl
is a ClassificationGAM
model object.
Conserve memory by reducing the size of the trained model.
CMdl = compact(Mdl);
Classify the first observation of the training data, and plot the local effects of the terms in Mdl
on the prediction.
label = predict(CMdl,X(1,:))
label = 1x1 cell array
{'g'}
plotLocalEffects(CMdl,X(1,:))
The predict
function classifies the first observation X(1,:)
as 'g'
. The plotLocalEffects
function creates a horizontal bar graph that shows the local effects of the 10 most important terms on the prediction. Each local effect value shows the contribution of each term to the classification score for 'g'
, which is the logit of the posterior probability that the classification is 'g'
for the observation.
Compare Local Effects in GAMs
Train a GAM for binary classification with both linear and interaction terms for predictors. Create local effects plot using both linear and interaction terms in the model, and then create a plot using only linear terms in the model. Specify whether to include interaction terms when creating the local effects plot.
Load the ionosphere
data set. This data set has 34 predictors and 351 binary responses for radar returns, either bad ('b'
) or good ('g'
).
load ionosphere
Train a GAM using the predictors X
and class labels Y
. A recommended practice is to specify the class names. Specify to include the 10 most important interaction terms.
Mdl = fitcgam(X,Y,'ClassNames',{'b','g'},'Interactions',10);
Mdl
is a ClassificationGAM
model object.
Create local effects plots for the 10th observation. Use both the linear and interaction terms in Mdl
for the first plot, and use only the linear terms in Mdl
for the second plot. To exclude interaction terms, specify 'IncludeInteractions',false
.
t = tiledlayout(2,1); title(t,'Local Effects Plots for 10th Observation') nexttile plotLocalEffects(Mdl,X(10,:)) title('GAM with linear and interaction terms') nexttile plotLocalEffects(Mdl,X(10,:),'IncludeInteractions',false) title('GAM with only linear terms')
The plots display the 10 most important terms. Both plots include nine common terms and one uncommon term. The first plot includes the interaction term for x1
and x5
, whereas the second plot includes the linear term for x14
.
Include Intercept Term in Local Effects Plot
Train a univariate GAM for regression, which contains linear terms for predictors. Then, interpret the prediction for a specified data instance by using the plotLocalEffects
function.
Load the data set NYCHousing2015
.
load NYCHousing2015
The data set includes 10 variables with information on the sales of properties in New York City in 2015. This example uses these variables to analyze the sale prices (SALEPRICE
).
Preprocess the data set. Remove outliers, convert the datetime
array (SALEDATE
) to the month numbers, and move the response variable (SALEPRICE
) to the last column.
idx = isoutlier(NYCHousing2015.SALEPRICE); NYCHousing2015(idx,:) = []; NYCHousing2015.SALEDATE = month(NYCHousing2015.SALEDATE); NYCHousing2015 = movevars(NYCHousing2015,'SALEPRICE','After','SALEDATE');
Display the first three rows of the table.
head(NYCHousing2015,3)
BOROUGH NEIGHBORHOOD BUILDINGCLASSCATEGORY RESIDENTIALUNITS COMMERCIALUNITS LANDSQUAREFEET GROSSSQUAREFEET YEARBUILT SALEDATE SALEPRICE _______ ____________ ____________________________ ________________ _______________ ______________ _______________ _________ ________ _________ 2 {'BATHGATE'} {'01 ONE FAMILY DWELLINGS'} 1 0 4750 2619 1899 8 0 2 {'BATHGATE'} {'01 ONE FAMILY DWELLINGS'} 1 0 4750 2619 1899 8 0 2 {'BATHGATE'} {'01 ONE FAMILY DWELLINGS'} 1 1 1287 2528 1899 12 0
Train a univariate GAM for the sale prices. Specify the variables for BOROUGH
, NEIGHBORHOOD
, BUILDINGCLASSCATEGORY
, and SALEDATE
as categorical predictors.
Mdl = fitrgam(NYCHousing2015,'SALEPRICE','CategoricalPredictors',[1 2 3 9]);
Mdl
is a RegressionGAM
model object.
Display the estimated intercept (constant) term of Mdl
.
Mdl.Intercept
ans = 3.7518e+05
The intercept term value is close to the average of the response variable in a regression GAM if the training data does not include NaN
values. Compute average of the response variable.
mean(NYCHousing2015.SALEPRICE)
ans = 3.7518e+05
Predict the sale price for the first observation of the training data, and plot the local effects of the terms in Mdl
on the prediction. Specify 'IncludeIntercept',true
to include the intercept term in the plot.
yFit = predict(Mdl,NYCHousing2015(1,:))
yFit = 4.4421e+05
plotLocalEffects(Mdl,NYCHousing2015(1,:),'IncludeIntercept',true)
The predict
function predicts the sale price for the first observation as 4.4421e5
. The plotLocalEffects
function creates a horizontal bar graph that shows the local effects of the terms in Mdl
on the prediction. Each local effect value shows the contribution of each term to the predicted sale price.
Input Arguments
Mdl
— Generalized additive model
ClassificationGAM
model object | CompactClassificationGAM
model object | RegressionGAM
model object | CompactRegressionGAM
model object
Generalized additive model, specified as a ClassificationGAM
, CompactClassificationGAM
, RegressionGAM
,
or CompactRegressionGAM
model object.
queryPoint
— Query point
row vector of numeric values | single-row table
Query point at which plotLocalEffects
plots the local effects,
specified as a row vector of numeric values or a single-row table.
For a row vector of numeric values:
The variables that makes up the columns of
queryPoint
must have the same order as the predictor variables that trainedMdl
.If you trained
Mdl
using a table (for example,Tbl
), thenqueryPoint
can be a numeric matrix ifTbl
contains all numeric variables.
For a single-row table:
If you trained
Mdl
using a table (for example,Tbl
), then all predictor variables inqueryPoint
must have the same variable names and data types as those inTbl
. However, the column order ofqueryPoint
does not need to correspond to the column order ofTbl
.If you trained
Mdl
using a numeric matrix, then the predictor names inMdl.PredictorNames
and the corresponding predictor variable names inqueryPoint
must be the same. To specify predictor names during training, use the'PredictorNames'
name-value argument. All predictor variables inqueryPoint
must be numeric vectors.queryPoint
can contain additional variables (response variables, observation weights, and so on), butplotLocalEffects
ignores them.plotLocalEffects
does not support multicolumn variables or cell arrays other than cell arrays of character vectors.
Data Types: single
| double
| table
ax
— Target axes
Axes
object
Since R2024a
Target axes, specified as an Axes object. If you do not specify the axes, then
plotLocalEffects
uses the current axes (gca
).
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: plotLocalEffects(Mdl,queryPoint,'IncludeInteractions',false,'NumTerms',5)
specifies to create a bar plot containing the five most important linear terms for predictors
in Mdl
excluding the interaction terms in
Mdl
.
IncludeInteractions
— Flag to include interaction terms
true
| false
Flag to include interaction terms of the model in the plot, specified as
true
or false
.
The default 'IncludeInteractions'
value is
true
if Mdl
contains interaction terms. The
value must be false
if the model does not contain interaction
terms.
Example: 'IncludeInteractions',false
Data Types: logical
IncludeIntercept
— Flag to include intercept term
false
(default) | true
Flag to include an intercept term of the model in the plot, specified as
true
or false
.
Example: 'IncludeIntercept',true
Data Types: logical
NumTerms
— Number of terms to plot
min(M,10)
where M
is the
number of terms in Mdl
(default) | positive integer scalar
Number of terms to plot, specified as a positive integer scalar.
plotLocalEffects
plots the specified number of terms with the
highest absolute local effect values.
Example: 'NumTerms',5
specifies to plot the five most important
terms. plotLocalEffects
determines the order of importance by using
the absolute local effect values.
Data Types: single
| double
Version History
Introduced in R2021aR2024a: Specify target axes
Specify the target axes for the plot by using the ax
input
argument.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)