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

Author: sklearn-ci

dev/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 6cd47419ab6a7583ffff2c1811ceb650
+config: 5744e0ab801bd7d341c57909164479c2
 tags: 645f666f9bcd5a90fca523b33c5a78b7

dev/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip

@@ -44,7 +44,8 @@
 #
 # The decision classifier has an attribute called ``tree_`` which allows access
 # to low level attributes such as ``node_count``, the total number of nodes,
-# and ``max_depth``, the maximal depth of the tree. It also stores the
+# and ``max_depth``, the maximal depth of the tree. The tree_.compute_node_depths()
+# method computes the depth of each node in the tree. `tree_` also stores the
 # entire binary tree structure, represented as a number of parallel arrays. The
 # i-th element of each array holds information about the node ``i``. Node 0 is
 # the tree's root. Some of the arrays only apply to either leaves or split
@@ -63,6 +64,10 @@
 #   - ``n_node_samples[i]``: the number of training samples reaching node
 #     ``i``
 #   - ``impurity[i]``: the impurity at node ``i``
+#   - ``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
+#     class j and output k.
 #
 # 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
@@ -73,6 +78,7 @@
 children_right = clf.tree_.children_right
 feature = clf.tree_.feature
 threshold = clf.tree_.threshold
+values = clf.tree_.value
 
 node_depth = np.zeros(shape=n_nodes, dtype=np.int64)
 is_leaves = np.zeros(shape=n_nodes, dtype=bool)
@@ -100,13 +106,13 @@
 for i in range(n_nodes):
     if is_leaves[i]:
         print(
-            "{space}node={node} is a leaf node.".format(
-                space=node_depth[i] * "\t", node=i
+            "{space}node={node} is a leaf node with value={value}.".format(
+                space=node_depth[i] * "\t", node=i, value=values[i]
             )
         )
     else:
         print(
-            "{space}node={node} is a split node: "
+            "{space}node={node} is a split node with value={value}: "
             "go to node {left} if X[:, {feature}] <= {threshold} "
             "else to node {right}.".format(
                 space=node_depth[i] * "\t",
@@ -115,9 +121,30 @@
                 feature=feature[i],
                 threshold=threshold[i],
                 right=children_right[i],
+                value=values[i],
             )
         )
 
+# %%
+# 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.
+#
+# For example, in the above tree built on the iris dataset, 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]``
+# 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
+# multi-output problems. The `value` array at each node would just be a 2D
+# array instead.
+
 ##############################################################################
 # We can compare the above output to the plot of the decision tree.
 

dev/_downloads/21a6ff17ef2837fe1cd49e63223a368d/plot_unveil_tree_structure.py

@@ -40,7 +40,7 @@
       "cell_type": "markdown",
       "metadata": {},
       "source": [
-        "## Tree structure\n\nThe decision classifier has an attribute called ``tree_`` which allows access\nto low level attributes such as ``node_count``, the total number of nodes,\nand ``max_depth``, the maximal depth of the tree. It also stores the\nentire binary tree structure, represented as a number of parallel arrays. The\ni-th element of each array holds information about the node ``i``. Node 0 is\nthe tree's root. Some of the arrays only apply to either leaves or split\nnodes. In this case the values of the nodes of the other type is arbitrary.\nFor example, the arrays ``feature`` and ``threshold`` only apply to split\nnodes. The values for leaf nodes in these arrays are therefore arbitrary.\n\nAmong these arrays, we have:\n\n  - ``children_left[i]``: id of the left child of node ``i`` or -1 if leaf\n    node\n  - ``children_right[i]``: id of the right child of node ``i`` or -1 if leaf\n    node\n  - ``feature[i]``: feature used for splitting node ``i``\n  - ``threshold[i]``: threshold value at node ``i``\n  - ``n_node_samples[i]``: the number of training samples reaching node\n    ``i``\n  - ``impurity[i]``: the impurity at node ``i``\n\nUsing the arrays, we can traverse the tree structure to compute various\nproperties. Below, we will compute the depth of each node and whether or not\nit is a leaf.\n\n"
+        "## Tree structure\n\nThe decision classifier has an attribute called ``tree_`` which allows access\nto low level attributes such as ``node_count``, the total number of nodes,\nand ``max_depth``, the maximal depth of the tree. The tree_.compute_node_depths()\nmethod computes the depth of each node in the tree. `tree_` also stores the\nentire binary tree structure, represented as a number of parallel arrays. The\ni-th element of each array holds information about the node ``i``. Node 0 is\nthe tree's root. Some of the arrays only apply to either leaves or split\nnodes. In this case the values of the nodes of the other type is arbitrary.\nFor example, the arrays ``feature`` and ``threshold`` only apply to split\nnodes. The values for leaf nodes in these arrays are therefore arbitrary.\n\nAmong these arrays, we have:\n\n  - ``children_left[i]``: id of the left child of node ``i`` or -1 if leaf\n    node\n  - ``children_right[i]``: id of the right child of node ``i`` or -1 if leaf\n    node\n  - ``feature[i]``: feature used for splitting node ``i``\n  - ``threshold[i]``: threshold value at node ``i``\n  - ``n_node_samples[i]``: the number of training samples reaching node\n    ``i``\n  - ``impurity[i]``: the impurity at node ``i``\n  - ``weighted_n_node_samples[i]``: the weighted number of training samples\n    reaching node ``i``\n  - ``value[i, j, k]``: the summary of the training samples that reached node i for\n    class j and output k.\n\nUsing the arrays, we can traverse the tree structure to compute various\nproperties. Below, we will compute the depth of each node and whether or not\nit is a leaf.\n\n"
       ]
     },
     {
@@ -51,7 +51,14 @@
       },
       "outputs": [],
       "source": [
-        "n_nodes = clf.tree_.node_count\nchildren_left = clf.tree_.children_left\nchildren_right = clf.tree_.children_right\nfeature = clf.tree_.feature\nthreshold = clf.tree_.threshold\n\nnode_depth = np.zeros(shape=n_nodes, dtype=np.int64)\nis_leaves = np.zeros(shape=n_nodes, dtype=bool)\nstack = [(0, 0)]  # start with the root node id (0) and its depth (0)\nwhile len(stack) > 0:\n    # `pop` ensures each node is only visited once\n    node_id, depth = stack.pop()\n    node_depth[node_id] = depth\n\n    # If the left and right child of a node is not the same we have a split\n    # node\n    is_split_node = children_left[node_id] != children_right[node_id]\n    # If a split node, append left and right children and depth to `stack`\n    # so we can loop through them\n    if is_split_node:\n        stack.append((children_left[node_id], depth + 1))\n        stack.append((children_right[node_id], depth + 1))\n    else:\n        is_leaves[node_id] = True\n\nprint(\n    \"The binary tree structure has {n} nodes and has \"\n    \"the following tree structure:\\n\".format(n=n_nodes)\n)\nfor i in range(n_nodes):\n    if is_leaves[i]:\n        print(\n            \"{space}node={node} is a leaf node.\".format(\n                space=node_depth[i] * \"\\t\", node=i\n            )\n        )\n    else:\n        print(\n            \"{space}node={node} is a split node: \"\n            \"go to node {left} if X[:, {feature}] <= {threshold} \"\n            \"else to node {right}.\".format(\n                space=node_depth[i] * \"\\t\",\n                node=i,\n                left=children_left[i],\n                feature=feature[i],\n                threshold=threshold[i],\n                right=children_right[i],\n            )\n        )"
+        "n_nodes = clf.tree_.node_count\nchildren_left = clf.tree_.children_left\nchildren_right = clf.tree_.children_right\nfeature = clf.tree_.feature\nthreshold = clf.tree_.threshold\nvalues = clf.tree_.value\n\nnode_depth = np.zeros(shape=n_nodes, dtype=np.int64)\nis_leaves = np.zeros(shape=n_nodes, dtype=bool)\nstack = [(0, 0)]  # start with the root node id (0) and its depth (0)\nwhile len(stack) > 0:\n    # `pop` ensures each node is only visited once\n    node_id, depth = stack.pop()\n    node_depth[node_id] = depth\n\n    # If the left and right child of a node is not the same we have a split\n    # node\n    is_split_node = children_left[node_id] != children_right[node_id]\n    # If a split node, append left and right children and depth to `stack`\n    # so we can loop through them\n    if is_split_node:\n        stack.append((children_left[node_id], depth + 1))\n        stack.append((children_right[node_id], depth + 1))\n    else:\n        is_leaves[node_id] = True\n\nprint(\n    \"The binary tree structure has {n} nodes and has \"\n    \"the following tree structure:\\n\".format(n=n_nodes)\n)\nfor i in range(n_nodes):\n    if is_leaves[i]:\n        print(\n            \"{space}node={node} is a leaf node with value={value}.\".format(\n                space=node_depth[i] * \"\\t\", node=i, value=values[i]\n            )\n        )\n    else:\n        print(\n            \"{space}node={node} is a split node with value={value}: \"\n            \"go to node {left} if X[:, {feature}] <= {threshold} \"\n            \"else to node {right}.\".format(\n                space=node_depth[i] * \"\\t\",\n                node=i,\n                left=children_left[i],\n                feature=feature[i],\n                threshold=threshold[i],\n                right=children_right[i],\n                value=values[i],\n            )\n        )"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## What is the values array used here?\nThe `tree_.value` array is a 3D array of shape\n[``n_nodes``, ``n_classes``, ``n_outputs``] which provides the count of samples\nreaching a node for each class and for each output. Each node has a ``value``\narray which is the number of weighted samples reaching this\nnode for each output and class.\n\nFor example, in the above tree built on the iris dataset, the root node has\n``value = [37, 34, 41]``, indicating there are 37 samples\nof class 0, 34 samples of class 1, and 41 samples of class 2 at the root node.\nTraversing the tree, the samples are split and as a result, the ``value`` array\nreaching each node changes. The left child of the root node has ``value = [37, 0, 0]``\nbecause all 37 samples in the left child node are from class 0.\n\nNote: In this example, `n_outputs=1`, but the tree classifier can also handle\nmulti-output problems. The `value` array at each node would just be a 2D\narray instead.\n\n"
       ]
     },
     {