DOC improve linear model coefficient interpretation example (scikit-learn#31760)

Co-authored-by: Stefanie Senger <91849487+StefanieSenger@users.noreply.github.com>

Author: MarieSacksick

examples/inspection/plot_linear_model_coefficient_interpretation.py

@@ -56,8 +56,8 @@
 survey = fetch_openml(data_id=534, as_frame=True)
 
 # %%
-# Then, we identify features `X` and targets `y`: the column WAGE is our
-# target variable (i.e., the variable which we want to predict).
+# Then, we identify features `X` and target `y`: the column WAGE is our
+# target variable (i.e. the variable which we want to predict).
 
 X = survey.data[survey.feature_names]
 X.describe(include="all")
@@ -89,7 +89,7 @@
 X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)
 
 # %%
-# First, let's get some insights by looking at the variable distributions and
+# First, let's get some insights by looking at the variables' distributions and
 # at the pairwise relationships between them. Only numerical
 # variables will be used. In the following plot, each dot represents a sample.
 #
@@ -107,7 +107,7 @@
 #
 # The WAGE is increasing when EDUCATION is increasing.
 # Note that the dependence between WAGE and EDUCATION
-# represented here is a marginal dependence, i.e., it describes the behavior
+# represented here is a marginal dependence, i.e. it describes the behavior
 # of a specific variable without keeping the others fixed.
 #
 # Also, the EXPERIENCE and AGE are strongly linearly correlated.
@@ -128,7 +128,7 @@
 # In particular categorical variables cannot be included in linear model if not
 # coded as integers first. In addition, to avoid categorical features to be
 # treated as ordered values, we need to one-hot-encode them.
-# Our pre-processor will
+# Our pre-processor will:
 #
 # - one-hot encode (i.e., generate a column by category) the categorical
 #   columns, only for non-binary categorical variables;
@@ -148,8 +148,8 @@
 )
 
 # %%
-# To describe the dataset as a linear model we use a ridge regressor
-# with a very small regularization and to model the logarithm of the WAGE.
+# We use a ridge regressor
+# with a very small regularization to model the logarithm of the WAGE.
 
 from sklearn.compose import TransformedTargetRegressor
 from sklearn.linear_model import Ridge
@@ -171,9 +171,9 @@
 model.fit(X_train, y_train)
 
 # %%
-# Then we check the performance of the computed model plotting its predictions
-# on the test set and computing,
-# for example, the median absolute error of the model.
+# Then we check the performance of the computed model by plotting its predictions
+# against the actual values on the test set, and by computing
+# the median absolute error.
 
 from sklearn.metrics import PredictionErrorDisplay, median_absolute_error
 
@@ -289,11 +289,12 @@
 # %%
 # Now that the coefficients have been scaled, we can safely compare them.
 #
-# .. warning::
+# .. note::
 #
 #   Why does the plot above suggest that an increase in age leads to a
-#   decrease in wage? Why the :ref:`initial pairplot
-#   <marginal_dependencies>` is telling the opposite?
+#   decrease in wage? Why is the :ref:`initial pairplot
+#   <marginal_dependencies>` telling the opposite?
+#   This difference is the difference between marginal and conditional dependence.
 #
 # The plot above tells us about dependencies between a specific feature and
 # the target when all other features remain constant, i.e., **conditional
@@ -399,7 +400,7 @@
 # Two regions are populated: when the EXPERIENCE coefficient is
 # positive the AGE one is negative and vice-versa.
 #
-# To go further we remove one of the 2 features and check what is the impact
+# To go further we remove one of the two features, AGE, and check what is the impact
 # on the model stability.
 
 column_to_drop = ["AGE"]
@@ -469,8 +470,7 @@
 
 # %%
 # Again, we check the performance of the computed
-# model using, for example, the median absolute error of the model and the R
-# squared coefficient.
+# model using the median absolute error.
 
 mae_train = median_absolute_error(y_train, model.predict(X_train))
 y_pred = model.predict(X_test)
@@ -506,10 +506,7 @@
 plt.subplots_adjust(left=0.3)
 
 # %%
-# We now inspect the coefficients across several cross-validation folds. As in
-# the above example, we do not need to scale the coefficients by the std. dev.
-# of the feature values since this scaling was already
-# done in the preprocessing step of the pipeline.
+# We now inspect the coefficients across several cross-validation folds.
 
 cv_model = cross_validate(
     model,
@@ -768,9 +765,6 @@
 # * Coefficients must be scaled to the same unit of measure to retrieve
 #   feature importance. Scaling them with the standard-deviation of the
 #   feature is a useful proxy.
-# * Interpreting causality is difficult when there are confounding effects. If
-#   the relationship between two variables is also affected by something
-#   unobserved, we should be careful when making conclusions about causality.
 # * Coefficients in multivariate linear models represent the dependency
 #   between a given feature and the target, **conditional** on the other
 #   features.
@@ -780,7 +774,6 @@
 #   coefficients could significantly vary from one another.
 # * Inspecting coefficients across the folds of a cross-validation loop
 #   gives an idea of their stability.
-# * Coefficients are unlikely to have any causal meaning. They tend
-#   to be biased by unobserved confounders.
-# * Inspection tools may not necessarily provide insights on the true
-#   data generating process.
+# * Interpreting causality is difficult when there are confounding effects. If
+#   the relationship between two variables is also affected by something
+#   unobserved, we should be careful when making conclusions about causality.