The ingredients package allows for generating prediction validation and predition perturbation explanations. They allow for both global and local model explanation.
Generic function decribe() generates a natural language description for explanations generated with feature_importance(), ceteris_paribus() functions.
To show generating automatic descriptions we first load the data set and build a random forest model classifying, which of the passangers survived sinking of the titanic. Then, using DALEX package, we generate an explainer of the model. Lastly we select a random passanger, which prediction’s should be explained.
#> Preparation of a new explainer is initiated
#> -> model label : Random Forest
#> -> data : 2099 rows 8 cols
#> -> target variable : 2099 values
#> -> model_info : package randomForest , ver. 4.6.14 , task regression ( [33m default [39m )
#> -> predict function : yhat.randomForest will be used ( [33m default [39m )
-#> -> predicted values : numerical, min = 0.007074326 , mean = 0.323572 , max = 0.9909881
+#> -> predicted values : numerical, min = 0.007831174 , mean = 0.3243102 , max = 0.9920739
#> -> residual function : difference between y and yhat ( [33m default [39m )
-#> -> residuals : numerical, min = -0.8119382 , mean = 0.0008682545 , max = 0.8993734
+#> -> residuals : numerical, min = -0.8199771 , mean = 0.0001300024 , max = 0.9015269
#> [32m A new explainer has been created! [39m
#> gender age class embarked country fare sibsp parch
+#> 1284 male 50 1st Southampton United States 211.1 1 1
Now we are ready for generating various explantions and then describing it with describe() function.
Feature Importance
Feature importance explanation shows the importance of all the model’s variables. As it is a global explanation technique, no passanger need to be specified.
Function describe() easily describes which variables are the most important. Argument nonsignificance_treshold as always sets the level above which variables become significant. For higher treshold, less variables will be described as significant.
#> The number of important variables for Random Forest's prediction is 65 out of 108.
-#> Variables _baseline_, _baseline_, _baseline_ have the highest importantance.
For a user with no experience, interpreting the above plot may be not straightforward. Thus we generate a natural language description in order to make it easier.
#> For the selected instance, prediction estimated by Random Forest is equal to 0.239.
#>
-#> Model's prediction would decrease substantially if the value of class variable would change to "engineering crew", "3rd", "restaurant staff", "victualling crew", "deck crew".
-#> The largest change would be marked if class variable would change to "engineering crew".
+#> Model's prediction would increase substantially if the value of class variable would change to "deck crew". On the other hand, Random Forest's prediction would decrease substantially if the value of class variable would change to "2nd", "restaurant staff", "3rd", "engineering crew", "victualling crew". The largest change would be marked if class variable would change to "2nd".
#>
-#> Other variables are with less importance and they do not change prediction by more than 0.04%.
+#> All the variables were displayed.
Natural lannguage descriptions should be flexible in order to provide the desired level of complexity and specificity. Thus various parameters can modify the description being generated.
#> Random Forest predicts that for the selected instance, the probability that the passanger will survive is equal to 0.239
#>
-#> The most important change in Random Forest's prediction would occur for class = "engineering crew". It decreases the prediction by 0.277.
-#> The second most important change in the prediction would occur for class = "3rd". It decreases the prediction by 0.276.
-#> The third most important change in the prediction would occur for class = "restaurant staff". It decreases the prediction by 0.215.
+#> The most important change in Random Forest's prediction would occur for class = "2nd". It decreases the prediction by 0.057.
+#> The second most important change in the prediction would occur for class = "restaurant staff". It decreases the prediction by 0.055.
+#> The third most important change in the prediction would occur for class = "3rd". It decreases the prediction by 0.053.
#>
-#> Other variable values are with less importance. They do not change the the probability that the passanger will survive by more than 0.2.
+#> Other variable values are with less importance. They do not change the the probability that the passanger will survive by more than 0.042.
Please note, that describe() can handle only one variable at a time, so it is recommended to specify, which variables should be described.
#> Random Forest predicts that for the selected instance, the probability that the passanger will survive is equal to 0.239
#>
-#> The most important change in Random Forest's prediction would occur for class = "engineering crew". It decreases the prediction by 0.277.
-#> The second most important change in the prediction would occur for class = "3rd". It decreases the prediction by 0.276.
-#> The third most important change in the prediction would occur for class = "restaurant staff". It decreases the prediction by 0.215.
+#> The most important change in Random Forest's prediction would occur for class = "2nd". It decreases the prediction by 0.057.
+#> The second most important change in the prediction would occur for class = "restaurant staff". It decreases the prediction by 0.055.
+#> The third most important change in the prediction would occur for class = "3rd". It decreases the prediction by 0.053.
#>
-#> Other variable values are with less importance. They do not change the the probability that the passanger will survive by more than 0.2.
+#> Other variable values are with less importance. They do not change the the probability that the passanger will survive by more than 0.042.
#> Random Forest predicts that for the selected instance, prediction is equal to 0.239
#>
-#> The highest prediction occurs for (age = 39), while the lowest for (age = 74).
-#> Breakpoint is identified at (age = 60).
+#> The highest prediction occurs for (age = 2), while the lowest for (age = 74).
+#> Breakpoint is identified at (age = 13).
#>
-#> Average model responses are *lower* for variable values *higher* than breakpoint (= 60).
-
Ceteris Paribus profiles are described only for a single observation. If we want to access the influence of more than one observation, we need to describe dependency profiles.
+#> Average model responses are *higher* for variable values *lower* than breakpoint (= 13).
+
Ceteris Paribus profiles are described only for a single observation. If we want to access the influence of more than one observation, we need to describe dependence profiles.
#> Random Forest's mean prediction is equal to 0.239.
#>
-#> The highest prediction occurs for (fare = 80), while the lowest for (fare = 0).
+#> The highest prediction occurs for (fare = 55.081), while the lowest for (fare = 221.669696).
#> Breakpoint is identified at (fare = 80).
#>
-#> Average model responses are *higher* for variable values *higher* than breakpoint (= 80).
-
pdp <-aggregate_profiles(cp_rf, type ="partial", variable_type ="categorical")
-plot(pdp, variables = perturbed_variable)
+#> Average model responses are *lower* for variable values *higher* than breakpoint (= 80).
+
pdp <-aggregate_profiles(cp_rf, type ="partial", variable_type ="categorical")
+plot(pdp, variables = perturbed_variable)
#> Random Forest's mean prediction is equal to 0.239.
#>
-#> Model's prediction would increase substantially if the value of class variable would change to "3rd". On the other hand, Random Forest's prediction would decrease substantially if the value of class variable would change to "engineering crew". The largest change would be marked if class variable would change to "2nd".
+#> Model's prediction would increase substantially if the value of class variable would change to "2nd".
+#> The largest change would be marked if class variable would change to "1st".
#>
-#> Other variables are with less importance and they do not change prediction by more than 0.04%.
+#> Other variables are with less importance and they do not change prediction by more than 0.01%.
Lets try Partial Dependency profiles, Conditional Dependency profiles and Accumulated Local profiles. For the last two we can try different smoothing factors
Lets try Partial Dependence profiles, Conditional Dependence profiles and Accumulated Local profiles. For the last two we can try different smoothing factors
Let’s see an example for DALEX package for classification models for the survival problem for Titanic dataset. Here we are using a dataset titanic avaliable in the DALEX package. Note that this data was copied from the stablelearner package.
#> gender age class embarked country fare sibsp parch survived
#> 1 male 42 3rd Southampton United States 7.11 0 0 no
#> 2 male 13 3rd Southampton United States 20.05 0 2 no
@@ -127,12 +127,12 @@
Model for Titanic survival
Ok, now it’s time to create a model. Let’s use the Random Forest model.
#> Preparation of a new explainer is initiated
#> -> model label : Random Forest v7
#> -> data : 2099 rows 8 cols
#> -> target variable : 2099 values
#> -> model_info : package randomForest , ver. 4.6.14 , task regression ( [33m default [39m )
#> -> predict function : yhat.randomForest will be used ( [33m default [39m )
-#> -> predicted values : numerical, min = 0.009726169 , mean = 0.3249803 , max = 0.9917946
+#> -> predicted values : numerical, min = 0.0133887 , mean = 0.3248256 , max = 0.9924437
#> -> residual function : difference between y and yhat ( [33m default [39m )
-#> -> residuals : numerical, min = -0.8000352 , mean = -0.0005401156 , max = 0.8904472
+#> -> residuals : numerical, min = -0.7953965 , mean = -0.0003854325 , max = 0.9009842
#> [32m A new explainer has been created! [39m
Model Level Feature Importance
Use the feature_importance() explainer to present importance of particular features. Note that type = "difference" normalizes dropouts, and now they all start in 0.
As we see the most important feature is gender. Next three importnat features are class, age and fare. Let’s see the link between model response and these features.
#> Top profiles :
#> _vname_ _label_ _x_ _yhat_ _ids_
-#> 1 fare Random Forest v7 0.0000000 0.3491995 0
-#> 2 age Random Forest v7 0.1666667 0.5393965 0
-#> 3 age Random Forest v7 2.0000000 0.5598879 0
-#> 4 age Random Forest v7 4.0000000 0.5647907 0
-#> 5 fare Random Forest v7 6.1904000 0.3325981 0
-#> 6 age Random Forest v7 7.0000000 0.5278368 0
+#> 1 fare Random Forest v7 0.0000000 0.3159050 0
+#> 2 age Random Forest v7 0.1666667 0.5384993 0
+#> 3 age Random Forest v7 2.0000000 0.5608622 0
+#> 4 age Random Forest v7 4.0000000 0.5678473 0
+#> 5 fare Random Forest v7 6.1904000 0.3005658 0
+#> 6 age Random Forest v7 7.0000000 0.5320725 0
+
It looks like the most important feature for this passenger is age and sex. After all his odds for survival are higher than for the average passenger. Mainly because of the young age and despite of being a male.
diff --git a/docs/index.html b/docs/index.html
index 2d5abc6d..1bc2700c 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -15,9 +15,9 @@
Key functions are:
feature_importance() for assessment of global level feature importance,
ceteris_paribus() for calculation of the what-if plots,
- partial_dependency() for partial dependency plots,
- conditional_dependency() for conditional dependency plots,
- accumulated_dependency() for accumulated local effects plots,
+ partial_dependence() for partial dependence plots,
+ conditional_dependence() for conditional dependence plots,
+ accumulated_dependence() for accumulated local effects plots,
aggregate_profiles() and cluster_profiles() for aggregation of ceteris paribus profiles,
generic print() and plot() for better usability of selected explainers,
generic plotD3() for interactive, D3 based explanations, and
@@ -53,7 +53,7 @@
Accumulated Local Effects Profiles accumulate local changes in Ceteris Paribus Profiles.
+Function accumulated_dependence calls ceteris_paribus and then aggregate_profiles.
an explainer created with function DALEX::explain(), an object of the class ceteris_paribus_explainer
+or a model to be explained.
+
+
+
...
+
other parameters
+
+
+
variables
+
names of variables for which profiles shall be calculated.
+Will be passed to calculate_variable_split.
+If NULL then all variables from the validation data will be used.
+
+
+
N
+
number of observations used for calculation of partial dependence profiles.
+By default, 500 observations will be chosen randomly.
+
+
+
variable_splits
+
named list of splits for variables, in most cases created with calculate_variable_split.
+If NULL then it will be calculated based on validation data avaliable in the explainer.
The function aggregate_profiles() calculates an aggregate of ceteris paribus profiles.
-It can be: Partial Dependency Profile (average across Ceteris Paribus Profiles),
-Conditional Dependency Profile (local weighted average across Ceteris Paribus Profiles) or
-Accumulated Local Dependency Profile (cummulated average local changes in Ceteris Paribus Profiles).
+It can be: Partial Dependence Profile (average across Ceteris Paribus Profiles),
+Conditional Dependence Profile (local weighted average across Ceteris Paribus Profiles) or
+Accumulated Local Dependence Profile (cummulated average local changes in Ceteris Paribus Profiles).
+
Internal Function for Individual Variable Profiles
+
This function calculates individual variable profiles (ceteris paribus profiles), i.e. series of predictions from a model calculated for observations with altered single coordinate.
+
calculate_variable_profile(
@@ -161,7 +164,7 @@
Internal Function for Individual Variable Profiles
predict_function=predict,
...
)
-
+
Arguments
@@ -186,28 +189,34 @@
Arg
other parameters that will be passed to the predict_function
-
+
Value
a data frame with profiles for selected variables and selected observations
+
Details
Note that calculate_variable_profile function is S3 generic.
If you want to work on non standard data sources (like H2O ddf, external databases)
you should overload it.
Internal Function for Split Points for Selected Variables
+
This function calculate candidate splits for each selected variable.
For numerical variables splits are calculated as percentiles
(in general uniform quantiles of the length grid_points).
For all other variables splits are calculated as unique values.
+
calculate_variable_split(data, variables=colnames(data), grid_points=101)
# S3 method for defaultcalculate_variable_split(data, variables=colnames(data), grid_points=101)
-
+
Arguments
@@ -172,24 +175,28 @@
Arg
number of points used for response path
-
+
Value
A named list with splits for selected variables
+
Details
Note that calculate_variable_split function is S3 generic.
If you want to work on non standard data sources (like H2O ddf, external databases)
you should overload it.
This explainer works for individual observations.
For each observation it calculates Ceteris Paribus Profiles for selected variables.
Such profiles can be used to hypothesize about model results if selected variable is changed.
For this reason it is also called 'What-If Profiles'.
This function calculates ceteris paribus profiles for grid of values spanned by two variables.
It may be useful to identify or present interactions between two variables.
Conditional Dependence Profiles (aka Local Profiles) average localy Ceteris Paribus Profiles.
+Function 'conditional_dependence' calls 'ceteris_paribus' and then 'aggregate_profiles'.
an explainer created with function DALEX::explain(), an object of the class ceteris_paribus_explainer
+or a model to be explained.
+
+
+
...
+
other parameters
+
+
+
variables
+
names of variables for which profiles shall be calculated.
+Will be passed to calculate_variable_split. If NULL then all variables from the validation data will be used.
+
+
+
N
+
number of observations used for calculation of partial dependence profiles. By default 500.
+
+
+
variable_splits
+
named list of splits for variables, in most cases created with calculate_variable_split.
+If NULL then it will be calculated based on validation data avaliable in the explainer.
Natural language description of feature importance explainer
+
Generic function describe generates a natural language
description of ceteris_paribus(), aggregated_profiles() and
feature_importance() explanations what enchaces their interpretability.
Natural language description of feature importance explainer
# S3 method for feature_importance_explainerdescribe(x, nonsignificance_treshold=0.15, ...)
-
+
Arguments
@@ -208,7 +211,7 @@
Arg
label for model's prediction
-
+
Details
Function describe.ceteris_paribus() generates a natural language description of
@@ -230,6 +233,7 @@
Details
have significant dropout difference from the full model, depending on nonsignificance_treshold.
The description prints the three most important variables for the model's prediction.
The current design of DALEX explainer does not allow for displaying variables values.
+
#> The number of important variables for lm's prediction is 43 out of 75.
-#> Variables _baseline_, _baseline_, _baseline_ have the highest importantance.
Examp
#> -> predict function : yhat.default will be used ( default )
#> -> predicted values : numerical, min = 1.687903e-06 , mean = 0.363713 , max = 0.9996712
#> -> residual function : difference between y and yhat ( default )
-#> -> residuals : numerical, min = -0.9885727 , mean = 0.0001203494 , max = 0.9970635
+#> -> residuals : numerical, min = -0.9885727 , mean = 0.0001203497 , max = 0.9970635
#> A new explainer has been created!
Partial Dependence Profiles are averages from Ceteris Paribus Profiles.
+Function partial_dependence calls ceteris_paribus and then aggregate_profiles.
an explainer created with function DALEX::explain(), an object of the class ceteris_paribus_explainer or
+or a model to be explained.
+
+
+
...
+
other parameters
+
+
+
variables
+
names of variables for which profiles shall be calculated.
+Will be passed to calculate_variable_split.
+If NULL then all variables from the validation data will be used.
+
+
+
N
+
number of observations used for calculation of partial dependence profiles. By default 500.
+
+
+
variable_splits
+
named list of splits for variables, in most cases created with calculate_variable_split.
+If NULL then it will be calculated based on validation data avaliable in the explainer.
Function plot.aggregated_profiles_explainer plots partial dependency plot or accumulated effect plot.
+
+
Function plot.aggregated_profiles_explainer plots partial dependence plot or accumulated effect plot.
It works in a similar way to plot.ceteris_paribus, but instead of individual profiles
show average profiles for each variable listed in the variables vector.
+
# S3 method for aggregated_profiles_explainer
@@ -159,7 +162,7 @@
Function plot.ceteris_paribus_explainer plots Individual Variable Profiles for selected observations.
Various parameters help to decide what should be plotted, profiles, aggregated profiles, points or rugs.
This function plots variable importance calculated as changes in the loss function after variable drops.
It uses output from feature_importance function that corresponds to
permutation based measure of variable importance.
@@ -155,6 +157,7 @@
Plots Feature Importance
The order depends on the average drop out loss.
In different panels variable contributions may not look like sorted if variable
importance is different in different in different models.
+
# S3 method for feature_importance_explainer
@@ -166,7 +169,7 @@
Plots Feature Importance
bar_width=10,
desc_sorting=TRUE
)
-
+
Arguments
@@ -196,16 +199,19 @@
Arg
logical. Should the bars be sorted descending? By default TRUE
Examp
#> -> predict function : yhat.default will be used ( default )
#> -> predicted values : numerical, min = 1.687903e-06 , mean = 0.363713 , max = 0.9996712
#> -> residual function : difference between y and yhat ( default )
-#> -> residuals : numerical, min = -0.9885727 , mean = 0.0001203494 , max = 0.9970635
+#> -> residuals : numerical, min = -0.9885727 , mean = 0.0001203497 , max = 0.9970635
#> A new explainer has been created!
Plots Aggregated Ceteris Paribus Profiles in D3 with r2d3 Package.
+
Function plotD3.aggregated_profiles_explainer plots an aggregate of ceteris paribus profiles.
It works in a similar way to plotD3.ceteris_paribus_explainer but, instead of individual profiles,
show average profiles for each variable listed in the variables vector.
Plots Ceteris Paribus Profiles in D3 with r2d3 Package.
+
Function plotD3.ceteris_paribus_explainer plots Individual Variable Profiles for selected observations.
It uses output from ceteris_paribus function.
Various parameters help to decide what should be plotted, profiles, aggregated profiles, points or rugs.
Plot Feature Importance Objects in D3 with r2d3 Package.
+
Function plotD3.feature_importance_explainer plots dropouts for variables used in the model.
It uses output from feature_importance function that corresponds to permutation based measure of feature importance.
Variables are sorted in the same order in all panels. The order depends on the average drop out loss.
In different panels variable contributions may not look like sorted if variable importance is different in different models.
+
# S3 method for feature_importance_explainer
@@ -163,7 +166,7 @@
Plot Feature Importance Objects in D3 with r2d3 Package.
Select Subset of Rows Closest to a Specified Observation
+
Function select_neighbours selects subset of rows from data set.
This is useful if data is large and we need just a sample to calculate profiles.
+
select_neighbours(
@@ -155,7 +158,7 @@
Select Subset of Rows Closest to a Specified Observation
n=20,
frac=NULL
)
-
+
Arguments
@@ -186,15 +189,17 @@
Arg
Either n or frac need to be specified.
-
+
Value
a data frame with selected rows
+
Details
Note that select_neighbours() function is S3 generic.
If you want to work on non standard data sources (like H2O ddf, external databases)
you should overload it.
Function select_sample selects subset of rows from data set.
This is useful if data is large and we need just a sample to calculate profiles.
+
select_sample(data, n=100, seed=1313)
-
+
Arguments
@@ -165,15 +168,17 @@
Arg
seed for random number generator.
-
+
Value
a data frame with selected rows
+
Details
Note that select_subsample() function is S3 generic.
If you want to work on non standard data sources (like H2O ddf, external databases)
you should overload it.
Function show_observations adds a layer to a plot created with
plot.ceteris_paribus_explainer for selected observations.
Various parameters help to decide what should be plotted, profiles, aggregated profiles, points or rugs.
Function show_residuals adds a layer to a plot created with
plot.ceteris_paribus_explainer for selected observations.
Note that the y argument has to be specified in the ceteris_paribus function.
Function show_rugs adds a layer to a plot created with
plot.ceteris_paribus_explainer for selected observations.
Various parameters help to decide what should be plotted, profiles, aggregated profiles, points or rugs.
diff --git a/man/accumulated_dependency.Rd b/man/accumulated_dependence.Rd
similarity index 81%
rename from man/accumulated_dependency.Rd
rename to man/accumulated_dependence.Rd
index 6c2a3ef6..857c7d04 100644
--- a/man/accumulated_dependency.Rd
+++ b/man/accumulated_dependence.Rd
@@ -1,15 +1,16 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/accumulated_dependency.R
-\name{accumulated_dependency}
+% Please edit documentation in R/accumulated_dependence.R
+\name{accumulated_dependence}
+\alias{accumulated_dependence}
+\alias{accumulated_dependence.explainer}
+\alias{accumulated_dependence.default}
+\alias{accumulated_dependence.ceteris_paribus_explainer}
\alias{accumulated_dependency}
-\alias{accumulated_dependency.explainer}
-\alias{accumulated_dependency.default}
-\alias{accumulated_dependency.ceteris_paribus_explainer}
\title{Accumulated Local Effects Profiles aka ALEPlots}
\usage{
-accumulated_dependency(x, ...)
+accumulated_dependence(x, ...)
-\method{accumulated_dependency}{explainer}(
+\method{accumulated_dependence}{explainer}(
x,
variables = NULL,
N = 500,
@@ -19,7 +20,7 @@ accumulated_dependency(x, ...)
variable_type = "numerical"
)
-\method{accumulated_dependency}{default}(
+\method{accumulated_dependence}{default}(
x,
data,
predict_function = predict,
@@ -32,7 +33,9 @@ accumulated_dependency(x, ...)
variable_type = "numerical"
)
-\method{accumulated_dependency}{ceteris_paribus_explainer}(x, ..., variables = NULL)
+\method{accumulated_dependence}{ceteris_paribus_explainer}(x, ..., variables = NULL)
+
+accumulated_dependency(x, ...)
}
\arguments{
\item{x}{an explainer created with function \code{DALEX::explain()}, an object of the class \code{ceteris_paribus_explainer}
@@ -44,7 +47,7 @@ or a model to be explained.}
Will be passed to \code{\link{calculate_variable_split}}.
If \code{NULL} then all variables from the validation data will be used.}
-\item{N}{number of observations used for calculation of partial dependency profiles.
+\item{N}{number of observations used for calculation of partial dependence profiles.
By default, 500 observations will be chosen randomly.}
\item{variable_splits}{named list of splits for variables, in most cases created with \code{\link{calculate_variable_split}}.
@@ -67,10 +70,10 @@ an object of the class \code{aggregated_profiles_explainer}
}
\description{
Accumulated Local Effects Profiles accumulate local changes in Ceteris Paribus Profiles.
-Function \code{\link{accumulated_dependency}} calls \code{\link{ceteris_paribus}} and then \code{\link{aggregate_profiles}}.
+Function \code{\link{accumulated_dependence}} calls \code{\link{ceteris_paribus}} and then \code{\link{aggregate_profiles}}.
}
\details{
-Find more detailes in the \href{https://pbiecek.github.io/ema/accumulatedLocalProfiles.html}{Accumulated Local Dependency Chapter}.
+Find more detailes in the \href{https://pbiecek.github.io/ema/accumulatedLocalProfiles.html}{Accumulated Local Dependence Chapter}.
}
\examples{
library("DALEX")
@@ -83,7 +86,7 @@ explain_titanic_glm <- explain(model_titanic_glm,
y = titanic_imputed[,8],
verbose = FALSE)
-adp_glm <- accumulated_dependency(explain_titanic_glm,
+adp_glm <- accumulated_dependence(explain_titanic_glm,
N = 150, variables = c("age", "fare"))
head(adp_glm)
plot(adp_glm)
@@ -98,10 +101,10 @@ explain_titanic_rf <- explain(model_titanic_rf,
y = titanic_imputed[,8],
verbose = FALSE)
-adp_rf <- accumulated_dependency(explain_titanic_rf, N = 200, variable_type = "numerical")
+adp_rf <- accumulated_dependence(explain_titanic_rf, N = 200, variable_type = "numerical")
plot(adp_rf)
-adp_rf <- accumulated_dependency(explain_titanic_rf, N = 200, variable_type = "categorical")
+adp_rf <- accumulated_dependence(explain_titanic_rf, N = 200, variable_type = "categorical")
plotD3(adp_rf, label_margin = 80, scale_plot = TRUE)
}
diff --git a/man/aggregate_profiles.Rd b/man/aggregate_profiles.Rd
index b9b96862..becb59de 100644
--- a/man/aggregate_profiles.Rd
+++ b/man/aggregate_profiles.Rd
@@ -39,9 +39,9 @@ an object of the class \code{aggregated_profiles_explainer}
}
\description{
The function \code{aggregate_profiles()} calculates an aggregate of ceteris paribus profiles.
-It can be: Partial Dependency Profile (average across Ceteris Paribus Profiles),
-Conditional Dependency Profile (local weighted average across Ceteris Paribus Profiles) or
-Accumulated Local Dependency Profile (cummulated average local changes in Ceteris Paribus Profiles).
+It can be: Partial Dependence Profile (average across Ceteris Paribus Profiles),
+Conditional Dependence Profile (local weighted average across Ceteris Paribus Profiles) or
+Accumulated Local Dependence Profile (cummulated average local changes in Ceteris Paribus Profiles).
}
\examples{
library("DALEX")
diff --git a/man/conditional_dependency.Rd b/man/conditional_dependence.Rd
similarity index 77%
rename from man/conditional_dependency.Rd
rename to man/conditional_dependence.Rd
index 6d577ed5..913938ef 100644
--- a/man/conditional_dependency.Rd
+++ b/man/conditional_dependence.Rd
@@ -1,16 +1,17 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/conditional_dependency.R
-\name{conditional_dependency}
-\alias{conditional_dependency}
-\alias{conditional_dependency.explainer}
-\alias{conditional_dependency.default}
-\alias{conditional_dependency.ceteris_paribus_explainer}
+% Please edit documentation in R/conditional_dependence.R
+\name{conditional_dependence}
+\alias{conditional_dependence}
+\alias{conditional_dependence.explainer}
+\alias{conditional_dependence.default}
+\alias{conditional_dependence.ceteris_paribus_explainer}
\alias{local_dependency}
-\title{Conditional Dependency Profiles}
+\alias{conditional_dependency}
+\title{Conditional Dependence Profiles}
\usage{
-conditional_dependency(x, ...)
+conditional_dependence(x, ...)
-\method{conditional_dependency}{explainer}(
+\method{conditional_dependence}{explainer}(
x,
variables = NULL,
N = 500,
@@ -20,7 +21,7 @@ conditional_dependency(x, ...)
variable_type = "numerical"
)
-\method{conditional_dependency}{default}(
+\method{conditional_dependence}{default}(
x,
data,
predict_function = predict,
@@ -33,9 +34,11 @@ conditional_dependency(x, ...)
variable_type = "numerical"
)
-\method{conditional_dependency}{ceteris_paribus_explainer}(x, ..., variables = NULL)
+\method{conditional_dependence}{ceteris_paribus_explainer}(x, ..., variables = NULL)
local_dependency(x, ...)
+
+conditional_dependency(x, ...)
}
\arguments{
\item{x}{an explainer created with function \code{DALEX::explain()}, an object of the class \code{ceteris_paribus_explainer}
@@ -46,7 +49,7 @@ or a model to be explained.}
\item{variables}{names of variables for which profiles shall be calculated.
Will be passed to \code{\link{calculate_variable_split}}. If \code{NULL} then all variables from the validation data will be used.}
-\item{N}{number of observations used for calculation of partial dependency profiles. By default 500.}
+\item{N}{number of observations used for calculation of partial dependence profiles. By default 500.}
\item{variable_splits}{named list of splits for variables, in most cases created with \code{\link{calculate_variable_split}}.
If \code{NULL} then it will be calculated based on validation data avaliable in the \code{explainer}.}
@@ -67,11 +70,11 @@ NOTE: It is best when target variable is not present in the \code{data}}
an object of the class \code{aggregated_profile_explainer}
}
\description{
-Conditional Dependency Profiles (aka Local Profiles) average localy Ceteris Paribus Profiles.
-Function 'conditional_dependency' calls 'ceteris_paribus' and then 'aggregate_profiles'.
+Conditional Dependence Profiles (aka Local Profiles) average localy Ceteris Paribus Profiles.
+Function 'conditional_dependence' calls 'ceteris_paribus' and then 'aggregate_profiles'.
}
\details{
-Find more detailes in the \href{https://pbiecek.github.io/ema/accumulatedLocalProfiles.html}{Accumulated Local Dependency Chapter}.
+Find more detailes in the \href{https://pbiecek.github.io/ema/accumulatedLocalProfiles.html}{Accumulated Local Dependence Chapter}.
}
\examples{
library("DALEX")
@@ -84,7 +87,7 @@ explain_titanic_glm <- explain(model_titanic_glm,
y = titanic_imputed[,8],
verbose = FALSE)
-cdp_glm <- conditional_dependency(explain_titanic_glm,
+cdp_glm <- conditional_dependence(explain_titanic_glm,
N = 150, variables = c("age", "fare"))
head(cdp_glm)
plot(cdp_glm)
@@ -99,10 +102,10 @@ explain_titanic_rf <- explain(model_titanic_rf,
y = titanic_imputed[,8],
verbose = FALSE)
-cdp_rf <- conditional_dependency(explain_titanic_rf, N = 200, variable_type = "numerical")
+cdp_rf <- conditional_dependence(explain_titanic_rf, N = 200, variable_type = "numerical")
plot(cdp_rf)
-cdp_rf <- conditional_dependency(explain_titanic_rf, N = 200, variable_type = "categorical")
+cdp_rf <- conditional_dependence(explain_titanic_rf, N = 200, variable_type = "categorical")
plotD3(cdp_rf, label_margin = 80, scale_plot = TRUE)
}
diff --git a/man/describe.Rd b/man/describe.Rd
index bc400835..5abf0141 100644
--- a/man/describe.Rd
+++ b/man/describe.Rd
@@ -1,14 +1,14 @@
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/describe_aggregated_profiles.R,
% R/describe_ceteris_paribus.R, R/describe_feature_importance.R
-\name{describe.partial_dependency_explainer}
-\alias{describe.partial_dependency_explainer}
+\name{describe.partial_dependence_explainer}
+\alias{describe.partial_dependence_explainer}
\alias{describe}
\alias{describe.ceteris_paribus_explainer}
\alias{describe.feature_importance_explainer}
\title{Natural language description of feature importance explainer}
\usage{
-\method{describe}{partial_dependency_explainer}(
+\method{describe}{partial_dependence_explainer}(
x,
nonsignificance_treshold = 0.15,
...,
diff --git a/man/partial_dependency.Rd b/man/partial_dependence.Rd
similarity index 79%
rename from man/partial_dependency.Rd
rename to man/partial_dependence.Rd
index df6359aa..f1d96a4f 100644
--- a/man/partial_dependency.Rd
+++ b/man/partial_dependence.Rd
@@ -1,15 +1,16 @@
% Generated by roxygen2: do not edit by hand
-% Please edit documentation in R/partial_dependency.R
-\name{partial_dependency}
+% Please edit documentation in R/partial_dependence.R
+\name{partial_dependence}
+\alias{partial_dependence}
+\alias{partial_dependence.explainer}
+\alias{partial_dependence.default}
+\alias{partial_dependence.ceteris_paribus_explainer}
\alias{partial_dependency}
-\alias{partial_dependency.explainer}
-\alias{partial_dependency.default}
-\alias{partial_dependency.ceteris_paribus_explainer}
-\title{Partial Dependency Profiles}
+\title{Partial Dependence Profiles}
\usage{
-partial_dependency(x, ...)
+partial_dependence(x, ...)
-\method{partial_dependency}{explainer}(
+\method{partial_dependence}{explainer}(
x,
variables = NULL,
N = 500,
@@ -19,7 +20,7 @@ partial_dependency(x, ...)
variable_type = "numerical"
)
-\method{partial_dependency}{default}(
+\method{partial_dependence}{default}(
x,
data,
predict_function = predict,
@@ -32,7 +33,9 @@ partial_dependency(x, ...)
variable_type = "numerical"
)
-\method{partial_dependency}{ceteris_paribus_explainer}(x, ..., variables = NULL)
+\method{partial_dependence}{ceteris_paribus_explainer}(x, ..., variables = NULL)
+
+partial_dependency(x, ...)
}
\arguments{
\item{x}{an explainer created with function \code{DALEX::explain()}, an object of the class \code{ceteris_paribus_explainer} or
@@ -44,7 +47,7 @@ or a model to be explained.}
Will be passed to \code{\link{calculate_variable_split}}.
If \code{NULL} then all variables from the validation data will be used.}
-\item{N}{number of observations used for calculation of partial dependency profiles. By default 500.}
+\item{N}{number of observations used for calculation of partial dependence profiles. By default 500.}
\item{variable_splits}{named list of splits for variables, in most cases created with \code{\link{calculate_variable_split}}.
If \code{NULL} then it will be calculated based on validation data avaliable in the \code{explainer}.}
@@ -65,8 +68,8 @@ NOTE: It is best when target variable is not present in the \code{data}}
an object of the class \code{aggregated_profiles_explainer}
}
\description{
-Partial Dependency Profiles are averages from Ceteris Paribus Profiles.
-Function \code{partial_dependency} calls \code{ceteris_paribus} and then \code{aggregate_profiles}.
+Partial Dependence Profiles are averages from Ceteris Paribus Profiles.
+Function \code{partial_dependence} calls \code{ceteris_paribus} and then \code{aggregate_profiles}.
}
\details{
Find more detailes in the \href{https://pbiecek.github.io/ema/partialDependenceProfiles.html}{Partial Dependence Profiles Chapter}.
@@ -82,7 +85,7 @@ explain_titanic_glm <- explain(model_titanic_glm,
y = titanic_imputed[,8],
verbose = FALSE)
-pdp_glm <- partial_dependency(explain_titanic_glm,
+pdp_glm <- partial_dependence(explain_titanic_glm,
N = 50, variables = c("age", "fare"))
head(pdp_glm)
plot(pdp_glm)
@@ -97,10 +100,10 @@ explain_titanic_rf <- explain(model_titanic_rf,
y = titanic_imputed[,8],
verbose = FALSE)
-pdp_rf <- partial_dependency(explain_titanic_rf, variable_type = "numerical")
+pdp_rf <- partial_dependence(explain_titanic_rf, variable_type = "numerical")
plot(pdp_rf)
-pdp_rf <- partial_dependency(explain_titanic_rf, variable_type = "categorical")
+pdp_rf <- partial_dependence(explain_titanic_rf, variable_type = "categorical")
plotD3(pdp_rf, label_margin = 80, scale_plot = TRUE)
}
diff --git a/man/plot.aggregated_profiles_explainer.Rd b/man/plot.aggregated_profiles_explainer.Rd
index ae828e3b..b3618e21 100644
--- a/man/plot.aggregated_profiles_explainer.Rd
+++ b/man/plot.aggregated_profiles_explainer.Rd
@@ -33,7 +33,7 @@
a \code{ggplot2} object
}
\description{
-Function \code{plot.aggregated_profiles_explainer} plots partial dependency plot or accumulated effect plot.
+Function \code{plot.aggregated_profiles_explainer} plots partial dependence plot or accumulated effect plot.
It works in a similar way to \code{plot.ceteris_paribus}, but instead of individual profiles
show average profiles for each variable listed in the \code{variables} vector.
}
@@ -48,11 +48,11 @@ explain_titanic_glm <- explain(model_titanic_glm,
y = titanic_imputed[,8],
verbose = FALSE)
-pdp_rf_p <- partial_dependency(explain_titanic_glm, N = 50)
+pdp_rf_p <- partial_dependence(explain_titanic_glm, N = 50)
pdp_rf_p$`_label_` <- "RF_partial"
-pdp_rf_l <- conditional_dependency(explain_titanic_glm, N = 50)
+pdp_rf_l <- conditional_dependence(explain_titanic_glm, N = 50)
pdp_rf_l$`_label_` <- "RF_local"
-pdp_rf_a<- accumulated_dependency(explain_titanic_glm, N = 50)
+pdp_rf_a<- accumulated_dependence(explain_titanic_glm, N = 50)
pdp_rf_a$`_label_` <- "RF_accumulated"
head(pdp_rf_p)
plot(pdp_rf_p, pdp_rf_l, pdp_rf_a, color = "_label_")
diff --git a/tests/testthat/test_aggregated_profiles.R b/tests/testthat/test_aggregated_profiles.R
index d29c8214..5ed5f5be 100644
--- a/tests/testthat/test_aggregated_profiles.R
+++ b/tests/testthat/test_aggregated_profiles.R
@@ -28,11 +28,11 @@ test_that("plot aggregate_profiles",{
expect_true("gg" %in% class(pl1))
- pdp_rf_p <- partial_dependency(explainer_rf, variables = "age")
+ pdp_rf_p <- partial_dependence(explainer_rf, variables = "age")
pdp_rf_p$`_label_` <- "RF_partial"
- pdp_rf_c <- conditional_dependency(explainer_rf, variables = "age")
+ pdp_rf_c <- conditional_dependence(explainer_rf, variables = "age")
pdp_rf_c$`_label_` <- "RF_conditional"
- pdp_rf_a <- accumulated_dependency(explainer_rf, variables = "age")
+ pdp_rf_a <- accumulated_dependence(explainer_rf, variables = "age")
pdp_rf_a$`_label_` <- "RF_accumulated"
pl2 <- plot(pdp_rf_p, pdp_rf_c, pdp_rf_a, color = "_label_")
@@ -42,7 +42,7 @@ test_that("plot aggregate_profiles",{
})
-test_that("plot partial_dependency",{
+test_that("plot partial_dependence",{
library("DALEX")
library("randomForest")
titanic <- na.omit(titanic)
@@ -56,7 +56,7 @@ test_that("plot partial_dependency",{
selected_passangers <- select_sample(titanic, n = 100)
cp_rf <- ceteris_paribus(explain_titanic_rf, selected_passangers)
- res <- partial_dependency(explain_titanic_rf, N=50, variables = "gender", variable_type = "categorical")
+ res <- partial_dependence(explain_titanic_rf, N=50, variables = "gender", variable_type = "categorical")
expect_true("aggregated_profiles_explainer" %in% class(res))
})
diff --git a/vignettes/vignette_describe.Rmd b/vignettes/vignette_describe.Rmd
index d1c85373..d614cf0a 100644
--- a/vignettes/vignette_describe.Rmd
+++ b/vignettes/vignette_describe.Rmd
@@ -114,9 +114,9 @@ plot(cp_rf, variables = perturbed_variable_continuous)
describe(cp_rf, variables = perturbed_variable_continuous)
```
-Ceteris Paribus profiles are described only for a single observation. If we want to access the influence of more than one observation, we need to describe dependency profiles.
+Ceteris Paribus profiles are described only for a single observation. If we want to access the influence of more than one observation, we need to describe dependence profiles.
-## Partial Dependency Profiles
+## Partial Dependence Profiles
```{r}
pdp <- aggregate_profiles(cp_rf, type = "partial")
diff --git a/vignettes/vignette_simulated.Rmd b/vignettes/vignette_simulated.Rmd
index f8e81c2d..a757416e 100644
--- a/vignettes/vignette_simulated.Rmd
+++ b/vignettes/vignette_simulated.Rmd
@@ -74,33 +74,33 @@ plot(cp_model) +
```
-# Dependency profiles
+# Dependence profiles
-Lets try Partial Dependency profiles, Conditional Dependency profiles and Accumulated Local profiles. For the last two we can try different smoothing factors
+Lets try Partial Dependence profiles, Conditional Dependence profiles and Accumulated Local profiles. For the last two we can try different smoothing factors
```{r}
-pd_model <- partial_dependency(explain_the_model, variables = c("x1", "x2"))
+pd_model <- partial_dependence(explain_the_model, variables = c("x1", "x2"))
pd_model$`_label_` = "PDP"
-cd_model <- conditional_dependency(explain_the_model, variables = c("x1", "x2"))
+cd_model <- conditional_dependence(explain_the_model, variables = c("x1", "x2"))
cd_model$`_label_` = "CDP 0.25"
-ad_model <- accumulated_dependency(explain_the_model, variables = c("x1", "x2"))
+ad_model <- accumulated_dependence(explain_the_model, variables = c("x1", "x2"))
ad_model$`_label_` = "ALE 0.25"
plot(ad_model, cd_model, pd_model) +
ggtitle("Feature effects - PDP, CDP, ALE")
-cd_model_1 <- conditional_dependency(explain_the_model, variables = c("x1", "x2"), span = 0.1)
+cd_model_1 <- conditional_dependence(explain_the_model, variables = c("x1", "x2"), span = 0.1)
cd_model_1$`_label_` = "CDP 0.1"
-cd_model_5 <- conditional_dependency(explain_the_model, variables = c("x1", "x2"), span = 0.5)
+cd_model_5 <- conditional_dependence(explain_the_model, variables = c("x1", "x2"), span = 0.5)
cd_model_5$`_label_` = "CDP 0.5"
-ad_model_1 <- accumulated_dependency(explain_the_model, variables = c("x1", "x2"), span = 0.5)
+ad_model_1 <- accumulated_dependence(explain_the_model, variables = c("x1", "x2"), span = 0.5)
ad_model_1$`_label_` = "ALE 0.1"
-ad_model_5 <- accumulated_dependency(explain_the_model, variables = c("x1", "x2"), span = 0.5)
+ad_model_5 <- accumulated_dependence(explain_the_model, variables = c("x1", "x2"), span = 0.5)
ad_model_5$`_label_` = "ALE 0.5"
plot(ad_model, cd_model, pd_model, cd_model_1, cd_model_5, ad_model_1, ad_model_5) +
@@ -108,7 +108,7 @@ plot(ad_model, cd_model, pd_model, cd_model_1, cd_model_5, ad_model_1, ad_model_
```
-# Dependency profiles in groups
+# Dependence profiles in groups
And now, let's see how the grouping factor works
@@ -119,14 +119,14 @@ df$x3 <- factor(sign(df$x2))
explain_the_model$data = df
# PDP in groups
-pd_model_groups <- partial_dependency(explain_the_model,
+pd_model_groups <- partial_dependence(explain_the_model,
variables = c("x1", "x2"),
groups = "x3")
plot(pd_model_groups) +
- ggtitle("Partial Dependency")
+ ggtitle("Partial Dependence")
# ALE in groups
-ad_model_groups <- accumulated_dependency(explain_the_model,
+ad_model_groups <- accumulated_dependence(explain_the_model,
variables = c("x1", "x2"),
groups = "x3")
plot(ad_model_groups) +
@@ -134,11 +134,11 @@ plot(ad_model_groups) +
# CDP in groups
-cd_model_groups <- conditional_dependency(explain_the_model,
+cd_model_groups <- conditional_dependence(explain_the_model,
variables = c("x1", "x2"),
groups = "x3")
plot(cd_model_groups) +
- ggtitle("Conditional Dependency")
+ ggtitle("Conditional Dependence")
```
diff --git a/vignettes/vignette_titanic.Rmd b/vignettes/vignette_titanic.Rmd
index 4c5b1c68..4aa57169 100644
--- a/vignettes/vignette_titanic.Rmd
+++ b/vignettes/vignette_titanic.Rmd
@@ -69,31 +69,31 @@ plot(fi_rf)
As we see the most important feature is `gender`. Next three importnat features are `class`, `age` and `fare`. Let's see the link between model response and these features.
-Such univariate relation can be calculated with `partial_dependency()`.
+Such univariate relation can be calculated with `partial_dependence()`.
## age
Kids 5 years old and younger have much higher survival probability.
-### Partial Dependency Profiles
+### Partial Dependence Profiles
```{r}
-pp_age <- partial_dependency(explain_titanic_rf, variables = c("age", "fare"))
+pp_age <- partial_dependence(explain_titanic_rf, variables = c("age", "fare"))
head(pp_age)
plot(pp_age)
```
-### Conditional Dependency Profiles
+### Conditional Dependence Profiles
```{r}
-cp_age <- conditional_dependency(explain_titanic_rf, variables = c("age", "fare"))
+cp_age <- conditional_dependence(explain_titanic_rf, variables = c("age", "fare"))
plot(cp_age)
```
### Accumulated Local Effect Profiles
```{r}
-ap_age <- accumulated_dependency(explain_titanic_rf, variables = c("age", "fare"))
+ap_age <- accumulated_dependence(explain_titanic_rf, variables = c("age", "fare"))
plot(ap_age)
```
+
