compute partial dependence

since r2020b

syntax

pd = partialdependence(regressionmdl,vars)

pd = partialdependence(classificationmdl,vars,labels)

pd = partialdependence(___,data)

pd = partialdependence(fun,vars,data)

pd = partialdependence(___,name,value)

[pd,x,y] = partialdependence(___)

description

example

pd = partialdependence(regressionmdl,vars) computes the partial dependence pd between the predictor variables listed in vars and the responses predicted by using the regression model regressionmdl, which contains predictor data.

example

pd = partialdependence(classificationmdl,vars,labels) computes the partial dependence pd between the predictor variables listed in vars and the scores for the classes specified in labels by using the classification model classificationmdl, which contains predictor data.

example

pd = partialdependence(___,data) uses new predictor data in data. you can specify data in addition to any of the input argument combinations in the previous syntaxes.

example

pd = partialdependence(fun,vars,data) computes the partial dependence between the predictor variables listed in vars and the outputs returned by the custom model fun, using the predictor data data.

example

pd = partialdependence(___,name,value) uses additional options specified by one or more name-value arguments. for example, if you specify "useparallel","true", the partialdependence function uses parallel computing to perform the partial dependence calculations.

[pd,x,y] = partialdependence(___) also returns x and y, which contain the query points of the first and second predictor variables in vars, respectively. if you specify one variable in vars, then partialdependence returns an empty matrix ([]) for y.

examples

compute and plot partial dependence on one variable

train a naive bayes classification model with the fisheriris data set, and compute partial dependence values that show the relationship between the predictor variable and the predicted scores (posterior probabilities) for multiple classes.

load the fisheriris data set, which contains species (species) and measurements (meas) on sepal length, sepal width, petal length, and petal width for 150 iris specimens. the data set contains 50 specimens from each of three species: setosa, versicolor, and virginica.

load fisheriris

train a naive bayes classification model with species as the response and meas as predictors.

mdl = fitcnb(meas,species,"predictornames",["sepal length","sepal width","petal length","petal width"]);

compute partial dependence values on the third predictor variable (petal length) of the scores predicted by mdl for all three classes of species. specify the class labels by using the classnames property of mdl.

[pd,x] = partialdependence(mdl,3,mdl.classnames);

pd contains the partial dependence values for the query points x. you can plot the computed partial dependence values by using plotting functions such as and . plot pd against x by using the bar function.

bar(x,pd)
legend(mdl.classnames)
xlabel("petal length")
ylabel("scores")
title("partial dependence plot")

figure contains an axes object. the axes object with title partial dependence plot, xlabel petal length, ylabel scores contains 3 objects of type bar. these objects represent setosa, versicolor, virginica.

according to this model, the probability of virginica increases with petal length. the probability of setosa is about 0.33, from where petal length is 0 to around 2.5, and then the probability drops to almost 0.

alternatively, you can use the plotpartialdependence function to compute and plot partial dependence values.

plotpartialdependence(mdl,3,mdl.classnames)

figure contains an axes object. the axes object with title partial dependence plot, xlabel petal length, ylabel scores contains 3 objects of type line. these objects represent setosa, versicolor, virginica.

compute and plot partial dependence on two variables for multiple classes

train an ensemble of classification models and compute partial dependence values on two variables for multiple classes. then plot the partial dependence values for each class.

load the census1994 data set, which contains us yearly salary data, categorized as <=50k or >50k, and several demographic variables.

load census1994

extract a subset of variables to analyze from the table adultdata.

x = adultdata(1:500,["age","workclass","education_num","marital_status","race", ...
   "sex","capital_gain","capital_loss","hours_per_week","salary"]);

train a random forest of classification trees by using fitcensemble and specifying method as "bag". for reproducibility, use a template of trees created by using templatetree with the reproducible option.

rng("default")
t = templatetree("reproducible",true);
mdl = fitcensemble(x,"salary","method","bag","learners",t);

inspect the class names in mdl.

mdl.classnames

ans = 2x1 categorical
     <=50k 
     >50k

compute partial dependence values of the scores on the predictors age and education_num for both classes (<=50k and >50k). specify the number of observations to sample as 100.

[pd,x,y] = partialdependence(mdl,["age","education_num"],mdl.classnames,"numobservationstosample",100);

create a surface plot of the partial dependence values for the first class (<=50k) by using the function.

figure
surf(x,y,squeeze(pd(1,:,:)))
xlabel("age")
ylabel("education\_num")
zlabel("score of class <=50k")
title("partial dependence plot")
view([130 30]) % modify the viewing angle

figure contains an axes object. the axes object with title partial dependence plot, xlabel age, ylabel e d u c a t i o n _ n u m contains an object of type surface.

create a surface plot of the partial dependence values for the second class (>50k).

figure
surf(x,y,squeeze(pd(2,:,:)))
xlabel("age")
ylabel("education\_num")
zlabel("score of class >50k")
title("partial dependence plot")
view([130 30]) % modify the viewing angle

figure contains an axes object. the axes object with title partial dependence plot, xlabel age, ylabel e d u c a t i o n _ n u m contains an object of type surface.

the two plots show different partial dependence patterns depending on the class.

compute partial dependence for noisy data

load the carbig sample data set.

load carbig

the vectors displacement, cylinders, and model_year contain data for car engine displacement, number of engine cylinders, and year the car was manufactured, respectively.

fit a multinomial regression model using displacement and cylinders as predictor variables and model_year as the response.

predvars = [displacement,cylinders];
mdl = fitmnr(predvars,model_year,predictornames=["displacement","cylinders"]);

create a vector of noisy predictor data from the predictor variables by using the function.

data = predvars(1:10:end,:);
rng("default")
rows = length(data);
data = data   10*rand([rows,2]);

calculate the partial dependence of the response category probability corresponding to cars manufactured in 1980 on displacement. use the noisy predictor data to calculate the partial dependence.

[pd,x,~] = partialdependence(mdl,"displacement",80,data)

pd = 1×100
    0.0030    0.0031    0.0031    0.0032    0.0032    0.0033    0.0033    0.0033    0.0034    0.0034    0.0035    0.0035    0.0036    0.0036    0.0036    0.0037    0.0037    0.0037    0.0038    0.0038    0.0038    0.0039    0.0039    0.0039    0.0039    0.0039    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0040    0.0039    0.0039    0.0039    0.0039    0.0038    0.0038    0.0038    0.0037    0.0037    0.0036

the output shows the calculated values for the partial dependence of the category probability on displacement. because displacement is a continuous variable, the partialdependence function calculates the partial dependence at 100 equally spaced query points x.

plot the partial dependence using plotpartialdependence.

plotpartialdependence(mdl,"displacement",80,data)

the plot shows that when displacement increases from approximately 70 to approximately 180, the probability of a car being manufactured in 1980 increases. as displacement continues to increase, the probability of a car being manufactured in 1980 decreases.

compute and plot partial dependence on multiple variables for regression

train a support vector machine (svm) regression model using the carsmall data set, and compute the partial dependence on two predictor variables. then, create a figure that shows the partial dependence on the two variables along with the histogram on each variable.

load the carsmall data set.

load carsmall

create a table that contains weight, cylinders, displacement, and horsepower.

tbl = table(weight,cylinders,displacement,horsepower);

train an svm regression model using the predictor variables in tbl and the response variable mpg. use a gaussian kernel function with an automatic kernel scale.

mdl = fitrsvm(tbl,mpg,"responsename","mpg", ...
    "categoricalpredictors","cylinders","standardize",true, ...
    "kernelfunction","gaussian","kernelscale","auto");

compute the partial dependence of the predicted response (mpg) on the predictor variables weight and horsepower. specify query points to compute the partial dependence by using the querypoints name-value argument.

numpoints = 10;
ptx = linspace(min(weight),max(weight),numpoints)';
pty = linspace(min(horsepower),max(horsepower),numpoints)';
[pd,x,y] = partialdependence(mdl,["weight","horsepower"],"querypoints",[ptx pty]);

create a figure that contains a 5-by-5 tiled chart layout. plot the partial dependence on the two variables by using the function. then draw the histogram for each variable by using the function. specify the edges of the histograms so that the centers of the histogram bars align with the query points. change the axes properties to align the axes of the plots.

t = tiledlayout(5,5,"tilespacing","compact");
ax1 = nexttile(2,[4,4]);
imagesc(x,y,pd)
title("partial dependence plot")
colorbar("eastoutside")
ax1.ydir = "normal";
ax2 = nexttile(22,[1,4]);
dx = diff(ptx(1:2));
edgex = [ptx-dx/2;ptx(end) dx];
histogram(weight,edgex);
xlabel("weight")
xlim(ax1.xlim);
ax3 = nexttile(1,[4,1]);
dy = diff(pty(1:2));
edgey = [pty-dy/2;pty(end) dy];
histogram(horsepower,edgey)
xlabel("horsepower")
xlim(ax1.ylim);
ax3.xdir = "reverse";
camroll(-90)

figure contains 3 axes objects. axes object 1 with title partial dependence plot contains an object of type image. axes object 2 with xlabel weight contains an object of type histogram. axes object 3 with xlabel horsepower contains an object of type histogram.

each element of pd specifies the color for one pixel of the image plot. the histograms aligned with the axes of the image show the distribution of the predictors.

specify model using function handle

compute the partial dependence of label scores on predictor variables for a semisupervisedselftrainingmodel object. you cannot pass a semisupervisedselftrainingmodel object directly to the partialdependence function. instead, define a custom function that returns label scores for the object, and then pass the function to partialdependence.

randomly generate 15 observations of labeled data, with five observations in each of three classes.

rng("default") % for reproducibility
labeledx = [randn(5,2)*0.25   ones(5,2);
            randn(5,2)*0.25 - ones(5,2);
            randn(5,2)*0.5];
y = [ones(5,1); ones(5,1)*2; ones(5,1)*3];

randomly generate 300 additional observations of unlabeled data, with 100 observations per class.

unlabeledx = [randn(100,2)*0.25   ones(100,2);
              randn(100,2)*0.25 - ones(100,2);
              randn(100,2)*0.5];

fit labels to the unlabeled data by using a semi-supervised self-training method. the function fitsemiself returns a semisupervisedselftrainingmodel object.

mdl = fitsemiself(labeledx,y,unlabeledx);

define the custom function mylabelscores, which returns label scores computed by the predict function of semisupervisedselftrainingmodel; the custom function definition appears at the end of this example.

compute the partial dependence of the scores for unlabeledx on each variable for all classes. partialdependence accepts a custom model in the form of a function handle. the function represented by the function handle must accept predictor data and return a column vector or matrix with one row for each observation. specify the custom model as @(x)mylabelscores(mdl,x) so that the custom function uses the trained model mdl and accepts predictor data.

[pd1,x1] = partialdependence(@(x)mylabelscores(mdl,x),1,unlabeledx);
[pd2,x2] = partialdependence(@(x)mylabelscores(mdl,x),2,unlabeledx);

you can plot the computed partial dependence values by using plotting functions such as and . alternatively, you can use the plotpartialdependence function to compute and plot partial dependence values.

create partial dependence plots for the first variable and all classes.

plotpartialdependence(@(x)mylabelscores(mdl,x),1,unlabeledx)
xlabel("1st variable of unlabeledx")
ylabel("scores")
legend("class 1","class 2","class 3")

figure contains an axes object. the axes object with title partial dependence plot, xlabel 1st variable of unlabeledx, ylabel scores contains 3 objects of type line. these objects represent class 1, class 2, class 3.

custom function mylabelscores

function scores = mylabelscores(mdl,x)
[~,scores] = predict(mdl,x);
end

input arguments

`regressionmdl` — regression model
regression model object

regression model, specified as a full or compact regression model object, as given in the following tables of supported models.

model	full or compact model object
generalized linear model	,
generalized linear mixed-effect model
linear regression	,
linear mixed-effect model
nonlinear regression
ensemble of regression models	, `regressionbaggedensemble`,
generalized additive model (gam)	,
gaussian process regression	`regressiongp`,
gaussian kernel regression model using random feature expansion
linear regression for high-dimensional data	`regressionlinear`
neural network regression model	,
support vector machine (svm) regression	`regressionsvm`, `compactregressionsvm`
regression tree	`regressiontree`, `compactregressiontree`
bootstrap aggregation for ensemble of decision trees	`treebagger`,

if regressionmdl is a model object that does not contain predictor data (for example, a compact model), you must provide the input argument data.

partialdependence does not support a model object trained with a sparse matrix. when you train a model, use a full numeric matrix or table for predictor data where rows correspond to individual observations.

`classificationmdl` — classification model
classification model object

classification model, specified as a full or compact classification model object, as given in the following table of supported models.

model	full or compact model object
discriminant analysis classifier	,
multiclass model for support vector machines or other classifiers	`classificationecoc`, `compactclassificationecoc`
ensemble of learners for classification	, ,
generalized additive model (gam)	,
gaussian kernel classification model using random feature expansion	`classificationkernel`
k-nearest neighbor classifier	`classificationknn`
linear classification model	`classificationlinear`
multiclass naive bayes model	, `compactclassificationnaivebayes`
neural network classifier	,
support vector machine (svm) classifier for one-class and binary classification	`classificationsvm`, `compactclassificationsvm`
binary decision tree for multiclass classification	, `compactclassificationtree`
bagged ensemble of decision trees	`treebagger`,
multinomial regression model

if classificationmdl is a model object that does not contain predictor data (for example, a compact model), you must provide the input argument data.

`fun` — custom model
function handle

custom model, specified as a function handle. the function handle fun must represent a function that accepts the predictor data data and returns an output in the form of a column vector or matrix. each row of the output must correspond to each observation (row) in the predictor data.

by default, partialdependence uses all output columns of fun for the partial dependence computation. you can specify which output columns to use by setting the outputcolumns name-value argument.

if the predictor data (data) is in a table, partialdependence assumes that a variable is categorical if it is a logical vector, categorical vector, character array, string array, or cell array of character vectors. if the predictor data is a matrix, partialdependence assumes that all predictors are continuous. to identify any other predictors as categorical predictors, specify them by using the categoricalpredictors name-value argument.

data types: function_handle

`vars` — predictor variables
vector of positive integers | character vector | string scalar | string array | cell array of character vectors

predictor variables, specified as a vector of positive integers, character vector, string scalar, string array, or cell array of character vectors. you can specify one or two predictor variables, as shown in the following tables.

one predictor variable

value	description
positive integer	index value corresponding to the column of the predictor data.
character vector or string scalar	name of the predictor variable. the name must match the entry in the `predictornames` property for `regressionmdl` and `classificationmdl` or the variable name of `data` in a table for a custom model `fun`.

two predictor variables

value	description
vector of two positive integers	index values corresponding to the columns of the predictor data.
string array or cell array of character vectors	names of the predictor variables. each element in the array is the name of a predictor variable. the names must match the entries in the `predictornames` property for `regressionmdl` and `classificationmdl` or the variable names of `data` in a table for a custom model `fun`.

example: ["x1","x3"]

data types: single | double | char | string | cell

`labels` — class labels
categorical array | character array | logical vector | numeric vector | cell array of character vectors

class labels, specified as a categorical or character array, logical or numeric vector, or cell array of character vectors. the values and data types in labels must match those of the class names in the classnames property of classificationmdl (classificationmdl.classnames).

you can specify one or multiple class labels.

this argument is valid only when you specify a classification model object classificationmdl.

example: ["red","blue"]

example: classificationmdl.classnames([1 3]) specifies labels as the first and third classes in classificationmdl.

`data` — predictor data
numeric matrix | table

predictor data, specified as a numeric matrix or table. each row of data corresponds to one observation, and each column corresponds to one variable.

for both a regression model (regressionmdl) and a classification model (classificationmdl), data must be consistent with the predictor data that trained the model, stored in either the x or variables property.

if you trained the model using a numeric matrix, then data must be a numeric matrix. the variables that make up the columns of data must have the same number and order as the predictor variables that trained the model.
if you trained the model using a table (for example, tbl), then data must be a table. all predictor variables in data must have the same variable names and data types as the names and types in tbl. however, the column order of data does not need to correspond to the column order of tbl.
data must not be sparse.

if you specify a regression or classification model that does not contain predictor data, you must provide data. if the model is a full model object that contains predictor data and you specify the data argument, then partialdependence ignores the predictor data in the model and uses data only.

if you specify a custom model fun, you must provide data.

data types: single | double | table

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: partialdependence(mdl,vars,data,"numobservationstosample",100,"useparallel",true) computes the partial dependence values by using 100 sampled observations in data and executing for-loop iterations in parallel.

`includeinteractions` — flag to include interaction terms
`true` | `false`

flag to include interaction terms of the generalized additive model (gam) in the partial dependence computation, specified as true or false. this argument is valid only for a gam. that is, you can specify this argument only when regressionmdl is or , or classificationmdl is or .

the default includeinteractions value is true if the model 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
`true` (default) | `false`

flag to include an intercept term of the generalized additive model (gam) in the partial dependence computation, specified as true or false. this argument is valid only for a gam. that is, you can specify this argument only when regressionmdl is or , or classificationmdl is or .

example: "includeintercept",false

data types: logical

`numobservationstosample` — number of observations to sample
number of total observations (default) | positive integer

number of observations to sample, specified as a positive integer. the default value is the number of total observations in data or the model (regressionmdl or classificationmdl). if you specify a value larger than the number of total observations, then partialdependence uses all observations.

partialdependence samples observations without replacement by using the function and uses the sampled observations to compute partial dependence.

example: "numobservationstosample",100

data types: single | double

`querypoints` — points to compute partial dependence
numeric column vector | numeric two-column matrix | cell array of two numeric column vectors

points to compute partial dependence for numeric predictors, specified as a numeric column vector, a numeric two-column matrix, or a cell array of two numeric column vectors.

if you select one predictor variable in vars, use a numeric column vector.
if you select two predictor variables in vars:
- use a numeric two-column matrix to specify the same number of points for each predictor variable.
- use a cell array of two numeric column vectors to specify a different number of points for each predictor variable.

the default value is a numeric column vector or a numeric two-column matrix, depending on the number of selected predictor variables. each column contains 100 evenly spaced points between the minimum and maximum values of the sampled observations for the corresponding predictor variable.

you cannot modify querypoints for a categorical variable. the partialdependence function uses all categorical values in the selected variable.

if you select one numeric variable and one categorical variable, you can specify querypoints for a numeric variable by using a cell array consisting of a numeric column vector and an empty array.

example: "querypoints",{pt,[]}

data types: single | double | cell

`useparallel` — flag to run in parallel
`false` (default) | `true`

flag to run in parallel, specified as true or false. if you specify "useparallel",true, the partialdependence function executes for-loop iterations by using when predicting responses or scores for each observation and averaging them. the loop runs in parallel when you have parallel computing toolbox™.

example: "useparallel",true

data types: logical

`categoricalpredictors` — categorical predictors list for custom model
vector of positive integers | logical vector | character matrix | string array | cell array of character vectors | `"all"`

categorical predictors list for the custom model fun, specified as one of the values in this table.

value	description
vector of positive integers	each entry in the vector is an index value indicating that the corresponding predictor is categorical. the index values are between 1 and `p`, where `p` is the number of variables in `data`.
logical vector	a `true` entry means that the corresponding predictor is categorical. the length of the vector is `p`.
character matrix	each row of the matrix is the name of a predictor variable. the names must match the variable names of the predictor data `data` in a table. pad the names with extra blanks so each row of the character matrix has the same length.
string array or cell array of character vectors	each element in the array is the name of a predictor variable. the names must match the variable names of the predictor data `data` in a table.
`"all"`	all predictors are categorical.

by default, if the predictor data data is in a table, partialdependence assumes that a variable is categorical if it is a logical vector, categorical vector, character array, string array, or cell array of character vectors. if the predictor data is a matrix, partialdependence assumes that all predictors are continuous. to identify any other predictors as categorical predictors, specify them by using the categoricalpredictors name-value argument.

this argument is valid only when you specify a custom model by using fun.

example: "categoricalpredictors","all"

`outputcolumns` — output columns of custom model
`"all"` (default) | vector of positive integers | logical vector

output columns of the custom model fun to use for the partial dependence computation, specified as one of the values in this table.

value	description
vector of positive integers	each entry in the vector is an index value indicating that `partialdependence` uses the corresponding output column for the partial dependence computation. the index values are between 1 and `q`, where `q` is the number of columns in the output matrix returned by the custom model `fun`.
logical vector	a `true` entry means that `partialdependence` uses the corresponding output column for the partial dependence computation. the length of the vector is `q`.
`"all"`	`partialdependence` uses all output columns for the partial dependence computation.

this argument is valid only when you specify a custom model by using fun.

example: "outputcolumns",[1 2]

data types: single | double | logical | char | string

output arguments

`pd` — partial dependence values
numeric array

partial dependence values, returned as a numeric array.

the dimension of pd depends on the type of model (regression, classification or custom), number of variables specified in vars, number of classes specified in labels (classification model only), and number of columns specified in outputcolumns (custom model only).

for a regression model (regressionmdl), the following conditions apply:

if you specify two variables in vars, pd is a numy-by-numx matrix, where numy and numx are the number of query points of the second and first variables in vars, respectively. the value in pd(i,j) is the partial dependence value of the query point corresponding to y(i) and x(j). y(i) is the ith query point of the second predictor variable, and x(j) is the jth query point of the first predictor variable.
if you specify one variable in vars, pd is a 1-by-numx vector.

for a classification model (classificationmdl), the following conditions apply:

if you specify two variables in vars, pd is a num-by-numy-by-numx array, where num is the number of class labels in labels. the value in pd(i,j,k) is the partial dependence value of the query point y(j) and x(k) for the ith class label in labels.
if you specify one variable in vars, pd is a num-by-numx matrix.
if you specify one class in labels, pd is a numy-by-numx matrix.
if you specify one variable and one class, pd is a 1-by-numx vector.

for a custom model (fun), the following conditions apply:

if you specify two variables in vars, pd is a num-by-numy-by-numx array, where num is the number of output columns in outputcolumns. the value in pd(i,j,k) is the partial dependence value of the query point y(j) and x(k) for the ith column in outputcolumns.
if you specify one variable in vars, pd is a num-by-numx matrix.
if you specify one column in outputcolumns, pd is a numy-by-numx matrix.
if you specify one variable and one column, pd is a 1-by-numx vector.

`x` — query points of first predictor variable
numeric column vector | categorical column vector

query points of the first predictor variable in vars, returned as a numeric or categorical column vector.

if the predictor variable is numeric, then you can specify the query points by using the querypoints name-value argument.

data types: single | double | categorical

`y` — query points of second predictor variable
numeric column vector | categorical column vector | `[]`

query points of the second predictor variable in vars, returned as a numeric or categorical column vector. this output argument is empty ([]) if you specify only one variable in vars.

if the predictor variable is numeric, then you can specify the query points by using the querypoints name-value argument.

data types: single | double | categorical

more about

partial dependence for regression models

partial dependence represents the relationships between predictor variables and predicted responses in a trained regression model. partialdependence computes the partial dependence of predicted responses on a subset of predictor variables by marginalizing over the other variables.

consider partial dependence on a subset x^s of the whole predictor variable set x = {x₁, x₂, …, x_m}. a subset x^s includes either one variable or two variables: x^s = {x_s1} or x^s = {x_s1, x_s2}. let x^c be the complementary set of x^s in x. a predicted response f(x) depends on all variables in x:

f(x) = f(x^s, x^c).

the partial dependence of predicted responses on x^s is defined by the expectation of predicted responses with respect to x^c:

$f^{s} (x^{s}) = e_{c} [f (x^{s}, x^{c})] = \int f (x^{s}, x^{c}) p_{c} (x^{c}) d x^{c},$

where p_c(x^c) is the marginal probability of x^c, that is, $p_{c} (x^{c}) \approx \int p (x^{s}, x^{c}) d x^{s}$ . assuming that each observation is equally likely, and the dependence between x^s and x^c and the interactions of x^s and x^c in responses is not strong, partialdependence estimates the partial dependence by using observed predictor data as follows:

f^{s} (x^{s}) \approx \frac{1}{n} \sum_{i = 1}^{n} f (x^{s}, x_{i}^{c}),

(1)

where n is the number of observations and x_i = (x_i^s, x_i^c) is the ith observation.

when you call the partialdependence function, you can specify a trained model (f(·)) and select variables (x^s) by using the input arguments regressionmdl and vars, respectively. partialdependence computes the partial dependence at 100 evenly spaced points of x^s or the points that you specify by using the querypoints name-value argument. you can specify the number (n) of observations to sample from given predictor data by using the numobservationstosample name-value argument.

partial dependence classification models

in the case of classification models, partialdependence computes the partial dependence in the same way as for regression models, with one exception: instead of using the predicted responses from the model, the function uses the predicted scores for the classes specified in labels.

weighted traversal algorithm

the weighted traversal algorithm is a method to estimate partial dependence for a tree-based model. the estimated partial dependence is the weighted average of response or score values corresponding to the leaf nodes visited during the tree traversal.

let x^s be a subset of the whole variable set x and x^c be the complementary set of x^s in x. for each x^s value to compute partial dependence, the algorithm traverses a tree from the root (beginning) node down to leaf (terminal) nodes and finds the weights of leaf nodes. the traversal starts by assigning a weight value of one at the root node. if a node splits by x^s, the algorithm traverses to the appropriate child node depending on the x^s value. the weight of the child node becomes the same value as its parent node. if a node splits by x^c, the algorithm traverses to both child nodes. the weight of each child node becomes a value of its parent node multiplied by the fraction of observations corresponding to each child node. after completing the tree traversal, the algorithm computes the weighted average by using the assigned weights.

for an ensemble of bagged trees, the estimated partial dependence is an average of the weighted averages over the individual trees.

algorithms

for both a regression model (regressionmdl) and a classification model (classificationmdl), partialdependence uses a predict function to predict responses or scores. partialdependence chooses the proper predict function according to the model and runs predict with its default settings. for details about each predict function, see the predict functions in the following two tables. if the specified model is a tree-based model (not including a boosted ensemble of trees), then partialdependence uses the weighted traversal algorithm instead of the predict function. for details, see .

regression model object

model type	full or compact regression model object	function to predict responses
bootstrap aggregation for ensemble of decision trees
bootstrap aggregation for ensemble of decision trees	`treebagger`
ensemble of regression models	, `regressionbaggedensemble`,
gaussian kernel regression model using random feature expansion
gaussian process regression	`regressiongp`,
generalized additive model	,
generalized linear mixed-effect model
generalized linear model	,
linear mixed-effect model
linear regression	,
linear regression for high-dimensional data	`regressionlinear`
neural network regression model	,
nonlinear regression
regression tree	`regressiontree`, `compactregressiontree`
support vector machine	`regressionsvm`, `compactregressionsvm`

classification model object

model type	full or compact classification model object	function to predict labels and scores
discriminant analysis classifier	,
multiclass model for support vector machines or other classifiers	`classificationecoc`, `compactclassificationecoc`	`predict`
ensemble of learners for classification	, ,
gaussian kernel classification model using random feature expansion	`classificationkernel`
generalized additive model	,
k-nearest neighbor model	`classificationknn`
linear classification model	`classificationlinear`
naive bayes model	, `compactclassificationnaivebayes`
neural network classifier	,
support vector machine for one-class and binary classification	`classificationsvm`, `compactclassificationsvm`	`predict`
binary decision tree for multiclass classification	, `compactclassificationtree`
bagged ensemble of decision trees	`treebagger`,

alternative functionality

plotpartialdependence computes and plots partial dependence values. the function can also create individual conditional expectation (ice) plots.

references

[1] friedman, jerome. h. “greedy function approximation: a gradient boosting machine.” the annals of statistics 29, no. 5 (2001): 1189-1232.

[2] hastie, trevor, robert tibshirani, and jerome friedman. the elements of statistical learning. new york, ny: springer new york, 2009.

extended capabilities

automatic parallel support
accelerate code by automatically running computation in parallel using parallel computing toolbox™.

to run in parallel, set the useparallel name-value argument to true in the call to this function.

for more general information about parallel computing, see (parallel computing toolbox).

gpu arrays
accelerate code by running on a graphics processing unit (gpu) using parallel computing toolbox™.

usage notes and limitations:

this function fully supports gpu arrays for the following regression models:
- and objects
- and objects
- regressionsvm and compactregressionsvm objects

this function supports gpu arrays with limitations for the regression and classification models described in this table.

full or compact model object	limitations
`classificationecoc` or `compactclassificationecoc`	surrogate splits are not supported for decision tree learners. for knn learners, you cannot set the following options to the values shown: `"nsmethod","kdtree"` `"distance"`,function handle `"includeties",true`
or	surrogate splits are not supported for decision tree learners.
`classificationknn`	you cannot set the following options to the values shown: `"nsmethod","kdtree"` `"distance"`,function handle `"includeties",true`
`classificationsvm` or `compactclassificationsvm`	one-class classification is not supported `data` cannot contain infinite values name-value arguments have the following limitations: you cannot specify the `kernelfunction` name-value argument as a custom kernel function. you can specify the `solver` name-value argument as "`smo`" only. you cannot specify the `outlierfraction` or `shrinkageperiod` name-value argument.
or `compactclassificationtree`	surrogate splits are not supported for decision trees.
or	surrogate splits are not supported for decision tree learners.
`regressiontree` or `compactregressiontree`	surrogate splits are not supported for decision trees.

this function fully supports gpu arrays for a custom function if the custom function supports gpu arrays.

for more information, see run matlab functions on a gpu (parallel computing toolbox).

version history

introduced in r2020b

r2023a: gpu array support for `regressionsvm` and `compactregressionsvm` models

starting in r2023a, partialdependence fully supports gpu arrays for regressionsvm and compactregressionsvm models.

compute partial dependence -凯发k8网页登录

syntax

description

examples

compute and plot partial dependence on one variable

compute and plot partial dependence on two variables for multiple classes

compute partial dependence for noisy data

compute and plot partial dependence on multiple variables for regression

specify model using function handle

input arguments

regressionmdl — regression model regression model object

classificationmdl — classification model classification model object

fun — custom model function handle

vars — predictor variables vector of positive integers | character vector | string scalar | string array | cell array of character vectors

labels — class labels categorical array | character array | logical vector | numeric vector | cell array of character vectors

data — predictor data numeric matrix | table

name-value arguments

includeinteractions — flag to include interaction terms true | false

includeintercept — flag to include intercept term true (default) | false

numobservationstosample — number of observations to sample number of total observations (default) | positive integer

querypoints — points to compute partial dependence numeric column vector | numeric two-column matrix | cell array of two numeric column vectors

useparallel — flag to run in parallel false (default) | true

categoricalpredictors — categorical predictors list for custom model vector of positive integers | logical vector | character matrix | string array | cell array of character vectors | "all"

outputcolumns — output columns of custom model "all" (default) | vector of positive integers | logical vector

output arguments

pd — partial dependence values numeric array

x — query points of first predictor variable numeric column vector | categorical column vector

y — query points of second predictor variable numeric column vector | categorical column vector | []

more about

partial dependence for regression models

partial dependence classification models

weighted traversal algorithm

algorithms

alternative functionality

references

extended capabilities

automatic parallel support accelerate code by automatically running computation in parallel using parallel computing toolbox™.

gpu arrays accelerate code by running on a graphics processing unit (gpu) using parallel computing toolbox™.

version history

r2023a: gpu array support for regressionsvm and compactregressionsvm models

see also

topics

wechat

`regressionmdl` — regression model
regression model object

`classificationmdl` — classification model
classification model object

`fun` — custom model
function handle

`vars` — predictor variables
vector of positive integers | character vector | string scalar | string array | cell array of character vectors

`labels` — class labels
categorical array | character array | logical vector | numeric vector | cell array of character vectors

`data` — predictor data
numeric matrix | table

`includeinteractions` — flag to include interaction terms
`true` | `false`

`includeintercept` — flag to include intercept term
`true` (default) | `false`

`numobservationstosample` — number of observations to sample
number of total observations (default) | positive integer

`querypoints` — points to compute partial dependence
numeric column vector | numeric two-column matrix | cell array of two numeric column vectors

`useparallel` — flag to run in parallel
`false` (default) | `true`

`categoricalpredictors` — categorical predictors list for custom model
vector of positive integers | logical vector | character matrix | string array | cell array of character vectors | `"all"`

`outputcolumns` — output columns of custom model
`"all"` (default) | vector of positive integers | logical vector

`pd` — partial dependence values
numeric array

`x` — query points of first predictor variable
numeric column vector | categorical column vector

`y` — query points of second predictor variable
numeric column vector | categorical column vector | `[]`

automatic parallel support
accelerate code by automatically running computation in parallel using parallel computing toolbox™.

gpu arrays
accelerate code by running on a graphics processing unit (gpu) using parallel computing toolbox™.

r2023a: gpu array support for `regressionsvm` and `compactregressionsvm` models