` renders the embedding linked to a feature-contribution bar chart.\n",
"\n",
":::{admonition} Install the plotting extras\n",
":class: tip dropdown\n",
"\n",
"`glass_box_umap.plotting` is an optional dependency, that can be installed like so:\n",
"\n",
"```bash\n",
"pip install \"glass-box-umap[plotting]\"\n",
"# or\n",
"uv pip install \"glass-box-umap[plotting]\"\n",
"```\n",
":::"
]
},
{
"cell_type": "code",
"execution_count": 9,
"id": "976a8eac",
"metadata": {
"execution": {
"iopub.execute_input": "2026-05-11T22:14:01.265358Z",
"iopub.status.busy": "2026-05-11T22:14:01.265263Z",
"iopub.status.idle": "2026-05-11T22:14:01.517521Z",
"shell.execute_reply": "2026-05-11T22:14:01.517160Z"
}
},
"outputs": [
{
"data": {
"application/javascript": [
"'use strict';\n",
"(function(root) {\n",
" function now() {\n",
" return new Date();\n",
" }\n",
"\n",
" const force = true;\n",
"\n",
" if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n",
" root._bokeh_onload_callbacks = [];\n",
" root._bokeh_is_loading = undefined;\n",
" }\n",
"\n",
"const JS_MIME_TYPE = 'application/javascript';\n",
" const HTML_MIME_TYPE = 'text/html';\n",
" const EXEC_MIME_TYPE = 'application/vnd.bokehjs_exec.v0+json';\n",
" const CLASS_NAME = 'output_bokeh rendered_html';\n",
"\n",
" /**\n",
" * Render data to the DOM node\n",
" */\n",
" function render(props, node) {\n",
" const script = document.createElement(\"script\");\n",
" node.appendChild(script);\n",
" }\n",
"\n",
" /**\n",
" * Handle when an output is cleared or removed\n",
" */\n",
" function handleClearOutput(event, handle) {\n",
" function drop(id) {\n",
" const view = Bokeh.index.get_by_id(id)\n",
" if (view != null) {\n",
" view.model.document.clear()\n",
" Bokeh.index.delete(view)\n",
" }\n",
" }\n",
"\n",
" const cell = handle.cell;\n",
"\n",
" const id = cell.output_area._bokeh_element_id;\n",
" const server_id = cell.output_area._bokeh_server_id;\n",
"\n",
" // Clean up Bokeh references\n",
" if (id != null) {\n",
" drop(id)\n",
" }\n",
"\n",
" if (server_id !== undefined) {\n",
" // Clean up Bokeh references\n",
" const cmd_clean = \"from bokeh.io.state import curstate; print(curstate().uuid_to_server['\" + server_id + \"'].get_sessions()[0].document.roots[0]._id)\";\n",
" cell.notebook.kernel.execute(cmd_clean, {\n",
" iopub: {\n",
" output: function(msg) {\n",
" const id = msg.content.text.trim()\n",
" drop(id)\n",
" }\n",
" }\n",
" });\n",
" // Destroy server and session\n",
" const cmd_destroy = \"import bokeh.io.notebook as ion; ion.destroy_server('\" + server_id + \"')\";\n",
" cell.notebook.kernel.execute(cmd_destroy);\n",
" }\n",
" }\n",
"\n",
" /**\n",
" * Handle when a new output is added\n",
" */\n",
" function handleAddOutput(event, handle) {\n",
" const output_area = handle.output_area;\n",
" const output = handle.output;\n",
"\n",
" // limit handleAddOutput to display_data with EXEC_MIME_TYPE content only\n",
" if ((output.output_type != \"display_data\") || (!Object.prototype.hasOwnProperty.call(output.data, EXEC_MIME_TYPE))) {\n",
" return\n",
" }\n",
"\n",
" const toinsert = output_area.element.find(\".\" + CLASS_NAME.split(' ')[0]);\n",
"\n",
" if (output.metadata[EXEC_MIME_TYPE][\"id\"] !== undefined) {\n",
" toinsert[toinsert.length - 1].firstChild.textContent = output.data[JS_MIME_TYPE];\n",
" // store reference to embed id on output_area\n",
" output_area._bokeh_element_id = output.metadata[EXEC_MIME_TYPE][\"id\"];\n",
" }\n",
" if (output.metadata[EXEC_MIME_TYPE][\"server_id\"] !== undefined) {\n",
" const bk_div = document.createElement(\"div\");\n",
" bk_div.innerHTML = output.data[HTML_MIME_TYPE];\n",
" const script_attrs = bk_div.children[0].attributes;\n",
" for (let i = 0; i < script_attrs.length; i++) {\n",
" toinsert[toinsert.length - 1].firstChild.setAttribute(script_attrs[i].name, script_attrs[i].value);\n",
" toinsert[toinsert.length - 1].firstChild.textContent = bk_div.children[0].textContent\n",
" }\n",
" // store reference to server id on output_area\n",
" output_area._bokeh_server_id = output.metadata[EXEC_MIME_TYPE][\"server_id\"];\n",
" }\n",
" }\n",
"\n",
" function register_renderer(events, OutputArea) {\n",
"\n",
" function append_mime(data, metadata, element) {\n",
" // create a DOM node to render to\n",
" const toinsert = this.create_output_subarea(\n",
" metadata,\n",
" CLASS_NAME,\n",
" EXEC_MIME_TYPE\n",
" );\n",
" this.keyboard_manager.register_events(toinsert);\n",
" // Render to node\n",
" const props = {data: data, metadata: metadata[EXEC_MIME_TYPE]};\n",
" render(props, toinsert[toinsert.length - 1]);\n",
" element.append(toinsert);\n",
" return toinsert\n",
" }\n",
"\n",
" /* Handle when an output is cleared or removed */\n",
" events.on('clear_output.CodeCell', handleClearOutput);\n",
" events.on('delete.Cell', handleClearOutput);\n",
"\n",
" /* Handle when a new output is added */\n",
" events.on('output_added.OutputArea', handleAddOutput);\n",
"\n",
" /**\n",
" * Register the mime type and append_mime function with output_area\n",
" */\n",
" OutputArea.prototype.register_mime_type(EXEC_MIME_TYPE, append_mime, {\n",
" /* Is output safe? */\n",
" safe: true,\n",
" /* Index of renderer in `output_area.display_order` */\n",
" index: 0\n",
" });\n",
" }\n",
"\n",
" // register the mime type if in Jupyter Notebook environment and previously unregistered\n",
" if (root.Jupyter !== undefined) {\n",
" const events = require('base/js/events');\n",
" const OutputArea = require('notebook/js/outputarea').OutputArea;\n",
"\n",
" if (OutputArea.prototype.mime_types().indexOf(EXEC_MIME_TYPE) == -1) {\n",
" register_renderer(events, OutputArea);\n",
" }\n",
" }\n",
" if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n",
" root._bokeh_timeout = Date.now() + 5000;\n",
" root._bokeh_failed_load = false;\n",
" }\n",
"\n",
" const NB_LOAD_WARNING = {'data': {'text/html':\n",
" \"\\n\"+\n",
" \"
\\n\"+\n",
" \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n",
" \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n",
" \"
\\n\"+\n",
" \"
\\n\"+\n",
" \"- re-rerun `output_notebook()` to attempt to load from CDN again, or
\\n\"+\n",
" \"- use INLINE resources instead, as so:
\\n\"+\n",
" \"
\\n\"+\n",
" \"
\\n\"+\n",
" \"from bokeh.resources import INLINE\\n\"+\n",
" \"output_notebook(resources=INLINE)\\n\"+\n",
" \"\\n\"+\n",
" \"
\\n\"+\n \"
\\n\"+\n \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n \"
\\n\"+\n \"
\\n\"+\n \"- re-rerun `output_notebook()` to attempt to load from CDN again, or
\\n\"+\n \"- use INLINE resources instead, as so:
\\n\"+\n \"
\\n\"+\n \"
\\n\"+\n \"from bokeh.resources import INLINE\\n\"+\n \"output_notebook(resources=INLINE)\\n\"+\n \"\\n\"+\n \"
index: @index · group: @group · value: @picker_data_value{0.000}
\",\"sort_by\":null}},{\"type\":\"object\",\"name\":\"HoverTool\",\"id\":\"p1116\",\"attributes\":{\"renderers\":[{\"id\":\"p1076\"},{\"id\":\"p1066\"}],\"tooltips\":\"index: @index · group: @group · value: @top_data_value{0.000} · feature: @top_feature_name
\",\"sort_by\":null}},{\"type\":\"object\",\"name\":\"HoverTool\",\"id\":\"p1117\",\"attributes\":{\"renderers\":[{\"id\":\"p1085\"},{\"id\":\"p1094\"},{\"id\":\"p1103\"}],\"tooltips\":\"index: @index · group: @group
\",\"sort_by\":null}}]}},\"left\":[{\"type\":\"object\",\"name\":\"LinearAxis\",\"id\":\"p1034\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"BasicTicker\",\"id\":\"p1035\",\"attributes\":{\"mantissas\":[1,2,5]}},\"formatter\":{\"type\":\"object\",\"name\":\"BasicTickFormatter\",\"id\":\"p1036\"},\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1037\"}}}],\"right\":[{\"id\":\"p1113\"}],\"below\":[{\"type\":\"object\",\"name\":\"LinearAxis\",\"id\":\"p1029\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"BasicTicker\",\"id\":\"p1030\",\"attributes\":{\"mantissas\":[1,2,5]}},\"formatter\":{\"type\":\"object\",\"name\":\"BasicTickFormatter\",\"id\":\"p1031\"},\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1032\"}}}],\"center\":[{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1033\",\"attributes\":{\"axis\":{\"id\":\"p1029\"}}},{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1038\",\"attributes\":{\"dimension\":1,\"axis\":{\"id\":\"p1034\"}}}],\"output_backend\":\"webgl\"}}]}},{\"type\":\"object\",\"name\":\"Column\",\"id\":\"p1166\",\"attributes\":{\"styles\":{\"type\":\"map\",\"entries\":[[\"background-color\",\"white\"],[\"flex\",\"0 0 40%\"],[\"min-width\",\"0\"]]},\"sizing_mode\":\"stretch_both\",\"children\":[{\"id\":\"p1164\"},{\"id\":\"p1163\"},{\"type\":\"object\",\"name\":\"Figure\",\"id\":\"p1136\",\"attributes\":{\"sizing_mode\":\"stretch_both\",\"x_range\":{\"type\":\"object\",\"name\":\"DataRange1d\",\"id\":\"p1138\"},\"y_range\":{\"id\":\"p1135\"},\"x_scale\":{\"type\":\"object\",\"name\":\"LinearScale\",\"id\":\"p1145\"},\"y_scale\":{\"type\":\"object\",\"name\":\"CategoricalScale\",\"id\":\"p1146\"},\"title\":{\"type\":\"object\",\"name\":\"Title\",\"id\":\"p1143\"},\"renderers\":[{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1160\",\"attributes\":{\"data_source\":{\"id\":\"p1132\"},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1161\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1162\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"HBar\",\"id\":\"p1157\",\"attributes\":{\"y\":{\"type\":\"field\",\"field\":\"feature\"},\"height\":{\"type\":\"value\",\"value\":0.8},\"right\":{\"type\":\"field\",\"field\":\"mean\"},\"line_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"fill_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"hatch_color\":{\"type\":\"value\",\"value\":\"#756bb1\"}}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"HBar\",\"id\":\"p1158\",\"attributes\":{\"y\":{\"type\":\"field\",\"field\":\"feature\"},\"height\":{\"type\":\"value\",\"value\":0.8},\"right\":{\"type\":\"field\",\"field\":\"mean\"},\"line_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"line_alpha\":{\"type\":\"value\",\"value\":0.1},\"fill_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"fill_alpha\":{\"type\":\"value\",\"value\":0.1},\"hatch_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"hatch_alpha\":{\"type\":\"value\",\"value\":0.1}}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"HBar\",\"id\":\"p1159\",\"attributes\":{\"y\":{\"type\":\"field\",\"field\":\"feature\"},\"height\":{\"type\":\"value\",\"value\":0.8},\"right\":{\"type\":\"field\",\"field\":\"mean\"},\"line_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"line_alpha\":{\"type\":\"value\",\"value\":0.2},\"fill_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"fill_alpha\":{\"type\":\"value\",\"value\":0.2},\"hatch_color\":{\"type\":\"value\",\"value\":\"#756bb1\"},\"hatch_alpha\":{\"type\":\"value\",\"value\":0.2}}}}}],\"toolbar\":{\"type\":\"object\",\"name\":\"Toolbar\",\"id\":\"p1144\"},\"toolbar_location\":null,\"left\":[{\"type\":\"object\",\"name\":\"CategoricalAxis\",\"id\":\"p1152\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"CategoricalTicker\",\"id\":\"p1153\"},\"formatter\":{\"type\":\"object\",\"name\":\"CategoricalTickFormatter\",\"id\":\"p1154\"},\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1155\"}}}],\"below\":[{\"type\":\"object\",\"name\":\"LinearAxis\",\"id\":\"p1147\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"BasicTicker\",\"id\":\"p1148\",\"attributes\":{\"mantissas\":[1,2,5]}},\"formatter\":{\"type\":\"object\",\"name\":\"BasicTickFormatter\",\"id\":\"p1149\"},\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1150\"}}}],\"center\":[{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1151\",\"attributes\":{\"axis\":{\"id\":\"p1147\"},\"grid_line_color\":null}},{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1156\",\"attributes\":{\"dimension\":1,\"axis\":{\"id\":\"p1152\"}}}]}}]}}]}}]}};\n",
" const render_items = [{\"docid\":\"6845aeb6-12e5-4f93-afd7-f920f1f891ea\",\"roots\":{\"p1169\":\"bcb610ac-542d-4834-8b08-7e757dc51128\"},\"root_ids\":[\"p1169\"]}];\n",
" void root.Bokeh.embed.embed_items_notebook(docs_json, render_items);\n",
" }\n",
" if (root.Bokeh !== undefined) {\n",
" embed_document(root);\n",
" } else {\n",
" let attempts = 0;\n",
" const timer = setInterval(function(root) {\n",
" if (root.Bokeh !== undefined) {\n",
" clearInterval(timer);\n",
" embed_document(root);\n",
" } else {\n",
" attempts++;\n",
" if (attempts > 100) {\n",
" clearInterval(timer);\n",
" console.log(\"Bokeh: ERROR: Unable to run BokehJS code because BokehJS library is missing\");\n",
" }\n",
" }\n",
" }, 10, root)\n",
" }\n",
"})(window);"
],
"application/vnd.bokehjs_exec.v0+json": ""
},
"metadata": {
"application/vnd.bokehjs_exec.v0+json": {
"id": "p1169"
}
},
"output_type": "display_data"
}
],
"source": [
"from glass_box_umap.plotting import (\n",
" output_notebook,\n",
" plot_embedding,\n",
" show,\n",
")\n",
"\n",
"output_notebook(hide_banner=True)\n",
"\n",
"show(\n",
" plot_embedding(\n",
" Z=gb_umap_embedding,\n",
" contributions=contributions,\n",
" group_names=target,\n",
" feature_names=wine.columns,\n",
" feature_values=X,\n",
" )\n",
")"
]
},
{
"cell_type": "markdown",
"id": "4b8b797b",
"metadata": {},
"source": [
"Two toggles drive what you see:\n",
"\n",
"- Color by *(above the scatter)*:\n",
" * `Group` colors points by labels you supply (here, cultivar)\n",
" * `Feature` paints a gradient over the L2-reduced contribution of a single feature picked from an autocomplete\n",
" * `Top feature` colors each point by whichever feature contributes most at that point\n",
"\n",
"- View *(above the bar chart)*:\n",
" * `L2` is the magnitude of each feature's contribution to embedding position (always non-negative)\n",
" * `normed L2` is the same, however contributions are normalized per-sample such that they always sum to 1\n",
" * `Dim 1` and `Dim 2` are the signed contributions to the corresponding embedding axis.\n",
"\n",
"You can use the \"Lasso\" or \"box-select\" tools to restrict the bars to a custom cohort. With nothing selected, the bars summarize all samples.\n",
"\n",
"---\n",
"\n",
"Here are a few observations:\n",
"\n",
"1. **Proline holds cultivar 0 together.** Switch *Color by* to **Top feature** and the bottom-right cluster lights up as proline. Lasso it and look at **normed L2**: proline accounts for ~17% of the average sample's reconstruction there, compared to ~8% and ~4% for cultivars 1 and 2.\n",
"\n",
"2. **Flavanoids is a polarity feature: same magnitude, opposite sign at the two ends.** It has the largest mean L2 globally, but switching the bar chart to **Dim 1** and lassoing each cluster shows it flips sign. Strongly positive (push right) inside cultivar 0 and strongly negative (push left) inside cultivar 2. Switching *Color by* to **Feature**, selecting flavanoids, and hovering over datapoints in cultivars 0 and 2 reveal that the standard-normalized flavanoid values (i.e., values in `X` -- not `contributions`) are negative (below average) for cultivar 2 and positive (above average) for cultivar 0.\n",
"\n",
"3. **Color intensity is uniquely prominent in cultivar 2**. Interestingly, members of cultivar 1 that leak towards the cultivar 2 cluster have upweighted color intensity contributions, further evidencing that color intensity is a unifying feature of the cultivar 2 cluster.\n",
"\n",
"4. **Ash drives sub-clustering in cultivar 0**. Color by ash and notice the rightmost members of cultivar 0 light up. Lasso these points and see that ash is the dominant contributor of these points. This is despite the fact that proline and flavanoids are the dominant contributors of cultivar 0 as a whole. This suggests that features that separate a cluster from the others are not always the features that define local positioning of points within.\n",
"\n",
"## Conclusion\n",
"\n",
"`GlassBoxUMAP` behaves like any other UMAP implementation for fitting and transforming, and adds `compute_contributions`: a per-feature attribution that sums exactly to the embedding. `contributions` is just a NumPy array, safe to plug into any downstream analysis. The interactive plot used in this guide is one starting point.\n",
"\n",
"From here, [Saving & Loading](saving_and_loading.ipynb) covers persisting fitted models to disk, and [Embedding Comparison](embedding_comparison.ipynb) compares Glass Box UMAP against standard UMAP on a variety of datasets."
]
}
],
"metadata": {
"jupytext": {
"formats": "ipynb,py:percent"
},
"kernelspec": {
"display_name": "glass-box-umap (3.13.1)",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.13.1"
}
},
"nbformat": 4,
"nbformat_minor": 5
}