docs: add example plots and interactive tree to documentation

Author: aivuk

docs/assets/images/cluster_heatmap.png

@@ -0,0 +1,2 @@
+<div>                        <script>window.PlotlyConfig = {MathJaxConfig: 'local'};</script>
+        <script charset="utf-8" src="https://cdn.plot.ly/plotly-3.4.0.min.js" integrity="sha256-KEmPoupLpFyGMyGAiOsiNDbKDKAvxXAn/W+oQa0ZAfk=" crossorigin="anonymous"></script>                <div id="f2d760f7-0763-49d2-abad-fb44719dffe5" class="plotly-graph-div" style="height:100%; width:100%;"></div>            <script>                window.PLOTLYENV=window.PLOTLYENV || {};                                if (document.getElementById("f2d760f7-0763-49d2-abad-fb44719dffe5")) {                    Plotly.newPlot(                        "f2d760f7-0763-49d2-abad-fb44719dffe5",                        [{"hoverinfo":"none","line":{"color":"lightgray","width":1},"mode":"lines","x":[0.3888817414335363,0.36617756926900175,null,0.4852118896695189,0.36139871518170114,null,-0.42216803624454435,-0.7559570822648302,null,-0.42216803624454435,-0.2404132982292021,null,-0.42216803624454435,-0.24275714221110156,null,-0.7559570822648302,-0.9636964177966363,null,-0.2404132982292021,-0.03760165438796734,null,-0.053013093577543746,0.11042649318149739,null,-0.053013093577543746,-0.24275714221110156,null,0.3809160415318499,0.36139871518170114,null,0.36617756926900175,0.36139871518170114,null,0.1214637890485378,0.36139871518170114,null,0.1214637890485378,-0.03760165438796734,null,0.36139871518170114,0.5011304853961827,null],"y":[0.7713453421410312,0.611932818281781,null,0.4968798819211464,0.42047170098405773,null,-0.33752684852077935,-0.3026507328715368,null,-0.33752684852077935,-0.048706526748209855,null,-0.33752684852077935,-0.6293591330323334,null,-0.3026507328715368,-0.26848441383430593,null,-0.048706526748209855,0.17813932061009885,null,-0.8397743431856491,-1.0,null,-0.8397743431856491,-0.6293591330323334,null,0.29205036198912815,0.42047170098405773,null,0.611932818281781,0.42047170098405773,null,0.2907975241478882,0.42047170098405773,null,0.2907975241478882,0.17813932061009885,null,0.42047170098405773,0.36488504811768296,null],"type":"scatter"},{"hoverinfo":"text","hovertext":["Cluster 0\u003cbr\u003eSize: 800","Cluster 1\u003cbr\u003eSize: 600","Cluster 2\u003cbr\u003eSize: 143","Cluster 3\u003cbr\u003eSize: 111","Cluster 4\u003cbr\u003eSize: 16","Cluster 5\u003cbr\u003eSize: 1","Cluster 6\u003cbr\u003eSize: 33","Cluster 7\u003cbr\u003eSize: 0","Cluster 8\u003cbr\u003eSize: 13","Cluster 9\u003cbr\u003eSize: 400","Cluster 10\u003cbr\u003eSize: 181","Cluster 11\u003cbr\u003eSize: 30","Cluster 12\u003cbr\u003eSize: 50","Cluster 13\u003cbr\u003eSize: 2","Cluster 14\u003cbr\u003eSize: 0"],"marker":{"color":[4.969681557735544,1.046107570132383,0.02939936100086413,0.45454437995690994,-0.3990981408827592,0.3182347164972426,-1.0765947104987057,0.0,-0.20022622356597952,6.950274929214093,-0.1331560428261692,1.982546099645788,3.0268330586848538,0.5838227937416858,0.0],"colorbar":{"title":{"text":"Median CD3"}},"colorscale":[[0.0,"#440154"],[0.1111111111111111,"#482878"],[0.2222222222222222,"#3e4989"],[0.3333333333333333,"#31688e"],[0.4444444444444444,"#26828e"],[0.5555555555555556,"#1f9e89"],[0.6666666666666666,"#35b779"],[0.7777777777777778,"#6ece58"],[0.8888888888888888,"#b5de2b"],[1.0,"#fde725"]],"line":{"color":"white","width":1},"showscale":true,"size":[50.0,40.0,17.15,15.55,10.8,10.05,11.65,10.0,10.65,30.0,19.05,11.5,12.5,10.1,10.0]},"mode":"markers+text","text":["0","1","2","3","4","5","6","7","8","9","10","11","12","13","14"],"textposition":"top center","x":[0.3888817414335363,0.4852118896695189,-0.42216803624454435,-0.7559570822648302,-0.2404132982292021,-0.9636964177966363,-0.053013093577543746,0.3809160415318499,0.11042649318149739,0.36617756926900175,-0.24275714221110156,0.1214637890485378,0.36139871518170114,-0.03760165438796734,0.5011304853961827],"y":[0.7713453421410312,0.4968798819211464,-0.33752684852077935,-0.3026507328715368,-0.048706526748209855,-0.26848441383430593,-0.8397743431856491,0.29205036198912815,-1.0,0.611932818281781,-0.6293591330323334,0.2907975241478882,0.42047170098405773,0.17813932061009885,0.36488504811768296],"type":"scatter"}],                        {"plot_bgcolor":"white","showlegend":false,"title":{"text":"SPADE Tree"},"xaxis":{"showgrid":false,"showticklabels":false,"zeroline":false},"yaxis":{"showgrid":false,"showticklabels":false,"zeroline":false},"template":{"data":{"histogram2dcontour":[{"type":"histogram2dcontour","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"choropleth":[{"type":"choropleth","colorbar":{"outlinewidth":0,"ticks":""}}],"histogram2d":[{"type":"histogram2d","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"heatmap":[{"type":"heatmap","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"contourcarpet":[{"type":"contourcarpet","colorbar":{"outlinewidth":0,"ticks":""}}],"contour":[{"type":"contour","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"surface":[{"type":"surface","colorbar":{"outlinewidth":0,"ticks":""},"colorscale":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]]}],"mesh3d":[{"type":"mesh3d","colorbar":{"outlinewidth":0,"ticks":""}}],"scatter":[{"fillpattern":{"fillmode":"overlay","size":10,"solidity":0.2},"type":"scatter"}],"parcoords":[{"type":"parcoords","line":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterpolargl":[{"type":"scatterpolargl","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"bar":[{"error_x":{"color":"#2a3f5f"},"error_y":{"color":"#2a3f5f"},"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"bar"}],"scattergeo":[{"type":"scattergeo","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterpolar":[{"type":"scatterpolar","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"histogram":[{"marker":{"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"histogram"}],"scattergl":[{"type":"scattergl","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatter3d":[{"type":"scatter3d","line":{"colorbar":{"outlinewidth":0,"ticks":""}},"marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattermap":[{"type":"scattermap","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattermapbox":[{"type":"scattermapbox","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scatterternary":[{"type":"scatterternary","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"scattercarpet":[{"type":"scattercarpet","marker":{"colorbar":{"outlinewidth":0,"ticks":""}}}],"carpet":[{"aaxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"baxis":{"endlinecolor":"#2a3f5f","gridcolor":"white","linecolor":"white","minorgridcolor":"white","startlinecolor":"#2a3f5f"},"type":"carpet"}],"table":[{"cells":{"fill":{"color":"#EBF0F8"},"line":{"color":"white"}},"header":{"fill":{"color":"#C8D4E3"},"line":{"color":"white"}},"type":"table"}],"barpolar":[{"marker":{"line":{"color":"#E5ECF6","width":0.5},"pattern":{"fillmode":"overlay","size":10,"solidity":0.2}},"type":"barpolar"}],"pie":[{"automargin":true,"type":"pie"}]},"layout":{"autotypenumbers":"strict","colorway":["#636efa","#EF553B","#00cc96","#ab63fa","#FFA15A","#19d3f3","#FF6692","#B6E880","#FF97FF","#FECB52"],"font":{"color":"#2a3f5f"},"hovermode":"closest","hoverlabel":{"align":"left"},"paper_bgcolor":"white","plot_bgcolor":"#E5ECF6","polar":{"bgcolor":"#E5ECF6","angularaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"radialaxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"ternary":{"bgcolor":"#E5ECF6","aaxis":{"gridcolor":"white","linecolor":"white","ticks":""},"baxis":{"gridcolor":"white","linecolor":"white","ticks":""},"caxis":{"gridcolor":"white","linecolor":"white","ticks":""}},"coloraxis":{"colorbar":{"outlinewidth":0,"ticks":""}},"colorscale":{"sequential":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"sequentialminus":[[0.0,"#0d0887"],[0.1111111111111111,"#46039f"],[0.2222222222222222,"#7201a8"],[0.3333333333333333,"#9c179e"],[0.4444444444444444,"#bd3786"],[0.5555555555555556,"#d8576b"],[0.6666666666666666,"#ed7953"],[0.7777777777777778,"#fb9f3a"],[0.8888888888888888,"#fdca26"],[1.0,"#f0f921"]],"diverging":[[0,"#8e0152"],[0.1,"#c51b7d"],[0.2,"#de77ae"],[0.3,"#f1b6da"],[0.4,"#fde0ef"],[0.5,"#f7f7f7"],[0.6,"#e6f5d0"],[0.7,"#b8e186"],[0.8,"#7fbc41"],[0.9,"#4d9221"],[1,"#276419"]]},"xaxis":{"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","automargin":true,"zerolinewidth":2},"yaxis":{"gridcolor":"white","linecolor":"white","ticks":"","title":{"standoff":15},"zerolinecolor":"white","automargin":true,"zerolinewidth":2},"scene":{"xaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2},"yaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2},"zaxis":{"backgroundcolor":"#E5ECF6","gridcolor":"white","linecolor":"white","showbackground":true,"ticks":"","zerolinecolor":"white","gridwidth":2}},"shapedefaults":{"line":{"color":"#2a3f5f"}},"annotationdefaults":{"arrowcolor":"#2a3f5f","arrowhead":0,"arrowwidth":1},"geo":{"bgcolor":"white","landcolor":"#E5ECF6","subunitcolor":"white","showland":true,"showlakes":true,"lakecolor":"white"},"title":{"x":0.05},"mapbox":{"style":"light"}}}},                        {"responsive": true}                    )                };            </script>        </div>

docs/assets/images/condition_comparison.png

@@ -32,14 +32,16 @@ print(spade.result_.cluster_stats_)
 
 ```python
 # Static matplotlib plot
-fig = spade.result_.plot_tree(color_by="CD4", backend="matplotlib")
+fig = spade.result_.plot_tree(color_by="CD3", backend="matplotlib")
 fig.savefig("tree.png", dpi=150)
 
 # Interactive plotly plot
-fig = spade.result_.plot_tree(color_by="CD4", backend="plotly")
+fig = spade.result_.plot_tree(color_by="CD3", backend="plotly")
 fig.show()
 ```
 
+![Example SPADE tree](../assets/images/tree_cd3.png)
+
 ## Choosing parameters
 
 | Parameter | Default | Guidance |

docs/assets/images/tree_basic.png

@@ -36,6 +36,32 @@ print(spade.result_.cluster_stats_)
 spade.result_.plot_tree(color_by=0, backend="matplotlib")
 ```
 
+## Example outputs
+
+### Tree colored by marker expression
+
+Nodes are sized by cell count. Color shows median CD3 expression -- high (yellow) in T cell clusters, low (purple) elsewhere.
+
+![SPADE tree colored by CD3](assets/images/tree_cd3.png)
+
+### Condition comparison
+
+Red nodes are enriched in the disease condition, blue in healthy. Cluster 5 (dark red) contains a rare population expanded in disease.
+
+![Condition comparison](assets/images/condition_comparison.png)
+
+### Cluster heatmap
+
+Median marker expression per cluster reveals distinct cell populations.
+
+![Cluster heatmap](assets/images/cluster_heatmap.png)
+
+### Interactive visualization
+
+densitree also supports interactive plotly trees -- hover for cluster details, zoom and pan.
+
+<iframe src="assets/images/tree_interactive.html" width="100%" height="500" frameborder="0"></iframe>
+
 ## Installation
 
 ```bash

docs/assets/images/tree_cd19.png

@@ -128,6 +128,8 @@ fig.savefig("condition_comparison.png", dpi=150, bbox_inches="tight")
 
 Blue nodes are enriched in healthy, red nodes in disease. The rare population cluster should appear as a bright red node.
 
+![Condition comparison](../assets/images/condition_comparison.png)
+
 ## Statistical testing (advanced)
 
 For rigorous comparison with biological replicates, use a per-cluster test:

docs/assets/images/tree_cd3.png

@@ -68,23 +68,31 @@ print(stats.nsmallest(5, "size")[["size"]])
 ### Visualize the tree
 
 ```python
-# Color by CD4 expression
-fig = spade.result_.plot_tree(color_by="CD4", size_by="count", backend="matplotlib")
-fig.savefig("spade_tree_cd4.png", dpi=150, bbox_inches="tight")
+# Color by CD3 expression
+fig = spade.result_.plot_tree(color_by="CD3", size_by="count", backend="matplotlib")
+fig.savefig("spade_tree_cd3.png", dpi=150, bbox_inches="tight")
+```
+
+![Tree colored by CD3](../assets/images/tree_cd3.png)
 
-# Color by CD8
-fig = spade.result_.plot_tree(color_by="CD8", size_by="count", backend="matplotlib")
-fig.savefig("spade_tree_cd8.png", dpi=150, bbox_inches="tight")
+```python
+# Color by CD19 (B cell marker)
+fig = spade.result_.plot_tree(color_by="CD19", size_by="count", backend="matplotlib")
+fig.savefig("spade_tree_cd19.png", dpi=150, bbox_inches="tight")
 ```
 
+![Tree colored by CD19](../assets/images/tree_cd19.png)
+
 ### Interactive exploration with plotly
 
 ```python
-fig = spade.result_.plot_tree(color_by="CD4", backend="plotly")
+fig = spade.result_.plot_tree(color_by="CD3", backend="plotly")
 fig.write_html("spade_tree_interactive.html")
 # or fig.show() in a notebook
 ```
 
+<iframe src="../assets/images/tree_interactive.html" width="100%" height="500" frameborder="0"></iframe>
+
 ### Work with the tree directly
 
 ```python