{"id":23584419,"url":"https://github.com/rawlins/svgling","last_synced_at":"2025-03-17T16:10:43.545Z","repository":{"id":57472565,"uuid":"156463713","full_name":"rawlins/svgling","owner":"rawlins","description":"linguistics tree drawing to SVG in python, aimed at Jupyter","archived":false,"fork":false,"pushed_at":"2024-08-20T14:15:53.000Z","size":853,"stargazers_count":62,"open_issues_count":3,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-02T13:11:18.109Z","etag":null,"topics":["jupyter","linguistics","nltk","python","svg","tree","tree-diagram","tree-drawing","visualization"],"latest_commit_sha":null,"homepage":"https://rawlins.github.io/svgling/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rawlins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2018-11-06T23:45:37.000Z","updated_at":"2024-12-30T22:23:53.000Z","dependencies_parsed_at":"2024-02-25T16:31:16.259Z","dependency_job_id":"09a1c1fe-7317-41ae-a3d8-754962a9c96c","html_url":"https://github.com/rawlins/svgling","commit_stats":{"total_commits":93,"total_committers":1,"mean_commits":93.0,"dds":0.0,"last_synced_commit":"fb254634287fa5a73687a49217eafb718b3cd285"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawlins%2Fsvgling","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawlins%2Fsvgling/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawlins%2Fsvgling/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rawlins%2Fsvgling/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rawlins","download_url":"https://codeload.github.com/rawlins/svgling/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244066180,"owners_count":20392406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["jupyter","linguistics","nltk","python","svg","tree","tree-diagram","tree-drawing","visualization"],"created_at":"2024-12-27T02:27:09.467Z","updated_at":"2025-03-17T16:10:43.511Z","avatar_url":"https://github.com/rawlins.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `svgling`: Linguistic tree diagrams in python + svg\n\n**Author**: Kyle Rawlins, [kgr@jhu.edu](kgr@jhu.edu)\n\n**Website and documentation**: [https://rawlins.github.io/svgling/](https://rawlins.github.io/svgling/)\n\n**Dependencies**: [`svgwrite`](https://pypi.org/project/svgwrite/), python 3, (optional) [cairosvg](https://cairosvg.org/)\n\n**Repository**: [https://github.com/rawlins/svgling/](https://github.com/rawlins/svgling/)\n\n**Installation**: `pip install svgling` for the current release version, install from the repository for the current unreleased version. (E.g., `pip install git+https://github.com/rawlins/svgling`)\n\n**License**: MIT License\n\n## Overview\n\nThe `svgling` package is a pure python package for doing single-pass rendering\nof tree diagrams as used in Linguistics and NLP, in the [SVG (Scalable Vector\nGraphics)](https://www.w3.org/Graphics/SVG/) format. It is primarily intended\nfor integrating with Jupyter notebooks, but can also be used to generate SVG\ndiagrams for all sorts of other purposes. It involves no javascript and so\nwill work in Jupyter without any plugins.\n\nThe basic interface is pretty simple: pass a tree-describing object to\n`svgling.draw_tree` (e.g. a tuple consisting of a label and a sequence of\ndaughter nodes, which may themselves be trees).\n\n    import svgling\n    svgling.draw_tree((\"S\", (\"NP\", (\"D\", \"the\"), (\"N\", \"elephant\")), (\"VP\", (\"V\", \"saw\"), (\"NP\", (\"D\", \"the\"), (\"N\", \"rhinoceros\")))))\n\nIn Jupyter, this code produces an SVG image like the following:\n\n![example sentence](https://raw.githubusercontent.com/rawlins/svgling/master/demotree.svg?sanitize=true)\n\nThe tree drawing code accepts two main tree formats: lisp-style trees made from\nlists of lists (or tuples of tuples), with node labels as strings, or trees from\nthe [`nltk`](https://www.nltk.org/) package, i.e. objects instantiating the\n[`nltk.tree.Tree`](https://www.nltk.org/_modules/nltk/tree.html) API. The\nfollowing nltk code run in Jupyter, as long as `svgling` has been installed,\nproduces an identical tree diagram to the above example:\n\n    nltk.Tree.fromstring(\"(S (NP (D the) (N elephant)) (VP (V saw) (NP (D the) (N rhinoceros))))\")\n\nOn current versions of `nltk`, the support goes both ways: the default (and\nonly) tree renderer in Jupyter is `svgling`. If the package is installed, nltk\n`Tree`s will automatically render using svgling trees. For more control, you can\nalso provide a tree directly to the `svgling.draw_tree` function, which allows\nyou to use options:\n\n    x = nltk.Tree.fromstring(\"(S (NP (D the) (N elephant)) (VP (V saw) (NP (D the) (N rhinoceros))))\")\n    svgling.draw_tree(x, leaf_nodes_align=True)\n\nBeyond basic tree-drawing, the package supports a number of flourishes like\nmovement arrows. For documentation and examples, see the project website:\n\n* [Overview of the package](https://rawlins.github.io/svgling/)\n* [`svgling` diagram gallery](https://rawlins.github.io/svgling/gallery.html)\n* [Full manual for `svgling`](https://rawlins.github.io/svgling/manual.html)\n\nThese three pages are directly rendered from notebooks in the [docs/]\n(https://github.com/rawlins/svgling/tree/master/docs) directory that you can\nalso download and execute in Jupyter Lab (or another frontend, modulo some\ncompatibility notes).\n\n## Core design principles and goals\n\n1. Be well suited for *programmatic* generation of tree diagrams (not just\nhand-customized diagrams).\n2. Be equally suited for theoretical linguistics and computational\nlinguistics/NLP, at least for cases where the latter is targeting constituent\ntrees. (This package is not aimed at dependency trees/graphs.)\n3. Do as much as possible with pure python (as opposed to python+javascript, or\npython+tk, or python+dot, or...).\n\n## Strengths and limitations\n\nThe `svgling` package does its rendering in one pass -- it takes a tree\nstructure as input, produces an svg output, and that's it. Because of this,\nit is extremely simple to use in Jupyter, and no messing with plugins or\nJupyter settings should be necessary. Because it is SVG-based, scaling and\nembedding in any web context should work smoothly. It also has minimal\ndependencies, just one package\n([`svgwrite`](https://github.com/mozman/svgwrite)) that provides an abstraction\nlayer over the process of generating valid SVG text.\n\nSingle-pass rendering also places limitations on what can be done. One of the\nchallenges is that it mostly uses absolute position, and the exact position\nand width of text elements can't be determined without actually rendering to\nsome device and seeing what happens. In addition, the exact details of\nrendering are in various ways at the mercy of the rendering device. This all\nmeans that `svgling` uses a bunch of tricks to estimate node size and width,\nand won't always be perfect on all devices. This situation also places some\nhard limitations on how far `svgling` can be extended without adding\njavascript or other multi-pass rendering techniques. For example, I would\neventually like to allow mathjax in nodes, but at the moment this does not\nseem possible in pure SVG without javascript on the client side. The package\ndoes provide support for hybrid HTML/SVG tree diagrams that allows MathJax in\nnodes, but this rendering mode comes with certain limitations.\n\nThere are many things that it might be nice to add to this package; if you find\n`svgling` useful, have any requests, or find any bugs, please let me know.\n\n## Compatibility\n\nThe SVG files produced by `svgling` should be compatible with all major browsers\n(Chrome, Firefox, Safari, Edge) on both desktop and mobile; if you find a\ncompatibility issue with some browser, please [report it as a\nbug](https://github.com/rawlins/svgling/issues). It also supports all major\ninteractive editing packages that I am aware of.\n\nThere are various ways to convert the generated SVG files to other formats,\nincluding raster ones, but the recommended/supported way to do this\nprogrammatically is via the [`cairosvg`](https://cairosvg.org/) package.\n`svgling.utils` provides some convenience functions for conversion to\nPNG/PDF/PS using cairosvg. See the \"Compatibility and Conversion\" section of\nthe svgling manual for more details. Note that `cairosvg` is an optional\ndependency of `svgling`, so won't necessarily be installed by default.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawlins%2Fsvgling","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frawlins%2Fsvgling","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frawlins%2Fsvgling/lists"}