31:[] 2f:{"title":"Introducing Sankey Plus","cells":[{"id":0,"value":"# Introducing Sankey Plus","pinned":false,"hidden":false,"mode":"md"},{"id":80,"value":"Welcome to the new [Sankey-Plus](https://github.com/tomshanley/sankey-plus) module. \n\nThis library builds upon the [d3-sankey](https://github.com/d3/d3-sankey) and [d3-sankey-circular]( https://github.com/tomshanley/d3-sankey-circular) libraries, and my testing of new options in various Observable notebooks.\n\nSankey-Plus introduces the following new features:\n* the concept of virtual nodes and links, which allows for nice routing of links around other nodes\n* arrows on the links to show direction\n* a new API that allows for easy sankey generation and drawing within a specified DOM element.\n\nThank you to [Ralph Spandl](https://twitter.com/ralph_spandl) for the testing, suggesting improvements, providing updates to the code and helping set up the NPM module.","pinned":false,"hidden":false,"mode":"md"},{"id":282,"value":"toc(\"h2,h3,h4\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":285,"value":"## Instructions","pinned":false,"hidden":false,"mode":"md"},{"id":95,"value":"### 1. Import the sankey-plus module","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"sankeyPlus = import(\"https://cdn.skypack.dev/sankey-plus@0.6.0?min\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":99,"value":"### 2. Add some nodes and links data","pinned":false,"hidden":false,"mode":"md"},{"id":9,"value":"nodes = [\n { name: \"node1\" },\n { name: \"node2\" },\n { name: \"node3\" },\n { name: \"node4\" },\n { name: \"node5\" },\n { name: \"node6\" },\n { name: \"node7\" },\n { name: \"node8\" }\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":12,"value":"links = [\n { source: \"node4\", target: \"node1\", value: 20 },\n { source: \"node1\", target: \"node8\", value: 20 },\n { source: \"node1\", target: \"node6\", value: 20 },\n { source: \"node2\", target: \"node7\", value: 20 },\n { source: \"node2\", target: \"node3\", value: 40 },\n { source: \"node3\", target: \"node8\", value: 40 },\n { source: \"node5\", target: \"node7\", value: 20 },\n { source: \"node4\", target: \"node6\", value: 20 },\n { source: \"node2\", target: \"node8\", value: 20 },\n { source: \"node6\", target: \"node1\", value: 20 },\n { source: \"node8\", target: \"node7\", value: 80 },\n { source: \"node4\", target: \"node3\", value: 80 },\n { source: \"node8\", target: \"node3\", value: 10 },\n { source: \"node8\", target: \"node2\", value: 10 }\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":103,"value":"### 3. Set the config","pinned":false,"hidden":false,"mode":"md"},{"id":171,"value":"The ```nodes.data``` and ```links.data``` are mandatory in the config object. The remaining config can be set or left to the defaults. \n\nI will set the width, so that it fits within the usual Observable cell ```width```.","pinned":false,"hidden":false,"mode":"md"},{"id":15,"value":"sankeyConfig = ({\n width: width,\n nodes: {\n data: clone(nodes)\n },\n links: {\n data: clone(links)\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":107,"value":"### 4. Create the sankey object","pinned":false,"hidden":false,"mode":"md"},{"id":153,"value":"Run the ```.process()``` method to calculate the node and link positions.","pinned":false,"hidden":false,"mode":"md"},{"id":55,"value":"sankey = {\n let obj = new sankeyPlus.SankeyChart(sankeyConfig);\n obj.process();\n return obj;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":111,"value":"### 5. ... And draw","pinned":false,"hidden":false,"mode":"md"},{"id":159,"value":"Call the ```.draw()``` method, which requires the ID of a DOM element (typcially a div container) in which to draw the SVG sankey chart.","pinned":false,"hidden":false,"mode":"md"},{"id":60,"value":"chart = {\n let containerId = \"chart-div\";\n let container = d3.create(\"div\").attr(\"id\", containerId);\n\n //div needs to be rendered for the .draw() method to work with Observable\n yield container.node();\n\n sankey.draw(containerId);\n\n return container.node();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":424,"value":"I think this chart's layout could be improved, so below we can tinker with the options to improve the look and readability.\n\nPersonally, I would\n* set the ```virtualLinkType``` to just use 'virtual'\n* increase the padding between virtual links and nodes\n* set the links' opacity to 0.5 and enable the arrows, like so:","pinned":false,"hidden":false,"mode":"md"},{"id":427,"value":"exampleChart = draw(\n {\n width: width,\n height: 400,\n nodes: { data: clone(nodes), virtualNodePadding: 25 },\n links: { virtualLinkType: \"virtual\", opacity: 0.5, data: clone(links) },\n arrows: { enabled: true, color: \"grey\", length: 10, gap: 50 }\n },\n \"chart-exampleChart-div\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":176,"value":"## Options\n\nSome of the options will be familiar if you have used the [d3.sankey](https://github.com/d3/d3-sankey) library, and some are new for sankey-plus.","pinned":false,"hidden":false,"mode":"md"},{"id":179,"value":"### align","pinned":false,"hidden":false,"mode":"md"},{"id":375,"value":"viewof align = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":363,"value":"alignChart = draw(\n {\n width: width,\n align: align,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) }\n },\n \"chart-align-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":199,"value":"### id","pinned":false,"hidden":false,"mode":"md"},{"id":182,"value":"### padding","pinned":false,"hidden":false,"mode":"md"},{"id":190,"value":"### width and height","pinned":false,"hidden":false,"mode":"md"},{"id":386,"value":"viewof sankeyWidth = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":390,"value":"viewof sankeyHeight = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":358,"value":"whChart = draw(\n {\n width: sankeyWidth,\n height: sankeyHeight,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) }\n },\n \"chart-wh-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":255,"value":"### nodes","pinned":false,"hidden":false,"mode":"md"},{"id":193,"value":"#### nodes.data","pinned":false,"hidden":false,"mode":"md"},{"id":197,"value":"#### nodes.padding","pinned":false,"hidden":false,"mode":"md"},{"id":206,"value":"#### nodes.minPadding","pinned":false,"hidden":false,"mode":"md"},{"id":209,"value":"#### nodes.virtualPadding","pinned":false,"hidden":false,"mode":"md"},{"id":214,"value":"#### nodes.fill","pinned":false,"hidden":false,"mode":"md"},{"id":544,"value":"viewof nodeFill = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":356,"value":"fillChart = draw(\n {\n width: width,\n nodes: { fill: nodeFill, data: clone(nodes) },\n links: { data: clone(links) }\n },\n \"chart-fillnode-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":217,"value":"#### nodes.stroke","pinned":false,"hidden":false,"mode":"md"},{"id":550,"value":"viewof nodeStroke = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":353,"value":"strokeChart = draw(\n {\n width: width,\n nodes: { stroke: nodeStroke, data: clone(nodes) },\n links: { data: clone(links) }\n },\n \"chart-nodestroke-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":220,"value":"#### nodes.opacity","pinned":false,"hidden":false,"mode":"md"},{"id":341,"value":"nodeOpacityChart = draw(\n {\n width: width,\n nodes: { opacity: 0.5, data: clone(nodes) },\n links: { data: clone(links) }\n },\n \"chart-nodeopacity-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":259,"value":"### links","pinned":false,"hidden":false,"mode":"md"},{"id":224,"value":"#### links.color","pinned":false,"hidden":false,"mode":"md"},{"id":555,"value":"viewof linkColor = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":447,"value":"linkStrokeChart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { color: linkColor, data: clone(links) }\n },\n \"chart-linkstroke-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":232,"value":"#### links.circularGap\n\nThe distance in pixels between any circular links, which are drawn next to each other","pinned":false,"hidden":false,"mode":"md"},{"id":453,"value":"circularGapChart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: {\n circularGap: 20,\n data: clone(links)\n }\n },\n \"chart-circulargap-div\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":234,"value":"#### links.circularLinkPortionTopBottom","pinned":true,"hidden":false,"mode":"md"},{"id":237,"value":"#### links.circularLinkPortionLeftRight","pinned":true,"hidden":false,"mode":"md"},{"id":239,"value":"#### links.opacity","pinned":false,"hidden":false,"mode":"md"},{"id":565,"value":"viewof linkOpacity = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":567,"value":"linkOpacity","pinned":false,"hidden":false,"mode":"ojs"},{"id":409,"value":"linkOpacityChart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { opacity: linkOpacity, data: clone(links) }\n },\n \"chart-linkopacity-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":581,"value":"#### links.useVirtualRoutes\n\nThe sankey-plus process can render links that pass around other nodes by either drawing a bezier curve or using virtual nodes, which allow for intermediary points to be laid out so they do not overlap other nodes.","pinned":false,"hidden":false,"mode":"md"},{"id":598,"value":"simpleNodes = [{ name: \"node1\" }, { name: \"node2\" }, { name: \"node3\" }]","pinned":true,"hidden":false,"mode":"ojs"},{"id":603,"value":"simpleLinks = [\n { source: \"node1\", target: \"node2\", value: 1 },\n { source: \"node2\", target: \"node3\", value: 1 },\n { source: \"node1\", target: \"node3\", value: 1 }\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":646,"value":"draw(\n {\n width: width,\n nodes: { data: clone(simpleNodes) },\n links: { data: clone(simpleLinks), useVirtualRoutes: true }\n },\n \"chart-virtualRoutes-div\"\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":241,"value":"#### links.virtualLinkType\n\nYou can force the chart to always use \"virtual\" links, or always use bezier curves, or allow the process to select the virtual links if it finds that the bezier curve may overlap another node. \n\nThe option to use bezier is not the same as disabling virtual links, as the process will still try to shift other nodes into better postions to avoid overlaps, which may allow for bezier curves to not overlap. But this can't be guaranteed :).","pinned":false,"hidden":false,"mode":"md"},{"id":415,"value":"viewof virtualRoutes = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":412,"value":"virtualLinkChart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { virtualLinkType: virtualRoutes, data: clone(links) }\n },\n \"chart-linkvirtual-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":243,"value":"#### links.baseRadius","pinned":true,"hidden":false,"mode":"md"},{"id":245,"value":"#### links.verticalMargin","pinned":true,"hidden":false,"mode":"md"},{"id":228,"value":"#### links.virtualLinkType","pinned":true,"hidden":false,"mode":"md"},{"id":262,"value":"### arrows\n\nI find arrows are useful for sankey charts where there are links going backwards, as sometimes its not obvious which direction the link is going.","pinned":false,"hidden":false,"mode":"md"},{"id":268,"value":"#### arrows.enabled\n\nBy default arrows are not enabled.","pinned":false,"hidden":false,"mode":"md"},{"id":501,"value":"arrowsEnabledChart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) },\n arrows: { enabled: true }\n },\n \"chart-arrowsenabled-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":270,"value":"#### arrows.color","pinned":false,"hidden":false,"mode":"md"},{"id":503,"value":"arrowsColorChart = draw(\n { \n width: width,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) },\n arrows: { enabled: true, color: \"yellow\" }\n },\n \"chart-arrowscolor-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":272,"value":"#### arrows.length","pinned":false,"hidden":false,"mode":"md"},{"id":529,"value":"viewof arrowLength = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":534,"value":"arrowLength","pinned":false,"hidden":false,"mode":"ojs"},{"id":507,"value":"chartarrowslength = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) },\n arrows: { enabled: true, length: arrowLength }\n },\n \"chart-arrowslength-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":274,"value":"#### arrows.gap","pinned":true,"hidden":false,"mode":"md"},{"id":522,"value":"viewof arrowGap = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":526,"value":"arrowGap","pinned":false,"hidden":false,"mode":"ojs"},{"id":509,"value":"arrowsgapchart = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) },\n arrows: { enabled: true, gap: arrowGap }\n },\n \"chart-arrowsgap-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":265,"value":"#### arrows.headSize","pinned":false,"hidden":false,"mode":"md"},{"id":511,"value":"headsize = draw(\n {\n width: width,\n nodes: { data: clone(nodes) },\n links: { data: clone(links) },\n arrows: { enabled: true, headSize: 7 }\n },\n \"chart-headsize-div\"\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":148,"value":"## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":347,"value":"function* draw(config, divID) {\n let s = new sankeyPlus.SankeyChart(config);\n s.process();\n\n let divHeight = config.height ? config.height + \"px\" : \"500px\";\n\n let container = d3\n .create(\"div\")\n .attr(\"id\", divID)\n .style(\"height\", divHeight)\n .style(\"display\", \"block\");\n\n yield container.node();\n\n s.draw(divID);\n\n return container.node();\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":5,"value":"d3v7_esm = import(\"https://cdn.skypack.dev/d3@7\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":139,"value":"clone = require(\"https://bundle.run/clone@2.1.2\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":279,"value":"import { toc } from \"@tomshanley/indented-toc\"","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}