Pushing the docs to dev/ for branch: main, commit de084fc3f00b7f1e790ce841fff7f484b254fa33

Author: sklearn-ci

dev/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip

@@ -124,8 +124,7 @@
 ax = coef.plot.barh()
 ax.set_xlabel("Coefficient values")
 ax.set_title("Coefficients of the linear regression including the ability features")
-plt.tight_layout()
-plt.show()
+_ = plt.tight_layout()
 
 # %%
 # Income prediction with partial observations
@@ -158,6 +157,8 @@
 ax = coef.plot.barh()
 ax.set_xlabel("Coefficient values")
 _ = ax.set_title("Coefficients of the linear regression excluding the ability feature")
+plt.tight_layout()
+plt.show()
 
 # %%
 # To compensate for the omitted variable, the model inflates the coefficient of

dev/_downloads/34b53ad148e36f98b6de8ddc15e3dfd3/plot_causal_interpretation.py

@@ -3,25 +3,35 @@
 Common pitfalls in the interpretation of coefficients of linear models
 ======================================================================
 
-In linear models, the target value is modeled as
-a linear combination of the features (see the :ref:`linear_model` User Guide
-section for a description of a set of linear models available in
-scikit-learn).
-Coefficients in multiple linear models represent the relationship between the
-given feature, :math:`X_i` and the target, :math:`y`, assuming that all the
-other features remain constant (`conditional dependence
-<https://en.wikipedia.org/wiki/Conditional_dependence>`_).
-This is different from plotting :math:`X_i` versus :math:`y` and fitting a
-linear relationship: in that case all possible values of the other features are
-taken into account in the estimation (marginal dependence).
+In linear models, the target value is modeled as a linear combination of the
+features (see the :ref:`linear_model` User Guide section for a description of a
+set of linear models available in scikit-learn). Coefficients in multiple linear
+models represent the relationship between the given feature, :math:`X_i` and the
+target, :math:`y`, assuming that all the other features remain constant
+(`conditional dependence
+<https://en.wikipedia.org/wiki/Conditional_dependence>`_). This is different
+from plotting :math:`X_i` versus :math:`y` and fitting a linear relationship: in
+that case all possible values of the other features are taken into account in
+the estimation (marginal dependence).
 
 This example will provide some hints in interpreting coefficient in linear
 models, pointing at problems that arise when either the linear model is not
 appropriate to describe the dataset, or when features are correlated.
 
+.. note::
+
+    Keep in mind that the features :math:`X` and the outcome :math:`y` are in
+    general the result of a data generating process that is unknown to us.
+    Machine learning models are trained to approximate the unobserved
+    mathematical function that links :math:`X` to :math:`y` from sample data. As
+    a result, any interpretation made about a model may not necessarily
+    generalize to the true data generating process. This is especially true when
+    the model is of bad quality or when the sample data is not representative of
+    the population.
+
 We will use data from the `"Current Population Survey"
-<https://www.openml.org/d/534>`_ from 1985 to predict
-wage as a function of various features such as experience, age, or education.
+<https://www.openml.org/d/534>`_ from 1985 to predict wage as a function of
+various features such as experience, age, or education.
 
 .. contents::
    :local:
@@ -729,18 +739,6 @@
 # See the :ref:`sphx_glr_auto_examples_inspection_plot_causal_interpretation.py`
 # for a simulated case of ability OVB.
 #
-# Warning: data and model quality
-# -------------------------------
-#
-# Keep in mind that the outcome `y` and features `X` are the product
-# of a data generating process that is hidden from us. Machine
-# learning models are trained to approximate the unobserved
-# mathematical function that links `X` to `y` from sample data. As a
-# result, any interpretation made about a model may not necessarily
-# generalize to the true data generating process. This is especially
-# true when the model is of bad quality or when the sample data is
-# not representative of the population.
-#
 # Lessons learned
 # ---------------
 #

dev/_downloads/521b554adefca348463adbbe047d7e99/plot_linear_model_coefficient_interpretation.py

@@ -15,7 +15,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "\n# Common pitfalls in the interpretation of coefficients of linear models\n\nIn linear models, the target value is modeled as\na linear combination of the features (see the `linear_model` User Guide\nsection for a description of a set of linear models available in\nscikit-learn).\nCoefficients in multiple linear models represent the relationship between the\ngiven feature, $X_i$ and the target, $y$, assuming that all the\nother features remain constant ([conditional dependence](https://en.wikipedia.org/wiki/Conditional_dependence)).\nThis is different from plotting $X_i$ versus $y$ and fitting a\nlinear relationship: in that case all possible values of the other features are\ntaken into account in the estimation (marginal dependence).\n\nThis example will provide some hints in interpreting coefficient in linear\nmodels, pointing at problems that arise when either the linear model is not\nappropriate to describe the dataset, or when features are correlated.\n\nWe will use data from the [\"Current Population Survey\"](https://www.openml.org/d/534) from 1985 to predict\nwage as a function of various features such as experience, age, or education.\n   :depth: 1\n"
+        "\n# Common pitfalls in the interpretation of coefficients of linear models\n\nIn linear models, the target value is modeled as a linear combination of the\nfeatures (see the `linear_model` User Guide section for a description of a\nset of linear models available in scikit-learn). Coefficients in multiple linear\nmodels represent the relationship between the given feature, $X_i$ and the\ntarget, $y$, assuming that all the other features remain constant\n([conditional dependence](https://en.wikipedia.org/wiki/Conditional_dependence)). This is different\nfrom plotting $X_i$ versus $y$ and fitting a linear relationship: in\nthat case all possible values of the other features are taken into account in\nthe estimation (marginal dependence).\n\nThis example will provide some hints in interpreting coefficient in linear\nmodels, pointing at problems that arise when either the linear model is not\nappropriate to describe the dataset, or when features are correlated.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Keep in mind that the features $X$ and the outcome $y$ are in\n    general the result of a data generating process that is unknown to us.\n    Machine learning models are trained to approximate the unobserved\n    mathematical function that links $X$ to $y$ from sample data. As\n    a result, any interpretation made about a model may not necessarily\n    generalize to the true data generating process. This is especially true when\n    the model is of bad quality or when the sample data is not representative of\n    the population.</p></div>\n\nWe will use data from the [\"Current Population Survey\"](https://www.openml.org/d/534) from 1985 to predict wage as a function of\nvarious features such as experience, age, or education.\n   :depth: 1\n"
       ]
     },
     {
@@ -693,7 +693,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "We observe that the AGE and EXPERIENCE coefficients are varying a lot\ndepending of the fold.\n\n## Wrong causal interpretation\n\nPolicy makers might want to know the effect of education on wage to assess\nwhether or not a certain policy designed to entice people to pursue more\neducation would make economic sense. While Machine Learning models are great\nfor measuring statistical associations, they are generally unable to infer\ncausal effects.\n\nIt might be tempting to look at the coefficient of education on wage from our\nlast model (or any model for that matter) and conclude that it captures the\ntrue effect of a change in the standardized education variable on wages.\n\nUnfortunately there are likely unobserved confounding variables that either\ninflate or deflate that coefficient. A confounding variable is a variable that\ncauses both EDUCATION and WAGE. One example of such variable is ability.\nPresumably, more able people are more likely to pursue education while at the\nsame time being more likely to earn a higher hourly wage at any level of\neducation. In this case, ability induces a positive [Omitted Variable Bias](https://en.wikipedia.org/wiki/Omitted-variable_bias) (OVB) on the EDUCATION\ncoefficient, thereby exaggerating the effect of education on wages.\n\nSee the `sphx_glr_auto_examples_inspection_plot_causal_interpretation.py`\nfor a simulated case of ability OVB.\n\n## Warning: data and model quality\n\nKeep in mind that the outcome `y` and features `X` are the product\nof a data generating process that is hidden from us. Machine\nlearning models are trained to approximate the unobserved\nmathematical function that links `X` to `y` from sample data. As a\nresult, any interpretation made about a model may not necessarily\ngeneralize to the true data generating process. This is especially\ntrue when the model is of bad quality or when the sample data is\nnot representative of the population.\n\n## Lessons learned\n\n* Coefficients must be scaled to the same unit of measure to retrieve\n  feature importance. Scaling them with the standard-deviation of the\n  feature is a useful proxy.\n* Coefficients in multivariate linear models represent the dependency\n  between a given feature and the target, **conditional** on the other\n  features.\n* Correlated features induce instabilities in the coefficients of linear\n  models and their effects cannot be well teased apart.\n* Different linear models respond differently to feature correlation and\n  coefficients could significantly vary from one another.\n* Inspecting coefficients across the folds of a cross-validation loop\n  gives an idea of their stability.\n* Coefficients are unlikely to have any causal meaning. They tend\n  to be biased by unobserved confounders.\n* Inspection tools may not necessarily provide insights on the true\n  data generating process.\n\n"
+        "We observe that the AGE and EXPERIENCE coefficients are varying a lot\ndepending of the fold.\n\n## Wrong causal interpretation\n\nPolicy makers might want to know the effect of education on wage to assess\nwhether or not a certain policy designed to entice people to pursue more\neducation would make economic sense. While Machine Learning models are great\nfor measuring statistical associations, they are generally unable to infer\ncausal effects.\n\nIt might be tempting to look at the coefficient of education on wage from our\nlast model (or any model for that matter) and conclude that it captures the\ntrue effect of a change in the standardized education variable on wages.\n\nUnfortunately there are likely unobserved confounding variables that either\ninflate or deflate that coefficient. A confounding variable is a variable that\ncauses both EDUCATION and WAGE. One example of such variable is ability.\nPresumably, more able people are more likely to pursue education while at the\nsame time being more likely to earn a higher hourly wage at any level of\neducation. In this case, ability induces a positive [Omitted Variable Bias](https://en.wikipedia.org/wiki/Omitted-variable_bias) (OVB) on the EDUCATION\ncoefficient, thereby exaggerating the effect of education on wages.\n\nSee the `sphx_glr_auto_examples_inspection_plot_causal_interpretation.py`\nfor a simulated case of ability OVB.\n\n## Lessons learned\n\n* Coefficients must be scaled to the same unit of measure to retrieve\n  feature importance. Scaling them with the standard-deviation of the\n  feature is a useful proxy.\n* Coefficients in multivariate linear models represent the dependency\n  between a given feature and the target, **conditional** on the other\n  features.\n* Correlated features induce instabilities in the coefficients of linear\n  models and their effects cannot be well teased apart.\n* Different linear models respond differently to feature correlation and\n  coefficients could significantly vary from one another.\n* Inspecting coefficients across the folds of a cross-validation loop\n  gives an idea of their stability.\n* Coefficients are unlikely to have any causal meaning. They tend\n  to be biased by unobserved confounders.\n* Inspection tools may not necessarily provide insights on the true\n  data generating process.\n\n"
       ]
     }
   ],

dev/_downloads/6f1e7a639e0699d6164445b55e6c116d/auto_examples_jupyter.zip

@@ -105,7 +105,7 @@
       },
       "outputs": [],
       "source": [
-        "import matplotlib.pyplot as plt\n\nmodel_coef = pd.Series(regressor_with_ability.coef_, index=features_names)\ncoef = pd.concat(\n    [true_coef[features_names], model_coef],\n    keys=[\"Coefficients of true generative model\", \"Model coefficients\"],\n    axis=1,\n)\nax = coef.plot.barh()\nax.set_xlabel(\"Coefficient values\")\nax.set_title(\"Coefficients of the linear regression including the ability features\")\nplt.tight_layout()\nplt.show()"
+        "import matplotlib.pyplot as plt\n\nmodel_coef = pd.Series(regressor_with_ability.coef_, index=features_names)\ncoef = pd.concat(\n    [true_coef[features_names], model_coef],\n    keys=[\"Coefficients of true generative model\", \"Model coefficients\"],\n    axis=1,\n)\nax = coef.plot.barh()\nax.set_xlabel(\"Coefficient values\")\nax.set_title(\"Coefficients of the linear regression including the ability features\")\n_ = plt.tight_layout()"
       ]
     },
     {
@@ -141,7 +141,7 @@
       },
       "outputs": [],
       "source": [
-        "model_coef = pd.Series(regressor_without_ability.coef_, index=features_names)\ncoef = pd.concat(\n    [true_coef[features_names], model_coef],\n    keys=[\"Coefficients of true generative model\", \"Model coefficients\"],\n    axis=1,\n)\nax = coef.plot.barh()\nax.set_xlabel(\"Coefficient values\")\n_ = ax.set_title(\"Coefficients of the linear regression excluding the ability feature\")"
+        "model_coef = pd.Series(regressor_without_ability.coef_, index=features_names)\ncoef = pd.concat(\n    [true_coef[features_names], model_coef],\n    keys=[\"Coefficients of true generative model\", \"Model coefficients\"],\n    axis=1,\n)\nax = coef.plot.barh()\nax.set_xlabel(\"Coefficient values\")\n_ = ax.set_title(\"Coefficients of the linear regression excluding the ability feature\")\nplt.tight_layout()\nplt.show()"
       ]
     },
     {