From 006e5d8e274d50b3636b68cdee2d336b11ed8c24 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 14:49:43 -0800 Subject: [PATCH 01/16] add xai example Signed-off-by: Jana Gagacheva --- .../databricks/kumo_tabular_quickstart.ipynb | 82 ++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/examples/databricks/kumo_tabular_quickstart.ipynb b/examples/databricks/kumo_tabular_quickstart.ipynb index 00eb0c3be..bfa126a2b 100644 --- a/examples/databricks/kumo_tabular_quickstart.ipynb +++ b/examples/databricks/kumo_tabular_quickstart.ipynb @@ -572,6 +572,86 @@ "2. The printed line counts the correct predictions for the same 60 products as Example 1, from the same context rows, so it matches Example 1's count." ] }, + { + "cell_type": "markdown", + "id": "723085f0ff6f44b5b0dfe42d2b5ceb5c", + "metadata": {}, + "source": "### Example 4: Explain the predictions\n\nThe earlier examples ask what; this one asks why.\nExplanations are available with NIM version 1.1+ and client version 1.1.0+.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples, the labelled rows sent with the request. Each column's values are split into cohorts (value ranges or categories). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the row's own columns — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 4.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 3 again with the `EXPLAIN` prefix, from the same context rows, for the first 25 of its 60 products:\n\n```\nEXPLAIN PREDICT products.Color ← also explain each prediction\nFOR EACH products.ProductID ← one prediction per product\n```" + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c2b144db005e4007b736b07327635d98", + "metadata": {}, + "outputs": [], + "source": [ + "# The first 25 of the 60 products Example 3 asked about.\n", + "to_explain = ask.head(25)\n", + "request = PredictiveQuery(\n", + " f'EXPLAIN PREDICT products.{TARGET} FOR EACH products.ProductID', schema\n", + ").materialize(\n", + " predict=to_explain.drop(columns=[TARGET, 'predicted']), model=model\n", + ")\n", + "result = client.predict(request, model=model)\n", + "\n", + "columns = result.explanations.columns.to_pandas()\n", + "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", + "display(columns)\n", + "\n", + "# How does the product line relate to the color? The class most_common is the\n", + "# most common color; each other color has rows of its own.\n", + "line = (columns['column'] == 'ProductLine') & (columns['class'] == most_common)\n", + "display(columns[line])\n", + "\n", + "# What drove the first product's prediction? A prediction carries a gradient\n", + "# for every value the model read, for every color, so the cell keeps the 10\n", + "# largest for the color Example 3 predicted for it.\n", + "gradients = result.explanations.gradients.to_pandas()\n", + "first = gradients[\n", + " (gradients['id'] == to_explain['ProductID'][0])\n", + " & (gradients['output'] == f'probability_{to_explain[\"predicted\"][0]}')\n", + "]\n", + "display(first.loc[first['gradient'].abs().nlargest(10).index])" + ] + }, + { + "cell_type": "markdown", + "id": "5e62cda0a14d4db5a8bcf0d7421b5be6", + "metadata": {}, + "source": [ + "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the products of one color from those of the others. The gradients come from the model, for each product, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." + ] + }, + { + "cell_type": "markdown", + "id": "98b3f19452054386a12523a3856674b7", + "metadata": {}, + "source": [ + "#### 4.2 Ask with outputs\n", + "\n", + "The `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\n", + "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "6b99b712a6394627adea279bbf9416ea", + "metadata": {}, + "outputs": [], + "source": [ + "# The same request and explanations, without the EXPLAIN prefix.\n", + "request = PredictiveQuery(\n", + " f'PREDICT products.{TARGET} FOR EACH products.ProductID', schema\n", + ").materialize(\n", + " predict=to_explain.drop(columns=[TARGET, 'predicted']), model=model\n", + ")\n", + "result = client.predict(\n", + " request, model=model, outputs=['prediction', 'explanation']\n", + ")\n", + "print(f'{len(result.explanations.gradients)} predictions explained.')" + ] + }, { "cell_type": "markdown", "id": "35191b5835272b7849ed573c1de6294e", @@ -685,4 +765,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file From 91ca5d83f8435d4822a0cedaa68d09a10af8c048 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Wed, 4 Nov 2026 16:43:16 -0800 Subject: [PATCH 02/16] update to latest Signed-off-by: Jana Gagacheva --- .../databricks/kumo_tabular_quickstart.ipynb | 113 +++++++++++++++--- 1 file changed, 94 insertions(+), 19 deletions(-) diff --git a/examples/databricks/kumo_tabular_quickstart.ipynb b/examples/databricks/kumo_tabular_quickstart.ipynb index bfa126a2b..62018df9d 100644 --- a/examples/databricks/kumo_tabular_quickstart.ipynb +++ b/examples/databricks/kumo_tabular_quickstart.ipynb @@ -576,14 +576,26 @@ "cell_type": "markdown", "id": "723085f0ff6f44b5b0dfe42d2b5ceb5c", "metadata": {}, - "source": "### Example 4: Explain the predictions\n\nThe earlier examples ask what; this one asks why.\nExplanations are available with NIM version 1.1+ and client version 1.1.0+.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples, the labelled rows sent with the request. Each column's values are split into cohorts (value ranges or categories). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the row's own columns — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 4.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 3 again with the `EXPLAIN` prefix, from the same context rows, for the first 25 of its 60 products:\n\n```\nEXPLAIN PREDICT products.Color ← also explain each prediction\nFOR EACH products.ProductID ← one prediction per product\n```" + "source": [ + "### Example 4: Explain the predictions\n", + "\n", + "We predicted the missing product colors. Now we'll explore patterns in the labelled examples and inspect how one product's prediction responds to small input changes.\n", + "\n", + "Explanations are available with NIM version 1.1+ and client version 1.1.0+.\n", + "The result carries explanations at two levels:\n", + "\n", + "- `result.explanations.columns`, computed by the client from the labelled examples sent with the request. It groups products by ranges or categories in each column. Each group reports its share of the examples and the fraction with each color.\n", + "- `result.explanations.gradients`, returned by the model for each explained product. A gradient describes how a predicted color probability responds to a small change in a preprocessed numerical input. It does not measure how much that input contributed to the prediction.\n", + "\n", + "#### 4.1 Ask with the EXPLAIN prefix\n", + "\n", + "Ask the question of Example 3 again with `EXPLAIN`, using the same context rows, for the first 25 of its 60 products." + ] }, { "cell_type": "code", - "execution_count": null, "id": "c2b144db005e4007b736b07327635d98", "metadata": {}, - "outputs": [], "source": [ "# The first 25 of the 60 products Example 3 asked about.\n", "to_explain = ask.head(25)\n", @@ -592,34 +604,97 @@ ").materialize(\n", " predict=to_explain.drop(columns=[TARGET, 'predicted']), model=model\n", ")\n", - "result = client.predict(request, model=model)\n", + "result = client.predict(request, model=model)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "2d235bbbc5014c188350db902322dac1", + "metadata": {}, + "source": [ + "**What patterns do we see in the labelled examples?**\n", "\n", - "columns = result.explanations.columns.to_pandas()\n", - "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", - "display(columns)\n", + "The column analysis groups products by ranges or categories in each column. For example, `ProductLine` groups products by their product line. For each group and color, `share` is the fraction of examples in the group, and `mean` is the fraction of that group with that color. A value of `0.30` means 30%." + ] + }, + { + "cell_type": "code", + "id": "1c6ab73514aa4619ae9920119137e7f8", + "metadata": {}, + "source": [ + "columns = result.explanations.columns.to_pandas().drop(columns='score')\n", + "display(columns)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "9e8280d327e342b9b20d39fe5a61d0ec", + "metadata": {}, + "source": [ + "**How does product line relate to color?**\n", "\n", - "# How does the product line relate to the color? The class most_common is the\n", - "# most common color; each other color has rows of its own.\n", - "line = (columns['column'] == 'ProductLine') & (columns['class'] == most_common)\n", - "display(columns[line])\n", + "Zoom in on `ProductLine` for the most common color in the labelled examples." + ] + }, + { + "cell_type": "code", + "id": "9a7ea75bd12541bc951cd34c2e3581c0", + "metadata": {}, + "source": [ + "line = columns[\n", + " (columns['column'] == 'ProductLine')\n", + " & (columns['class'] == most_common)\n", + "]\n", + "display(line)" + ], + "execution_count": null, + "outputs": [] + }, + { + "cell_type": "markdown", + "id": "6283031b7cd94cac9e8ed6589febbcf4", + "metadata": {}, + "source": [ + "Compare `mean` across the product lines: which have a larger fraction of products with this color? Check `share` to see how much of the data each line represents.\n", "\n", - "# What drove the first product's prediction? A prediction carries a gradient\n", - "# for every value the model read, for every color, so the cell keeps the 10\n", - "# largest for the color Example 3 predicted for it.\n", + "This shows a pattern in the labelled examples. It does not establish why a particular product received its predicted color.\n", + "\n", + "**How would small input changes affect one product's predicted color probability?**\n", + "\n", + "Gradients describe how the model output responds to small changes near the current input values. They use the model's numerical inputs after preprocessing, which may differ from the original columns.\n", + "\n", + "For the first product, inspect ten entries with the largest absolute gradients for the color predicted in Example 3." + ] + }, + { + "cell_type": "code", + "id": "a6bdaedb262542d3891889e49ae4cf8e", + "metadata": {}, + "source": [ "gradients = result.explanations.gradients.to_pandas()\n", "first = gradients[\n", - " (gradients['id'] == to_explain['ProductID'][0])\n", - " & (gradients['output'] == f'probability_{to_explain[\"predicted\"][0]}')\n", + " (gradients['id'] == to_explain['ProductID'].iloc[0])\n", + " & (gradients['output'] == f'probability_{to_explain[\"predicted\"].iloc[0]}')\n", "]\n", "display(first.loc[first['gradient'].abs().nlargest(10).index])" - ] + ], + "execution_count": null, + "outputs": [] }, { "cell_type": "markdown", "id": "5e62cda0a14d4db5a8bcf0d7421b5be6", "metadata": {}, "source": [ - "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the products of one color from those of the others. The gradients come from the model, for each product, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." + "A positive gradient means a small increase in that preprocessed value would locally increase the predicted probability of this color; a negative gradient means it would decrease it.\n", + "\n", + "The sizes depend on the input scales, so these ten entries are not necessarily the inputs that contributed most to the prediction.\n", + "\n", + "Use this table to investigate sensitivity—for example, when checking a possibly incorrect product attribute. Correct the value using the source record, rerun the prediction, and check whether the predicted color or its probability changes. This checks how the model responds to a data correction; it does not show that changing an attribute would change the product's actual color." ] }, { @@ -765,4 +840,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} From 3901240b26c2b61f80281002d5787902fd750278 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Wed, 4 Nov 2026 16:44:49 -0800 Subject: [PATCH 03/16] small fix Signed-off-by: Jana Gagacheva --- .../databricks/kumo_tabular_quickstart.ipynb | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/examples/databricks/kumo_tabular_quickstart.ipynb b/examples/databricks/kumo_tabular_quickstart.ipynb index 62018df9d..16709ac09 100644 --- a/examples/databricks/kumo_tabular_quickstart.ipynb +++ b/examples/databricks/kumo_tabular_quickstart.ipynb @@ -594,8 +594,10 @@ }, { "cell_type": "code", + "execution_count": null, "id": "c2b144db005e4007b736b07327635d98", "metadata": {}, + "outputs": [], "source": [ "# The first 25 of the 60 products Example 3 asked about.\n", "to_explain = ask.head(25)\n", @@ -605,9 +607,7 @@ " predict=to_explain.drop(columns=[TARGET, 'predicted']), model=model\n", ")\n", "result = client.predict(request, model=model)" - ], - "execution_count": null, - "outputs": [] + ] }, { "cell_type": "markdown", @@ -616,19 +616,19 @@ "source": [ "**What patterns do we see in the labelled examples?**\n", "\n", - "The column analysis groups products by ranges or categories in each column. For example, `ProductLine` groups products by their product line. For each group and color, `share` is the fraction of examples in the group, and `mean` is the fraction of that group with that color. A value of `0.30` means 30%." + "The column analysis groups products by ranges or categories in each column. For example, `ProductLine` groups products by their product line. For each group and color, `share` is the fraction of examples in the group, and `mean` is the fraction of that group with that color." ] }, { "cell_type": "code", + "execution_count": null, "id": "1c6ab73514aa4619ae9920119137e7f8", "metadata": {}, + "outputs": [], "source": [ "columns = result.explanations.columns.to_pandas().drop(columns='score')\n", "display(columns)" - ], - "execution_count": null, - "outputs": [] + ] }, { "cell_type": "markdown", @@ -642,17 +642,17 @@ }, { "cell_type": "code", + "execution_count": null, "id": "9a7ea75bd12541bc951cd34c2e3581c0", "metadata": {}, + "outputs": [], "source": [ "line = columns[\n", " (columns['column'] == 'ProductLine')\n", " & (columns['class'] == most_common)\n", "]\n", "display(line)" - ], - "execution_count": null, - "outputs": [] + ] }, { "cell_type": "markdown", @@ -672,8 +672,10 @@ }, { "cell_type": "code", + "execution_count": null, "id": "a6bdaedb262542d3891889e49ae4cf8e", "metadata": {}, + "outputs": [], "source": [ "gradients = result.explanations.gradients.to_pandas()\n", "first = gradients[\n", @@ -681,9 +683,7 @@ " & (gradients['output'] == f'probability_{to_explain[\"predicted\"].iloc[0]}')\n", "]\n", "display(first.loc[first['gradient'].abs().nlargest(10).index])" - ], - "execution_count": null, - "outputs": [] + ] }, { "cell_type": "markdown", From 5499c049dd221d7d31d685ec936e78e9f29d5799 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Thu, 5 Nov 2026 10:09:01 -0800 Subject: [PATCH 04/16] remove one drop Signed-off-by: Jana Gagacheva --- examples/databricks/kumo_tabular_quickstart.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/databricks/kumo_tabular_quickstart.ipynb b/examples/databricks/kumo_tabular_quickstart.ipynb index 16709ac09..10dbd9ae8 100644 --- a/examples/databricks/kumo_tabular_quickstart.ipynb +++ b/examples/databricks/kumo_tabular_quickstart.ipynb @@ -626,7 +626,7 @@ "metadata": {}, "outputs": [], "source": [ - "columns = result.explanations.columns.to_pandas().drop(columns='score')\n", + "columns = result.explanations.columns.to_pandas()\n", "display(columns)" ] }, From 72675f2032b48c65e5fc3ae98f55366c0c757597 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Thu, 5 Nov 2026 10:29:20 -0800 Subject: [PATCH 05/16] fix wording and stuff Signed-off-by: Jana Gagacheva --- examples/databricks/kumo_tabular_quickstart.ipynb | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/examples/databricks/kumo_tabular_quickstart.ipynb b/examples/databricks/kumo_tabular_quickstart.ipynb index 10dbd9ae8..aebe6bc0a 100644 --- a/examples/databricks/kumo_tabular_quickstart.ipynb +++ b/examples/databricks/kumo_tabular_quickstart.ipynb @@ -648,8 +648,7 @@ "outputs": [], "source": [ "line = columns[\n", - " (columns['column'] == 'ProductLine')\n", - " & (columns['class'] == most_common)\n", + " (columns['column'] == 'ProductLine') & (columns['class'] == most_common)\n", "]\n", "display(line)" ] @@ -705,7 +704,7 @@ "#### 4.2 Ask with outputs\n", "\n", "The `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\n", - "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:" + "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'probabilities', 'explanation']`:" ] }, { @@ -722,7 +721,7 @@ " predict=to_explain.drop(columns=[TARGET, 'predicted']), model=model\n", ")\n", "result = client.predict(\n", - " request, model=model, outputs=['prediction', 'explanation']\n", + " request, model=model, outputs=['prediction', 'probabilities', 'explanation']\n", ")\n", "print(f'{len(result.explanations.gradients)} predictions explained.')" ] From 64a12d36fcfd7153ad76ccdbc887cb9341914728 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 10:48:48 -0800 Subject: [PATCH 06/16] extend explanations in dbx notebook Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 8a6f1b9c8..ad069289e 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -464,6 +464,10 @@ "\n", "A comparison after the target turns it into a yes-or-no question: `COUNT(sales_order_headers.*, 0, 90, days) = 0` asks whether a customer places no order in the next 90 days.\n", "A `WHERE` inside the aggregation counts only some rows: `COUNT(sales_order_headers.* WHERE sales_order_headers.TotalDue > 1000, 0, 90, days)` counts only orders over $1,000.\n", + "\n", + "**Explanations**\n", + "\n", + "`EXPLAIN PREDICT …` returns the same predictions, and also explanations of them; see Example 5.\n", "" ] }, @@ -884,6 +888,76 @@ "This lets a team ask questions about the measures it already defines in metric views." ] }, + { + "cell_type": "markdown", + "id": "620b2a07b418435c90d8e7dca1fd869f", + "metadata": {}, + "source": [ + "### Example 5: Explain the predictions\n", + "\n", + "The earlier examples ask who; this one asks why.\n", + "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", + "\n", + "```\n", + "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", + "FOR EACH customers.CustomerID ← one prediction per customer\n", + "```\n", + "\n", + "The result carries explanations at two levels:\n", + "\n", + "- `result.explanations.columns`, computed by the client from the context examples the model read: each column of the linked tables is split into cohorts, such as value ranges, categories or time before the prediction time, and each cohort has its share of the customers and the share of them that placed no order. Each column gets a score.\n", + "- `result.explanations.gradients`, from the model, for each of the 25 customers: which tables and columns pushed that customer's probability up or down." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b2ee7bc6cf2e43d8b7e7e3207117ea3d", + "metadata": {}, + "outputs": [], + "source": [ + "# The 25 customers Example 1 rated riskiest, riskiest first.\n", + "riskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\n", + "request = PredictiveQuery(\n", + " 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", + " 'FOR EACH customers.CustomerID',\n", + " schema,\n", + ").materialize(\n", + " indices=riskiest_25, anchor_time=PAST, num_context_samples=5000\n", + ")\n", + "result = client.predict(request, model=model)\n", + "\n", + "columns = result.explanations.columns.to_pandas()\n", + "# The class True is placing no order.\n", + "no_order = columns[columns['class'].astype(str) == 'True']\n", + "scores = no_order.drop_duplicates(['table', 'hop', 'column'])\n", + "display(scores[['table', 'hop', 'column', 'score']])\n", + "# The cohorts of the highest-scoring column.\n", + "display(no_order.merge(scores[['table', 'hop', 'column']].head(1)))\n", + "\n", + "gradients = result.explanations.gradients.to_pandas()\n", + "first = gradients[\n", + " (gradients['id'] == riskiest_25[0])\n", + " & (gradients['output'] == 'probability_True')\n", + "]\n", + "display(first.loc[first['gradient'].abs().nlargest(10).index])" + ] + }, + { + "cell_type": "markdown", + "id": "a7b667632bfa4a48be8e94665ef115ca", + "metadata": {}, + "source": [ + "How to interpret the result:\n", + "\n", + "1. The first table lists the columns by `score`, highest first: over the context examples, the more the share that placed no order differs between a column's cohorts, the higher the score. The scores add up to 1.\n", + "2. The second table shows the cohorts of the highest-scoring column: `share` is the cohort's share of the customers, and `mean` the share of them that placed no order. `COUNT(*)` is the number of a customer's linked rows, such as orders.\n", + "3. Example 1 compared the model with the days since each customer's last order. Here that signal is `OrderDate`, with cohorts by how long before the prediction time the orders were placed; the first table shows where it ranks, and which other columns go with stopping to order.\n", + "4. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n", + "\n", + "The column table says what goes with stopping to order across many customers; the gradients say what drove the prediction for one." + ] + }, { "cell_type": "markdown", "id": "064697a1bad1b5348afae26f2d9acec4", From 6ac9aaad54b6af451c5e449e88d7f5b4dee0c5a7 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 11:03:38 -0800 Subject: [PATCH 07/16] fix notebook Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 27 ++++++------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index ad069289e..b57993024 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -922,18 +922,16 @@ " 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", " 'FOR EACH customers.CustomerID',\n", " schema,\n", - ").materialize(\n", - " indices=riskiest_25, anchor_time=PAST, num_context_samples=5000\n", - ")\n", + ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", "result = client.predict(request, model=model)\n", "\n", "columns = result.explanations.columns.to_pandas()\n", - "# The class True is placing no order.\n", - "no_order = columns[columns['class'].astype(str) == 'True']\n", - "scores = no_order.drop_duplicates(['table', 'hop', 'column'])\n", - "display(scores[['table', 'hop', 'column', 'score']])\n", - "# The cohorts of the highest-scoring column.\n", - "display(no_order.merge(scores[['table', 'hop', 'column']].head(1)))\n", + "display(columns)\n", + "\n", + "# How does order recency relate to stopping to order? The class True is the\n", + "# \"placed no order\" answer; the False rows are its mirror image.\n", + "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", + "display(columns[recency])\n", "\n", "gradients = result.explanations.gradients.to_pandas()\n", "first = gradients[\n", @@ -947,16 +945,7 @@ "cell_type": "markdown", "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, - "source": [ - "How to interpret the result:\n", - "\n", - "1. The first table lists the columns by `score`, highest first: over the context examples, the more the share that placed no order differs between a column's cohorts, the higher the score. The scores add up to 1.\n", - "2. The second table shows the cohorts of the highest-scoring column: `share` is the cohort's share of the customers, and `mean` the share of them that placed no order. `COUNT(*)` is the number of a customer's linked rows, such as orders.\n", - "3. Example 1 compared the model with the days since each customer's last order. Here that signal is `OrderDate`, with cohorts by how long before the prediction time the orders were placed; the first table shows where it ranks, and which other columns go with stopping to order.\n", - "4. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n", - "\n", - "The column table says what goes with stopping to order across many customers; the gradients say what drove the prediction for one." - ] + "source": "How to interpret the result:\n\n1. The first table is the whole column analysis, one row per column, cohort and class, highest-scoring columns first. `share` is the cohort's share of the customers, `mean` the share of them in that class, and `score` the column's weight: over the context examples, the more the share that placed no order differs between a column's cohorts, the higher. The scores add up to 1. `COUNT(*)` is the number of a customer's linked rows, such as orders.\n2. The second table keeps one column and one class: `OrderDate` for the customers who placed no order, with cohorts by how long before the prediction time the orders were placed. Example 1 compared the model with the days since each customer's last order; this is that signal, and the first table shows what else goes with stopping to order.\n3. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n\nThe column table says what goes with stopping to order across many customers; the gradients say what drove the prediction for one." }, { "cell_type": "markdown", From dc4d0d3db771e3875069662a1ef8b513f1806e48 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 11:31:57 -0800 Subject: [PATCH 08/16] fix Signed-off-by: Jana Gagacheva --- .../databricks/kumo_relational_quickstart.ipynb | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index b57993024..197a59af3 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -905,8 +905,8 @@ "\n", "The result carries explanations at two levels:\n", "\n", - "- `result.explanations.columns`, computed by the client from the context examples the model read: each column of the linked tables is split into cohorts, such as value ranges, categories or time before the prediction time, and each cohort has its share of the customers and the share of them that placed no order. Each column gets a score.\n", - "- `result.explanations.gradients`, from the model, for each of the 25 customers: which tables and columns pushed that customer's probability up or down." + "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", + "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradint represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole." ] }, { @@ -926,14 +926,20 @@ "result = client.predict(request, model=model)\n", "\n", "columns = result.explanations.columns.to_pandas()\n", + "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", "display(columns)\n", "\n", - "# How does order recency relate to stopping to order? The class True is the\n", + "# How does order recency relate to customers placing no order(s)? The class True is the\n", "# \"placed no order\" answer; the False rows are its mirror image.\n", "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", "display(columns[recency])\n", "\n", + "# Whole gradients analysis, for each explained row.\n", "gradients = result.explanations.gradients.to_pandas()\n", + "\n", + "# Why does the model give this customer a high probability of placing no\n", + "# order? Show the 10 facts about this customer it weighs most.\n", + "display(columns)\n", "first = gradients[\n", " (gradients['id'] == riskiest_25[0])\n", " & (gradients['output'] == 'probability_True')\n", @@ -945,7 +951,9 @@ "cell_type": "markdown", "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, - "source": "How to interpret the result:\n\n1. The first table is the whole column analysis, one row per column, cohort and class, highest-scoring columns first. `share` is the cohort's share of the customers, `mean` the share of them in that class, and `score` the column's weight: over the context examples, the more the share that placed no order differs between a column's cohorts, the higher. The scores add up to 1. `COUNT(*)` is the number of a customer's linked rows, such as orders.\n2. The second table keeps one column and one class: `OrderDate` for the customers who placed no order, with cohorts by how long before the prediction time the orders were placed. Example 1 compared the model with the days since each customer's last order; this is that signal, and the first table shows what else goes with stopping to order.\n3. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n\nThe column table says what goes with stopping to order across many customers; the gradients say what drove the prediction for one." + "source": [ + "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients come from the model, for each customer, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." + ] }, { "cell_type": "markdown", From 5d082c1f2482f680362d3bb4c944258453c7770e Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 11:42:55 -0800 Subject: [PATCH 09/16] split example in two Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 67 +++++-------------- 1 file changed, 17 insertions(+), 50 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 197a59af3..4f72040ac 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -892,22 +892,7 @@ "cell_type": "markdown", "id": "620b2a07b418435c90d8e7dca1fd869f", "metadata": {}, - "source": [ - "### Example 5: Explain the predictions\n", - "\n", - "The earlier examples ask who; this one asks why.\n", - "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", - "\n", - "```\n", - "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", - "FOR EACH customers.CustomerID ← one prediction per customer\n", - "```\n", - "\n", - "The result carries explanations at two levels:\n", - "\n", - "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", - "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradint represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole." - ] + "source": "### Example 5: Explain the predictions\n\nThe earlier examples ask who; this one asks why.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 5.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n\n```\nEXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\nFOR EACH customers.CustomerID ← one prediction per customer\n```" }, { "cell_type": "code", @@ -915,45 +900,27 @@ "id": "b2ee7bc6cf2e43d8b7e7e3207117ea3d", "metadata": {}, "outputs": [], - "source": [ - "# The 25 customers Example 1 rated riskiest, riskiest first.\n", - "riskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\n", - "request = PredictiveQuery(\n", - " 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", - " 'FOR EACH customers.CustomerID',\n", - " schema,\n", - ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", - "result = client.predict(request, model=model)\n", - "\n", - "columns = result.explanations.columns.to_pandas()\n", - "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", - "display(columns)\n", - "\n", - "# How does order recency relate to customers placing no order(s)? The class True is the\n", - "# \"placed no order\" answer; the False rows are its mirror image.\n", - "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", - "display(columns[recency])\n", - "\n", - "# Whole gradients analysis, for each explained row.\n", - "gradients = result.explanations.gradients.to_pandas()\n", - "\n", - "# Why does the model give this customer a high probability of placing no\n", - "# order? Show the 10 facts about this customer it weighs most.\n", - "display(columns)\n", - "first = gradients[\n", - " (gradients['id'] == riskiest_25[0])\n", - " & (gradients['output'] == 'probability_True')\n", - "]\n", - "display(first.loc[first['gradient'].abs().nlargest(10).index])" - ] + "source": "# The 25 customers Example 1 rated riskiest, riskiest first.\nriskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\nrequest = PredictiveQuery(\n 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n 'FOR EACH customers.CustomerID',\n schema,\n).materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\nresult = client.predict(request, model=model)\n\ncolumns = result.explanations.columns.to_pandas()\n# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\ndisplay(columns)\n\n# How does order recency relate to stopping to order? The class True is the\n# \"placed no order\" answer; the False rows are its mirror image.\nrecency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\ndisplay(columns[recency])\n\n# This customer looks likely to stop ordering — what about them makes the\n# model think so? Show the 10 facts about this customer it weighs most.\ngradients = result.explanations.gradients.to_pandas()\nfirst = gradients[\n (gradients['id'] == riskiest_25[0])\n & (gradients['output'] == 'probability_True')\n]\ndisplay(first.loc[first['gradient'].abs().nlargest(10).index])" }, { "cell_type": "markdown", "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, - "source": [ - "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients come from the model, for each customer, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." - ] + "source": "How to interpret the result:\n\n1. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n\nThe two levels differ in source and in scope. The column analysis comes from the data: across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering — the model plays no part in it. The gradients come from the model: for one customer, they show how each value the model read moved that prediction. Read the columns to understand the data; read the gradients to understand a prediction." + }, + { + "cell_type": "markdown", + "id": "be17fd43", + "source": "#### 5.2 Ask with outputs\n\nThe `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\nTo keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:", + "metadata": {} + }, + { + "cell_type": "code", + "id": "1575e783", + "source": "# The same request and explanations, without the EXPLAIN prefix.\nrequest = PredictiveQuery(\n 'PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n 'FOR EACH customers.CustomerID',\n schema,\n).materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\nresult = client.predict(\n request, model=model, outputs=['prediction', 'explanation']\n)\nprint(f'{len(result.explanations.gradients)} predictions explained.')", + "metadata": {}, + "execution_count": null, + "outputs": [] }, { "cell_type": "markdown", From 2efff48442a8dbbe965ab360b89e0e2c5dfb7b22 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 11:47:40 -0800 Subject: [PATCH 10/16] undo some bs the model changed Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 80 +++++++++++++++++-- 1 file changed, 72 insertions(+), 8 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 4f72040ac..8649e1601 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -892,7 +892,24 @@ "cell_type": "markdown", "id": "620b2a07b418435c90d8e7dca1fd869f", "metadata": {}, - "source": "### Example 5: Explain the predictions\n\nThe earlier examples ask who; this one asks why.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 5.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n\n```\nEXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\nFOR EACH customers.CustomerID ← one prediction per customer\n```" + "source": [ + "### Example 5: Explain the predictions\n", + "\n", + "The earlier examples ask who; this one asks why.\n", + "The result carries explanations at two levels:\n", + "\n", + "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", + "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n", + "\n", + "#### 5.1 Ask with the EXPLAIN prefix\n", + "\n", + "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", + "\n", + "```\n", + "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", + "FOR EACH customers.CustomerID ← one prediction per customer\n", + "```" + ] }, { "cell_type": "code", @@ -900,27 +917,74 @@ "id": "b2ee7bc6cf2e43d8b7e7e3207117ea3d", "metadata": {}, "outputs": [], - "source": "# The 25 customers Example 1 rated riskiest, riskiest first.\nriskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\nrequest = PredictiveQuery(\n 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n 'FOR EACH customers.CustomerID',\n schema,\n).materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\nresult = client.predict(request, model=model)\n\ncolumns = result.explanations.columns.to_pandas()\n# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\ndisplay(columns)\n\n# How does order recency relate to stopping to order? The class True is the\n# \"placed no order\" answer; the False rows are its mirror image.\nrecency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\ndisplay(columns[recency])\n\n# This customer looks likely to stop ordering — what about them makes the\n# model think so? Show the 10 facts about this customer it weighs most.\ngradients = result.explanations.gradients.to_pandas()\nfirst = gradients[\n (gradients['id'] == riskiest_25[0])\n & (gradients['output'] == 'probability_True')\n]\ndisplay(first.loc[first['gradient'].abs().nlargest(10).index])" + "source": [ + "# The 25 customers Example 1 rated riskiest, riskiest first.\n", + "riskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\n", + "request = PredictiveQuery(\n", + " 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", + " 'FOR EACH customers.CustomerID',\n", + " schema,\n", + ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", + "result = client.predict(request, model=model)\n", + "\n", + "columns = result.explanations.columns.to_pandas()\n", + "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", + "display(columns)\n", + "\n", + "# How does order recency relate to stopping to order? The class True is the\n", + "# \"placed no order\" answer; the False rows are its mirror image.\n", + "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", + "display(columns[recency])\n", + "\n", + "# What drove the riskiest customer's prediction? A prediction carries a\n", + "# gradient for every value of every linked row, so the cell keeps the 10\n", + "# largest. probability_True is the \"placed no order\" output; the others\n", + "# mirror it.\n", + "gradients = result.explanations.gradients.to_pandas()\n", + "first = gradients[\n", + " (gradients['id'] == riskiest_25[0])\n", + " & (gradients['output'] == 'probability_True')\n", + "]\n", + "display(first.loc[first['gradient'].abs().nlargest(10).index])" + ] }, { "cell_type": "markdown", "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, - "source": "How to interpret the result:\n\n1. The third table lists the 10 largest gradients of the riskiest customer's `probability_True`. Each line is one value the model read, from the customer's own row (`hop` 0) or a linked row, such as an order (`hop` 1). A positive `gradient` means a higher value would raise the probability of placing no order, a negative one would lower it. `column` is the model's numeric form of the column, which can differ from the table's, such as a date split into parts.\n\nThe two levels differ in source and in scope. The column analysis comes from the data: across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering — the model plays no part in it. The gradients come from the model: for one customer, they show how each value the model read moved that prediction. Read the columns to understand the data; read the gradients to understand a prediction." + "source": [ + "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients come from the model, for each customer, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." + ] }, { "cell_type": "markdown", "id": "be17fd43", - "source": "#### 5.2 Ask with outputs\n\nThe `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\nTo keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:", - "metadata": {} + "metadata": {}, + "source": [ + "#### 5.2 Ask with outputs\n", + "\n", + "The `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\n", + "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:" + ] }, { "cell_type": "code", + "execution_count": null, "id": "1575e783", - "source": "# The same request and explanations, without the EXPLAIN prefix.\nrequest = PredictiveQuery(\n 'PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n 'FOR EACH customers.CustomerID',\n schema,\n).materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\nresult = client.predict(\n request, model=model, outputs=['prediction', 'explanation']\n)\nprint(f'{len(result.explanations.gradients)} predictions explained.')", "metadata": {}, - "execution_count": null, - "outputs": [] + "outputs": [], + "source": [ + "# The same request and explanations, without the EXPLAIN prefix.\n", + "request = PredictiveQuery(\n", + " 'PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", + " 'FOR EACH customers.CustomerID',\n", + " schema,\n", + ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", + "result = client.predict(\n", + " request, model=model, outputs=['prediction', 'explanation']\n", + ")\n", + "print(f'{len(result.explanations.gradients)} predictions explained.')" + ] }, { "cell_type": "markdown", From 4bca1968711ba539711c58d23fe4fc8f304a2a50 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Tue, 3 Nov 2026 13:52:30 -0800 Subject: [PATCH 11/16] add version availability Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 21 ++----------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 8649e1601..ac3534c68 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -892,24 +892,7 @@ "cell_type": "markdown", "id": "620b2a07b418435c90d8e7dca1fd869f", "metadata": {}, - "source": [ - "### Example 5: Explain the predictions\n", - "\n", - "The earlier examples ask who; this one asks why.\n", - "The result carries explanations at two levels:\n", - "\n", - "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", - "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n", - "\n", - "#### 5.1 Ask with the EXPLAIN prefix\n", - "\n", - "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", - "\n", - "```\n", - "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", - "FOR EACH customers.CustomerID ← one prediction per customer\n", - "```" - ] + "source": "### Example 5: Explain the predictions\n\nThe earlier examples ask who; this one asks why.\nExplanations are available with NIM version 1.1+ and client version 1.1.0+.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 5.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n\n```\nEXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\nFOR EACH customers.CustomerID ← one prediction per customer\n```" }, { "cell_type": "code", @@ -1111,4 +1094,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file From 7293afe5258d85fdc121a2b2fc231afd7abf5cb3 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Wed, 4 Nov 2026 11:34:27 -0800 Subject: [PATCH 12/16] some updates to rel Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index ac3534c68..51d7a6776 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -892,7 +892,28 @@ "cell_type": "markdown", "id": "620b2a07b418435c90d8e7dca1fd869f", "metadata": {}, - "source": "### Example 5: Explain the predictions\n\nThe earlier examples ask who; this one asks why.\nExplanations are available with NIM version 1.1+ and client version 1.1.0+.\nThe result carries explanations at two levels:\n\n- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. The gradient represents how sensitive the prediction is to that value. The larger the gradient's magnitude is, the more that value influenced this prediction. Gradients describe the model's actual computation for one row, where the column analysis describes the data as a whole.\n\n#### 5.1 Ask with the EXPLAIN prefix\n\nThe cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n\n```\nEXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\nFOR EACH customers.CustomerID ← one prediction per customer\n```" + "source": [ + "### Example 5: Explain the predictions\n", + "\n", + "The earlier examples ask who; this one asks why.\n", + "Explanations are available with NIM version 1.1+ and client version 1.1.0+.\n", + "The result carries explanations at two levels:\n", + "\n", + "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", + "\n", + "\n", + "\n", + "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. A gradient measures local sensitivity: how the model output would change for a small change in a preprocessed numerical value, per unit of that column. Its sign gives the direction of change, and its magnitude gives the local rate of change. Magnitudes depend on units and preprocessing; they do not measure contributions to the prediction or provide a feature-importance ranking.\n", + "\n", + "#### 5.1 Ask with the EXPLAIN prefix\n", + "\n", + "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", + "\n", + "```\n", + "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", + "FOR EACH customers.CustomerID ← one prediction per customer\n", + "```" + ] }, { "cell_type": "code", @@ -919,9 +940,9 @@ "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", "display(columns[recency])\n", "\n", - "# What drove the riskiest customer's prediction? A prediction carries a\n", + "# Inspect local sensitivity for the riskiest customer. A prediction carries a\n", "# gradient for every value of every linked row, so the cell keeps the 10\n", - "# largest. probability_True is the \"placed no order\" output; the others\n", + "# largest absolute gradients for inspection. probability_True is the \"placed no order\" output; the others\n", "# mirror it.\n", "gradients = result.explanations.gradients.to_pandas()\n", "first = gradients[\n", @@ -936,7 +957,7 @@ "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, "source": [ - "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients come from the model, for each customer, they show how each value the model read influenced that prediction. Read the columns to understand the data, read the gradients to understand a prediction." + "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients describe local sensitivity of each customer's model output to preprocessed numerical values. The ten rows shown above have the largest absolute gradients for this customer and output. Because these rates depend on each column's units and preprocessing, they are not a ranking of feature importance or contributions to the prediction." ] }, { @@ -1094,4 +1115,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} \ No newline at end of file +} From 1af545af1f28e1365fa245cf2db051b7cca06404 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Wed, 4 Nov 2026 16:40:29 -0800 Subject: [PATCH 13/16] update notebook: Signed-off-by: Jana Gagacheva --- .../kumo_relational_quickstart.ipynb | 129 +++++++++++++----- 1 file changed, 98 insertions(+), 31 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 51d7a6776..970ea3eaa 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -895,24 +895,16 @@ "source": [ "### Example 5: Explain the predictions\n", "\n", - "The earlier examples ask who; this one asks why.\n", - "Explanations are available with NIM version 1.1+ and client version 1.1.0+.\n", - "The result carries explanations at two levels:\n", - "\n", - "- `result.explanations.columns`, computed by the client from the context examples the model reads. Each column's values are split into cohorts (value ranges, categories, or time buckets). Each cohort reports its share of the examples and its mean outcome. A column's score is the population-weighted standard deviation of its cohorts' mean outcomes — how much the outcome rate varies across the column's cohorts, with cohorts weighted by their share. Scores are normalized to sum to 1 across columns. High score means the column is strongly associated with the outcome in the data, while a low score is the opposite.\n", - "\n", + "We predicted which customers are likely to place no orders in the next 90 days. Now we'll explore patterns in the historical examples and inspect how one customer's prediction responds to small input changes.\n", "\n", + "Explanations are available with NIM version 1.1+ and client version 1.1.0+.\n", "\n", - "- `result.explanations.gradients`, returned by the model for each explained row. The entry covers every value the model read for that row — the entity's own columns and the linked rows' — and gives each a gradient. A gradient measures local sensitivity: how the model output would change for a small change in a preprocessed numerical value, per unit of that column. Its sign gives the direction of change, and its magnitude gives the local rate of change. Magnitudes depend on units and preprocessing; they do not measure contributions to the prediction or provide a feature-importance ranking.\n", - "\n", - "#### 5.1 Ask with the EXPLAIN prefix\n", + "The result carries explanations at two levels:\n", "\n", - "The cell asks the question of Example 1 again with the `EXPLAIN` prefix, at the same prediction time, for the 25 customers Example 1 rated riskiest:\n", + "- `result.explanations.columns`, computed by the client from the historical examples the model reads. It groups customers by ranges or categories in each column. Each group reports its share of the examples and the fraction who placed no orders in the following 90 days.\n", + "- `result.explanations.gradients`, returned by the model for each explained customer. A gradient describes how the predicted probability responds to a small change in a preprocessed numerical input. It does not measure how much that input contributed to the prediction.\n", "\n", - "```\n", - "EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 ← also explain each prediction\n", - "FOR EACH customers.CustomerID ← one prediction per customer\n", - "```" + "Add `EXPLAIN` to request both column analysis and gradients." ] }, { @@ -922,34 +914,105 @@ "metadata": {}, "outputs": [], "source": [ - "# The 25 customers Example 1 rated riskiest, riskiest first.\n", + "# Explain the 25 customers Example 1 rated riskiest.\n", "riskiest_25 = churn.loc[riskiest[:25], 'id'].tolist()\n", "request = PredictiveQuery(\n", " 'EXPLAIN PREDICT COUNT(sales_order_headers.*, 0, 90, days) = 0 '\n", " 'FOR EACH customers.CustomerID',\n", " schema,\n", ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", - "result = client.predict(request, model=model)\n", + "result = client.predict(request, model=model)" + ] + }, + { + "cell_type": "markdown", + "id": "dce952ea80cc428fb83782dd23aa2b3f", + "metadata": {}, + "source": [ + "#### What patterns do we see in the historical data?\n", "\n", + "The column analysis groups customers by ranges or categories in each column. For example, `OrderDate` groups customers by their average order date. For each group, the table shows what percentage of the historical examples it represents and what percentage placed no orders in the following 90 days." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2b5bb9ac990d40baab07c0a0cefab7e9", + "metadata": {}, + "outputs": [], + "source": [ "columns = result.explanations.columns.to_pandas()\n", - "# Whole column analysis, one row per column, cohort and class, highest-scoring columns first.\n", - "display(columns)\n", - "\n", - "# How does order recency relate to stopping to order? The class True is the\n", - "# \"placed no order\" answer; the False rows are its mirror image.\n", - "recency = (columns['column'] == 'OrderDate') & (columns['class'] == True) # noqa: E712\n", - "display(columns[recency])\n", - "\n", - "# Inspect local sensitivity for the riskiest customer. A prediction carries a\n", - "# gradient for every value of every linked row, so the cell keeps the 10\n", - "# largest absolute gradients for inspection. probability_True is the \"placed no order\" output; the others\n", - "# mirror it.\n", + "\n", + "# True means the customer placed no orders in the following 90 days.\n", + "groups = columns.loc[\n", + " columns['class'] == True, # noqa: E712\n", + " ['table', 'hop', 'column', 'cohort', 'share', 'mean'],\n", + "].copy()\n", + "\n", + "display(columns)" + ] + }, + { + "cell_type": "markdown", + "id": "7e07694e4f5c42a191903997b324abfc", + "metadata": {}, + "source": [ + "Each row answers: **How common is this group, and how often did customers in it stop ordering?**\n", + "\n", + "For example, a row with `30` under `examples (%)` and `45` under `placed no orders (%)` would mean that the group contains 30% of the historical examples, and 45% of that group placed no orders.\n", + "\n", + "#### Do customers with older ordering activity stop ordering more often?\n", + "\n", + "Zoom in on `OrderDate`. The analysis averages each customer's linked order dates before grouping, so this describes their average ordering date, not their most recent order." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c2becede8cda4ba09b497c1d48b39369", + "metadata": {}, + "outputs": [], + "source": [ + "order_dates = groups[\n", + " (groups['table'] == 'sales_order_headers')\n", + " & (groups['column'] == 'OrderDate')\n", + "]\n", + "display(order_dates)" + ] + }, + { + "cell_type": "markdown", + "id": "27b22710d2de41ff9da8cc017d6dfb61", + "metadata": {}, + "source": [ + "Compare the percentages across date ranges within the same hop. If older groups have higher percentages of customers placing no orders, that is a pattern in these historical examples. The group sizes show how much of the data the pattern covers.\n", + "\n", + "This helps you understand the data behind the predictions. It does not establish why a particular customer received their risk score.\n", + "\n", + "#### How would small input changes affect one customer's predicted probability?\n", + "\n", + "Gradients describe how the model output responds to small changes near the current input values. They use the model's numerical inputs after preprocessing, which may differ from the original columns.\n", + "\n", + "For the riskiest customer, inspect ten entries with the largest absolute gradients:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7b914676ad1e4ecbac19bf90c24bb735", + "metadata": {}, + "outputs": [], + "source": [ "gradients = result.explanations.gradients.to_pandas()\n", - "first = gradients[\n", + "customer_gradients = gradients[\n", " (gradients['id'] == riskiest_25[0])\n", " & (gradients['output'] == 'probability_True')\n", "]\n", - "display(first.loc[first['gradient'].abs().nlargest(10).index])" + "display(\n", + " customer_gradients.loc[\n", + " customer_gradients['gradient'].abs().nlargest(10).index\n", + " ]\n", + ")" ] }, { @@ -957,7 +1020,11 @@ "id": "a7b667632bfa4a48be8e94665ef115ca", "metadata": {}, "source": [ - "The two levels differ in source and in scope. The column analysis comes from the data, across the context examples, it shows which columns separate the customers who stopped ordering from those who kept ordering. The gradients describe local sensitivity of each customer's model output to preprocessed numerical values. The ten rows shown above have the largest absolute gradients for this customer and output. Because these rates depend on each column's units and preprocessing, they are not a ranking of feature importance or contributions to the prediction." + "A positive gradient means a small increase in that preprocessed value would locally increase the predicted probability of placing no orders; a negative gradient means it would decrease it.\n", + "\n", + "The sizes depend on the input scales, so these ten entries are not necessarily the inputs that contributed most to the prediction.\n", + "\n", + "Use this table to investigate sensitivity—for example, when checking a possibly incorrect source value. Correct the value using the source record, rerun the prediction, and check whether the customer's risk score changes enough to affect your outreach decision. Gradients alone do not tell you which business action would prevent churn." ] }, { From 6122c2645964e48f0c76e97f15e84645eb106589 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Thu, 5 Nov 2026 10:27:00 -0800 Subject: [PATCH 14/16] some fixes Signed-off-by: Jana Gagacheva --- .../databricks/kumo_relational_quickstart.ipynb | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 970ea3eaa..247b32ed8 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -931,7 +931,9 @@ "source": [ "#### What patterns do we see in the historical data?\n", "\n", - "The column analysis groups customers by ranges or categories in each column. For example, `OrderDate` groups customers by their average order date. For each group, the table shows what percentage of the historical examples it represents and what percentage placed no orders in the following 90 days." + "The column analysis groups customers by ranges or categories in each column. For each group, the table shows what percentage of the historical examples it represents and what percentage placed no orders in the following 90 days.\n", + "\n", + "Columns of linked tables, such as orders, are grouped per order, not per customer. For `OrderDate`, each order falls into a window of time before the customer's anchor date, for example `[0 days, 30 days)`. A customer whose orders fall into several windows is split across them by their share of orders: with 3 of 4 orders in the last 30 days, they count as three quarters in that window and one quarter in the window holding the fourth order." ] }, { @@ -959,11 +961,11 @@ "source": [ "Each row answers: **How common is this group, and how often did customers in it stop ordering?**\n", "\n", - "For example, a row with `30` under `examples (%)` and `45` under `placed no orders (%)` would mean that the group contains 30% of the historical examples, and 45% of that group placed no orders.\n", + "For example, a row with `30` under `share` and `45` under `mean` would mean that the group contains 30% of the historical examples, and 45% of that group placed no orders.\n", "\n", "#### Do customers with older ordering activity stop ordering more often?\n", "\n", - "Zoom in on `OrderDate`. The analysis averages each customer's linked order dates before grouping, so this describes their average ordering date, not their most recent order." + "Zoom in on `OrderDate`. Each group is a window of time before the anchor date, and its percentages are weighted by how much of each customer's orders fall into it. Customers with no orders before the anchor date do not appear in these groups." ] }, { @@ -985,7 +987,7 @@ "id": "27b22710d2de41ff9da8cc017d6dfb61", "metadata": {}, "source": [ - "Compare the percentages across date ranges within the same hop. If older groups have higher percentages of customers placing no orders, that is a pattern in these historical examples. The group sizes show how much of the data the pattern covers.\n", + "Compare the percentages across time windows within the same hop. If older groups have higher percentages of customers placing no orders, that is a pattern in these historical examples. The group sizes show how much of the data the pattern covers.\n", "\n", "This helps you understand the data behind the predictions. It does not establish why a particular customer received their risk score.\n", "\n", @@ -1035,7 +1037,7 @@ "#### 5.2 Ask with outputs\n", "\n", "The `EXPLAIN` prefix and the `outputs` argument ask for the same thing.\n", - "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'explanation']`:" + "To keep the query text fixed and decide per call, pass `outputs=['prediction', 'probabilities', 'explanation']`:" ] }, { @@ -1052,7 +1054,7 @@ " schema,\n", ").materialize(indices=riskiest_25, anchor_time=PAST, num_context_samples=5000)\n", "result = client.predict(\n", - " request, model=model, outputs=['prediction', 'explanation']\n", + " request, model=model, outputs=['prediction', 'probabilities', 'explanation']\n", ")\n", "print(f'{len(result.explanations.gradients)} predictions explained.')" ] From ec0b378b0f69502a0c3169f21b9f8dcbdb26eeff Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Thu, 5 Nov 2026 16:33:29 -0800 Subject: [PATCH 15/16] some minor updates Signed-off-by: Jana Gagacheva --- examples/databricks/kumo_relational_quickstart.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index 247b32ed8..d58d78b28 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -933,7 +933,7 @@ "\n", "The column analysis groups customers by ranges or categories in each column. For each group, the table shows what percentage of the historical examples it represents and what percentage placed no orders in the following 90 days.\n", "\n", - "Columns of linked tables, such as orders, are grouped per order, not per customer. For `OrderDate`, each order falls into a window of time before the customer's anchor date, for example `[0 days, 30 days)`. A customer whose orders fall into several windows is split across them by their share of orders: with 3 of 4 orders in the last 30 days, they count as three quarters in that window and one quarter in the window holding the fourth order." + "For numerical columns in linked tables, values are averaged per customer at each hop before grouping customers into cohorts. For categorical and timestamp columns, individual linked rows are grouped instead. For `OrderDate`, each order falls into a window of time before the customer's anchor date, for example `[0 days, 30 days)`. A customer whose orders fall into several windows is split across them by their share of orders: with 3 of 4 orders in the last 30 days, they count as three quarters in that window and one quarter in the window holding the fourth order." ] }, { @@ -961,7 +961,7 @@ "source": [ "Each row answers: **How common is this group, and how often did customers in it stop ordering?**\n", "\n", - "For example, a row with `30` under `share` and `45` under `mean` would mean that the group contains 30% of the historical examples, and 45% of that group placed no orders.\n", + "For example, a row with `0.30` under `share` and `0.45` under `mean` would mean that the group contains 30% of the historical examples, and 45% of that group placed no orders.\n", "\n", "#### Do customers with older ordering activity stop ordering more often?\n", "\n", From 63003cde2175451713ecd33ac00d57c7c268f011 Mon Sep 17 00:00:00 2001 From: Jana Gagacheva Date: Mon, 9 Nov 2026 09:46:34 -0800 Subject: [PATCH 16/16] Use a possible time window and display the filtered cohorts Signed-off-by: Jana Gagacheva --- examples/databricks/kumo_relational_quickstart.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/databricks/kumo_relational_quickstart.ipynb b/examples/databricks/kumo_relational_quickstart.ipynb index d58d78b28..06fd88f8b 100644 --- a/examples/databricks/kumo_relational_quickstart.ipynb +++ b/examples/databricks/kumo_relational_quickstart.ipynb @@ -933,7 +933,7 @@ "\n", "The column analysis groups customers by ranges or categories in each column. For each group, the table shows what percentage of the historical examples it represents and what percentage placed no orders in the following 90 days.\n", "\n", - "For numerical columns in linked tables, values are averaged per customer at each hop before grouping customers into cohorts. For categorical and timestamp columns, individual linked rows are grouped instead. For `OrderDate`, each order falls into a window of time before the customer's anchor date, for example `[0 days, 30 days)`. A customer whose orders fall into several windows is split across them by their share of orders: with 3 of 4 orders in the last 30 days, they count as three quarters in that window and one quarter in the window holding the fourth order." + "For numerical columns in linked tables, values are averaged per customer at each hop before grouping customers into cohorts. For categorical and timestamp columns, individual linked rows are grouped instead. For `OrderDate`, each order falls into a window of time before the customer's anchor date. The sampled history is split into ten equal windows, and their width and unit (hours, days, weeks or months) depend on how far back it reaches. A customer whose orders fall into several windows is split across them by their share of orders: with three of four orders in one window, they count as three quarters there and one quarter in the window holding the fourth order." ] }, { @@ -951,7 +951,7 @@ " ['table', 'hop', 'column', 'cohort', 'share', 'mean'],\n", "].copy()\n", "\n", - "display(columns)" + "display(groups)" ] }, {