DOC Fix tree explanation of tree_.value in example (scikit-learn#29331)

Co-authored-by: Arturo Amor <86408019+ArturoAmorQ@users.noreply.github.com>
Co-authored-by: Loïc Estève <loic.esteve@ymail.com>

Author: 3 people

doc/whats_new/v1.4.rst

@@ -29,6 +29,15 @@ Version 1.4.1
 
 **February 2024**
 
+Changed models
+--------------
+
+- |API| The `tree_.value` attribute in :class:`tree.DecisionTreeClassifier`,
+  :class:`tree.DecisionTreeRegressor`, :class:`tree.ExtraTreeClassifier` and
+  :class:`tree.ExtraTreeRegressor` changed from an weighted absolute count
+  of number of samples to a weighted fraction of the total number of samples.
+  :pr:`27639` by :user:`Samuel Ronsin <samronsin>`.
+
 Metadata Routing
 ----------------
 

examples/tree/plot_unveil_tree_structure.py

@@ -68,7 +68,8 @@
 #   - ``weighted_n_node_samples[i]``: the weighted number of training samples
 #     reaching node ``i``
 #   - ``value[i, j, k]``: the summary of the training samples that reached node i for
-#     output j and class k (for regression tree, class is set to 1).
+#     output j and class k (for regression tree, class is set to 1). See below
+#     for more information about ``value``.
 #
 # Using the arrays, we can traverse the tree structure to compute various
 # properties. Below, we will compute the depth of each node and whether or not
@@ -108,7 +109,7 @@
     if is_leaves[i]:
         print(
             "{space}node={node} is a leaf node with value={value}.".format(
-                space=node_depth[i] * "\t", node=i, value=values[i]
+                space=node_depth[i] * "\t", node=i, value=np.around(values[i], 3)
             )
         )
     else:
@@ -122,24 +123,36 @@
                 feature=feature[i],
                 threshold=threshold[i],
                 right=children_right[i],
-                value=values[i],
+                value=np.around(values[i], 3),
             )
         )
 
 # %%
 # What is the values array used here?
 # -----------------------------------
 # The `tree_.value` array is a 3D array of shape
-# [``n_nodes``, ``n_classes``, ``n_outputs``] which provides the count of samples
-# reaching a node for each class and for each output. Each node has a ``value``
-# array which is the number of weighted samples reaching this
-# node for each output and class.
+# [``n_nodes``, ``n_classes``, ``n_outputs``] which provides the proportion of samples
+# reaching a node for each class and for each output.
+# Each node has a ``value`` array which is the proportion of weighted samples reaching
+# this node for each output and class with respect to the parent node.
+#
+# One could convert this to the absolute weighted number of samples reaching a node,
+# by multiplying this number by `tree_.weighted_n_node_samples[node_idx]` for the
+# given node. Note sample weights are not used in this example, so the weighted
+# number of samples is the number of samples reaching the node because each sample
+# has a weight of 1 by default.
 #
 # For example, in the above tree built on the iris dataset, the root node has
-# ``value = [37, 34, 41]``, indicating there are 37 samples
+# ``value = [0.33, 0.304, 0.366]`` indicating there are 33% of class 0 samples,
+# 30.4% of class 1 samples, and 36.6% of class 2 samples at the root node. One can
+# convert this to the absolute number of samples by multiplying by the number of
+# samples reaching the root node, which is `tree_.weighted_n_node_samples[0]`.
+# Then the root node has ``value = [37, 34, 41]``, indicating there are 37 samples
 # of class 0, 34 samples of class 1, and 41 samples of class 2 at the root node.
+#
 # Traversing the tree, the samples are split and as a result, the ``value`` array
-# reaching each node changes. The left child of the root node has ``value = [37, 0, 0]``
+# reaching each node changes. The left child of the root node has ``value = [1., 0, 0]``
+# (or ``value = [37, 0, 0]`` when converted to the absolute number of samples)
 # because all 37 samples in the left child node are from class 0.
 #
 # Note: In this example, `n_outputs=1`, but the tree classifier can also handle
@@ -148,8 +161,10 @@
 
 ##############################################################################
 # We can compare the above output to the plot of the decision tree.
+# Here, we show the proportions of samples of each class that reach each
+# node corresponding to the actual elements of `tree_.value` array.
 
-tree.plot_tree(clf)
+tree.plot_tree(clf, proportion=True)
 plt.show()
 
 ##############################################################################