{"id":14966004,"url":"https://github.com/antononcube/raku-javascript-d3","last_synced_at":"2026-01-27T13:02:30.541Z","repository":{"id":64793625,"uuid":"577093610","full_name":"antononcube/Raku-JavaScript-D3","owner":"antononcube","description":"Raku package that generates JavaScript D3.js code for plots and charts. ","archived":false,"fork":false,"pushed_at":"2025-12-04T01:15:47.000Z","size":1394,"stargazers_count":7,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-07T07:21:51.938Z","etag":null,"topics":["code-generation","d3","d3js","javascript","jupyter-notebook","raku"],"latest_commit_sha":null,"homepage":"https://raku.land/zef:antononcube/JavaScript::D3","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antononcube.png","metadata":{"files":{"readme":"README-work.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-12-11T23:53:16.000Z","updated_at":"2025-12-04T01:15:51.000Z","dependencies_parsed_at":"2024-01-06T23:21:27.420Z","dependency_job_id":"37ac4e77-40fd-44a9-957d-f278943b4759","html_url":"https://github.com/antononcube/Raku-JavaScript-D3","commit_stats":{"total_commits":383,"total_committers":2,"mean_commits":191.5,"dds":0.007832898172323799,"last_synced_commit":"9867e73007fbbd9b4de1a220be6e036bd235df5d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/antononcube/Raku-JavaScript-D3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antononcube%2FRaku-JavaScript-D3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antononcube%2FRaku-JavaScript-D3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antononcube%2FRaku-JavaScript-D3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antononcube%2FRaku-JavaScript-D3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antononcube","download_url":"https://codeload.github.com/antononcube/Raku-JavaScript-D3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antononcube%2FRaku-JavaScript-D3/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28813224,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","d3","d3js","javascript","jupyter-notebook","raku"],"created_at":"2024-09-24T13:35:40.807Z","updated_at":"2026-01-27T13:02:30.519Z","avatar_url":"https://github.com/antononcube.png","language":"Raku","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JavaScript::D3 Raku package\n\n[![SparrowCI](https://ci.sparrowhub.io/project/gh-antononcube-Raku-JavaScript-D3/badge)](https://ci.sparrowhub.io)\n\nThis repository has the Raku package for generation of \n[JavaScript's D3](https://d3js.org/what-is-d3) \ncode for making plots and charts.\n\nThis package is intended to be used in Jupyter notebooks with the\n[Raku kernel implemented by Brian Duggan](https://github.com/bduggan/raku-jupyter-kernel), [BD1], or\n[\"Jupyter::Chatbook\"](https://github.com/antononcube/Raku-Jupyter-Chatbook), [AAp4].\nThe commands of the package generate JavaScript code that produces (nice) [D3.js](https://d3js.org/) plots or charts.\nSee the video [AAv1].\n\nThe package JavaScript graphs can be also included in HTML and Markdown documents.\nSee the videos [AAv2, AAv3].\n\nFor illustrative examples see the Jupyter notebook\n[\"Tests-for-JavaScript-D3\"](https://nbviewer.org/github/antononcube/Raku-JavaScript-D3/blob/main/resources/Tests-for-JavaScript-D3.ipynb).\n\nThe (original versions of the) JavaScript snippets used in this package are (mostly) taken from\n[\"The D3.js Graph Gallery\"](https://d3-graph-gallery.com/index.html).\n\nHere is a corresponding video demo (≈7 min): [\"The Raku-ju hijack hack of D3.js\"](https://www.youtube.com/watch?v=YIhx3FBWayo) (≈ 7 min.)\n\nAnd here is the demo notebook:\n[\"The-Raku-ju-hijack-hack-for-D3.js-demo\"](https://nbviewer.org/github/antononcube/Raku-JavaScript-D3/blob/main/resources/The-Raku-ju-hijack-hack-for-D3.js-demo.ipynb).\n\n--------\n\n## Mission statement\n\nMake first class -- beautiful, tunable, and useful -- plots and charts with Raku using \nconcise specifications.\n\n--------\n\n## Design and philosophy\n\nHere is a list of guiding design principles:\n\n- Concise plot and charts specifications.\n\n- Using Mathematica's plot functions for commands signatures inspiration. \n  (Instead of, say, R's [\"ggplot2\"](https://ggplot2.tidyverse.org).)\n\n  - For example, see [`ListPlot`](https://reference.wolfram.com/language/ref/ListPlot.html), \n    [`BubbleChart`](https://reference.wolfram.com/language/ref/BubbleChart.html).\n  \n- The primary target data structure to visualize is an array of hashes, \n   with all array elements having one of these sets of keys \n   - `\u003cx y\u003e` \n   - `\u003cx y group\u003e`\n   - `\u003cx y z\u003e`\n   - `\u003cx y z group\u003e` \n   \n- Multiple-dataset plots are produced via dataset records that have the key \"group\".  \n\n- Whenever possible deduce the keys from arrays of scalars.\n\n- The data reshaping functions in \"Data::Reshapers\", [AAp1], should fit nicely into workflows with this package.\n\n- The package functions are tested separately:\n\n  - As Raku functions that produce output for given signatures\n  - As JavaScript plots that correspond to the corresponding intents\n  \n--------\n\n## How does it work?\n\nHere is a diagram that summarizes the evaluation path from a Raku plot spec to a browser diagram:\n\n```mermaid\ngraph TD\n   Raku{{Raku}}\n   IRaku{{\"Raku\u003cbr\u003eJupyter kernel\"}}\n   Jupyter{{Jupyter}}\n   JS{{JavaScript}}\n   RakuInput[/Raku code input/]\n   JSOutput[/JavaScript code output/]\n   CellEval[Cell evaluation]\n   JSResDisplay[JavaScript code result display]\n   Jupyter -.-\u003e |1|IRaku -.-\u003e |2|Raku -.-\u003e |3|JSOutput -.-\u003e |4|Jupyter\n   Jupyter -.-\u003e |5|JS -.-\u003e |6|JSResDisplay\n   RakuInput ---\u003e CellEval ---\u003e Jupyter  ---\u003e JSResDisplay\n```\n\nHere is the corresponding narration:\n\n1. Enter Raku plot command in cell that starts with \n   [the magic spec `%% js`](https://github.com/bduggan/raku-jupyter-kernel/issues/100#issuecomment-1349494169).\n\n   - Like `js-d3-list-plot((^12)\u003e\u003e.rand)`.\n   \n2. Jupyter via the Raku kernel evaluates the Raku plot command.\n\n3. The Raku plot command produces JavaScript code.\n\n4. The Jupyter \"lets\" the web browser to evaluate the obtained JavaScript code.\n\n   - Instead of web browser, say, Visual Studio Code can be used.\n\n   \nThe evaluation loop spelled out above is possible because of the magics implementation in the Raku package\n[Jupyter::Kernel](https://github.com/bduggan/raku-jupyter-kernel#features), \n[BD1].\n   \n--------\n\n## Alternatives\n\n### Raku packages\n\nThe Raku packages \"Text::Plot\", [AAp2], and \"SVG::Plot\", [MLp1],\nprovide similar functionalities and both can be used in Jupyter notebooks. \n(Well, \"Text::Plot\" can be used anywhere.)\n\n### Different backend\n\nInstead of using [D3.js](https://d3js.org) as a \"backend\" it is possible -- and instructive --\nto implement Raku plotting functions that generate JavaScript code for the library \n[Chart.js](https://www.chartjs.org).\n\nD3.js is lower level than Chart.js, hence in principle Chart.js is closer to the mission of this Raku package.\nI.e. at first I considered having Raku plotting implementations with Chart.js\n(in a package called \"JavaScript::Chart\".)\nBut I had hard time making Chart.js plots work consistently within Jupyter.\n\n--------\n\n## Command Line Interface (CLI)\n\nThe package provides a CLI script that can be used to generate HTML files with plots or charts.\n\n```shell\njs-d3-graphics --help\n```\n\nHere is an usage example that produces a list line plot:\n\n```shell\njs-d3-graphics list-line-plot 1 2 2 12 33 41 15 5 -t=\"Nice plot\" --x-label=\"My X\" --y-label=\"My Y\" \u003e out.html \u0026\u0026 open out.html\n```\n\nHere is an example that produces bubble chart:\n\n```shell\njs-d3-graphics bubble-chart \"1,1,10 2,2,12 33,41,15 5,3,30\" -t=\"Nice plot\" --x-label=\"My X\" --y-label=\"My Y\" \u003e out.html \u0026\u0026 open out.html\n```\n\nHere is an example that produces a random mandala:\n\n```shell\njs-d3-graphics random-mandala 1 --margins=100 -h=1000 -w=1000 --color='rgb(120,120,120)' --background='white' -t=\"Random mandala\" \u003e out.html \u0026\u0026 open out.html\n```\n\nHere is an example that produces three random scribbles:\n\n```shell\njs-d3-graphics random-scribble 3 --margins=10 -h=200 -w=200 --color='blue' --background='white' \u003e out.html \u0026\u0026 open out.html\n```\n\n--------\n\n## TODO\n\nIn the lists below the highest priority items are placed first.\n\n### Plots\n\n#### Single dataset\n\n1. [X] DONE List plot\n2. [X] DONE List line plot\n3. [X] DONE Date list plot\n4. [X] DONE Box plot\n\n#### Multiple datasets\n\n1. [X] DONE List plot\n2. [X] DONE List line plot\n3. [X] DONE Date list plot \n4. [ ] TODO Box plot \n\n### Graph plots\n\n1. [ ] TODO Graph plot using d3-force\n    - [X] DONE Core graph plot\n    - [X] DONE Directed graphs\n    - [X] DONE Vertex label styling\n    - [X] DONE Edge label styling\n    - [X] DONE Highlight vertices and edges\n      - Multiple groups can be specified.\n    - [ ] TODO Vertex shape styling\n    - [ ] TODO Edge shape styling\n    - [ ] TODO Curved edges\n2. [ ] TODO Graph plot using vertex coordinates\n    - [X] DONE Core graph plot\n    - [X] DONE Directed graphs\n    - [X] DONE Vertex label styling\n    - [X] DONE Edge label styling\n    - [ ] TODO Vertex shape styling\n    - [ ] TODO Edge shape styling\n    - [ ] TODO Curved edges\n   \n### Charts\n\n#### Single dataset\n\n1. [X] DONE Bar chart\n   - [X] DONE Vertical   \n   - [X] DONE Horizontal   \n   - [X] DONE Chart label per bar   \n2. [X] DONE Histogram \n3. [X] DONE Bubble chart\n4. [ ] TODO Density 2D chart -- rectangular bins\n5. [ ] TODO Radar chart \n6. [ ] TODO Density 2D chart -- hexagonal bins\n7. [ ] TODO Pie chart\n8. [X] DONE Heatmap plot\n9. [X] DONE Chessboard position\n\n#### Multiple datasets\n\n1. [X] TODO Bar chart\n2. [ ] TODO Histogram\n3. [X] DONE Bubble chart\n4. [X] DONE Bubble chart with tooltips\n5. [ ] TODO Pie chart \n6. [ ] TODO Radar chart\n\n### Decorations\n\nUser specified or automatic:\n\n1. [X] DONE Plot label / title\n2. [X] DONE Axes labels\n3. [X] DONE Plot margins\n4. [X] DONE Plot legends (automatic for multi-datasets plots and chart)\n5. [X] DONE Plot grid lines \n     - [X] DONE Automatic \n     - [X] DONE User specified number of ticks\n6. [X] DONE Title style (font size, color, face)\n7. [X] DONE Axes labels style (font size, color, face)\n8. [ ] TODO Grid lines style\n\n### Infrastructural\n\n1. [X] DONE Support for different JavaScript wrapper styles\n  \n   - [X] DONE Jupyter cell execution ready\n   \n   - [X] DONE Standard HTML\n   \n   - Result output with JSON format?\n\n2. [ ] TODO Better, comprehensive type checking\n   \n   - Using the type system of \"Data::TypeSystem\".\n     \n3. [X] DONE CLI script\n\n4. [X] DONE JavaScript code snippets management\n\n   - Initially the JavaScript snippets were kept with the Raku code,\n     but it seems it is better to have them in a separate file.\n     (With the corresponding accessors.)\n   \n## Second wave\n\n1. [X] Random Mandala, single plot\n\n2. [X] Random mandalas row\n\n3. [ ] Random mandalas table/array\n   \n   - (I am not sure I will do this.)\n   \n4. [X] Random Scribble, single plot \n\n5. [X] Random Scribbles row \n\n--------\n\n## Implementation details\n\n### Splicing of JavaScript snippets\n\nThe package works by splicing of parametrized JavaScript code snippets and replacing the parameters\nwith concrete values.\n\nIn a sense, JavaScript macros are used to construct the final code through text manipulation.\n(Probably, unsound software-engineering-wise, but it works.)\n\n### History\n\nInitially  the commands of this package were executed in\n[Jupyter notebook with Raku kernel](https://raku.land/cpan:BDUGGAN/Jupyter::Kernel)\nproperly\n[hacked to redirect Raku code to JavaScript backend](https://github.com/bduggan/p6-jupyter-kernel/issues/100)\n\nBrian Duggan fairly quickly implemented the suggested Jupyter kernel magics, so, now no hacking is needed.\n\nAfter I finished version 0.1.3 of this package I decided to write a Python version of it, see [AAp3].\nWriting the Python version was a good brainstorming technique to produce reasonable refactoring (that is version 0.1.4).\n\n--------\n\n## References\n\n### Articles\n\n[OV1] Olivia Vane, \n[\"D3 JavaScript visualisation in a Python Jupyter notebook\"](https://livingwithmachines.ac.uk/d3-javascript-visualisation-in-a-python-jupyter-notebook), \n(2020), \n[livingwithmachines.ac.uk](https://livingwithmachines.ac.uk).\n\n[SF1] Stefaan Lippens, \n[Custom D3.js Visualization in a Jupyter Notebook](https://www.stefaanlippens.net/jupyter-custom-d3-visualization.html), \n(2018), \n[stefaanlippens.net](https://www.stefaanlippens.net).\n\n### Packages\n\n[AAp1] Anton Antonov,\n[Data::Reshapers Raku package](https://github.com/antononcube/Raku-Data-Reshapers),\n(2021-2024),\n[GitHub/antononcube](https://github.com/antononcube).\n\n[AAp2] Anton Antonov,\n[Text::Plot Raku package](https://github.com/antononcube/Raku-Text-Plot),\n(2022),\n[GitHub/antononcube](https://github.com/antononcube).\n\n[AAp3] Anton Antonov,\n[Data::TypeSystem Raku package](https://github.com/antononcube/Raku-Data-TypeSystem),\n(2023-2024),\n[GitHub/antononcube](https://github.com/antononcube).\n\n[AAp3] Anton Antonov,\n[JavaScriptD3 Python package](https://github.com/antononcube/Python-packages/tree/main/JavaScriptD3),\n(2022),\n[Python-packages at GitHub/antononcube](https://github.com/antononcube/Python-packages).\n\n[AAp4] Anton Antonov,\n[Jupyter::Chatbook Raku package](https://github.com/antononcube/Raku-Jupyter-Chatbook),\n(2023-2024),\n[GitHub/antononcube](https://github.com/antononcube).\n\n[BD1] Brian Duggan,\n[Jupyter::Kernel Raku package](https://raku.land/cpan:BDUGGAN/Jupyter::Kernel),\n(2017-2022),\n[GitHub/bduggan](https://github.com/bduggan/raku-jupyter-kernel).\n\n[MLp1] Moritz Lenz,\n[SVG::Plot Raku package](https://github.com/moritz/svg-plot)\n(2009-2018),\n[GitHub/moritz](https://github.com/moritz/svg-plot).\n\n### Videos\n\n[AAv1] Anton Antonov,\n[\"The Raku-ju hijack hack for D3.js\"](https://www.youtube.com/watch?v=YIhx3FBWayo),\n(2022),\n[YouTube/@AAA4Prediction](https://www.youtube.com/@AAA4prediction).\n\n[AAv2] Anton Antonov,\n[\"Random mandalas generation (with D3.js via Raku)\"](https://www.youtube.com/watch?v=THNnofZEAn4),\n(2022),\n[YouTube/@AAA4Prediction](https://www.youtube.com/@AAA4prediction).\n\n[AAv3] Anton Antonov,\n[\"Raku Literate Programming via command line pipelines\"](https://www.youtube.com/watch?v=2UjAdQaKof8),\n(2023),\n[YouTube/@AAA4Prediction](https://www.youtube.com/@AAA4prediction).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantononcube%2Fraku-javascript-d3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantononcube%2Fraku-javascript-d3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantononcube%2Fraku-javascript-d3/lists"}