{"id":32207443,"url":"https://github.com/pepijn-devries/ggsankeyfier","last_synced_at":"2025-10-22T05:53:23.755Z","repository":{"id":225101941,"uuid":"661137303","full_name":"pepijn-devries/ggsankeyfier","owner":"pepijn-devries","description":"Add alluvial / sankey diagram layers to a ggplot","archived":false,"fork":false,"pushed_at":"2025-09-05T20:35:58.000Z","size":16858,"stargazers_count":18,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-22T05:53:08.675Z","etag":null,"topics":["ggplot2","visualisation"],"latest_commit_sha":null,"homepage":"https://pepijn-devries.github.io/ggsankeyfier/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pepijn-devries.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2023-07-01T22:53:29.000Z","updated_at":"2025-09-05T20:30:35.000Z","dependencies_parsed_at":"2024-02-29T09:24:34.841Z","dependency_job_id":"a05a4b1a-f529-468d-9ae4-ed56d375d6a8","html_url":"https://github.com/pepijn-devries/ggsankeyfier","commit_stats":null,"previous_names":["pepijn-devries/ggsankeyfier"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pepijn-devries/ggsankeyfier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepijn-devries%2Fggsankeyfier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepijn-devries%2Fggsankeyfier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepijn-devries%2Fggsankeyfier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepijn-devries%2Fggsankeyfier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pepijn-devries","download_url":"https://codeload.github.com/pepijn-devries/ggsankeyfier/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pepijn-devries%2Fggsankeyfier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280389299,"owners_count":26322507,"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","status":"online","status_checked_at":"2025-10-22T02:00:06.515Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ggplot2","visualisation"],"created_at":"2025-10-22T05:53:17.993Z","updated_at":"2025-10-22T05:53:23.749Z","avatar_url":"https://github.com/pepijn-devries.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n```{r echo = FALSE, message = FALSE, warning = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  fig.ext = \"svg\",\n  dev = \"svg\"\n)\nlibrary(ggplot2)\nlibrary(ggsankeyfier)\ndata(\"ecosystem_services\")\ntheme_set(theme_light())\n```\n\n\u003e `ggsankeyfier` Go with the data flow\n\n## Overview\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/pepijn-devries/ggsankeyfier/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/pepijn-devries/ggsankeyfier/actions/workflows/R-CMD-check.yaml)\n![cranlogs](https://cranlogs.r-pkg.org/badges/ggsankeyfier)\n[![version](https://www.r-pkg.org/badges/version/ggsankeyfier)](https://CRAN.R-project.org/package=ggsankeyfier)\n[![cran checks](https://badges.cranchecks.info/worst/ggsankeyfier.svg)](https://cran.r-project.org/web/checks/check_results_ggsankeyfier.html)\n[![ggsankeyfier status badge](https://pepijn-devries.r-universe.dev/badges/ggsankeyfier)](https://pepijn-devries.r-universe.dev/ggsankeyfier)\n[![codecov](https://codecov.io/gh/pepijn-devries/ggsankeyfier/graph/badge.svg?token=2AK9YA9UXR)](https://codecov.io/gh/pepijn-devries/ggsankeyfier)\n\u003c!-- badges: end --\u003e\n\n\u003cimg src=\"man/figures/logo.png\" align=\"right\" alt = \"logo\" /\u003e\n\nThe `ggsankeyfier` packages allows you to visualise your data as Sankey or Alluvial diagrams.\nA Sankey diagram is essentially a stacked bar plot, where the bands connect bars across\nstages (on the x-axis), to show how quantities flow between them.\n\n## Why use `ggsankeyfier`?\n\n`ggsankeyfier` allows you to add Sankey diagram layers to a `ggplot2::ggplot()`. The\npackage also provides `stat_*` and `position_*` functions that allow you\nto add all sorts of other layers, such as text and labels.\n\nFurthermore, the data model used by the package allows you to visualise flows that skip stages\nor even feedback loops.\n\n## Installation\n\n\u003e Get CRAN version\n```{r eval=FALSE}\ninstall.packages(\"ggsankeyfier\")\n```\n\n\u003e Get development version on github\n```{r eval=FALSE}\ndevtools::install_github('pepijn-devries/ggsankeyfier')\n```\n\n## Important concepts\n\nAs there is some variation in the definition and terminology used in Sankey diagrams,\nthere are some introduced here for consistency across the package documentation.\nHere we try to adhere to common definitions used in the\n[graph theory](https://en.wikipedia.org/wiki/Graph_theory). This theory is used to\nmodel pairwise relationships between 'nodes' which are connected by 'edges'. These\naspects are circled in the illustration below.\n\n![Important aspects](man/figures/important_aspects.svg)\n\nThe `ggsankeyfier` package can only visualise structured graphs. Meaning that each node\nbelongs to a specific stage (arranged along the x-axis).\n\n### Sankey thesaurus\n\nAs there are no standards in Sankey diagrams, there may be different words representing the\nsame or similar aspects. Therefore the following thesaurus is presented to provide an overview\nand hopefully avoid confusion. The list starts with the term preferred in the present package,\nfollowed by alternatives.\n\n  * Sankey diagram:\n    * *Alluvial diagram*. Although arguably not the same as a Sankey diagram,\n      they are very similar. Differences ly in the type of data (population of facts across\n      categorical dimensions (alluvial) versus quantities in different states (Sankey))\n      Also, alluvial diagrams are always structured in stages (where the order does not matter),\n      whereas Sankey diagrams are not necessarily structured, but the order does matter\n      \u003c!-- See also  http://www.datasmith.org/2020/05/02/alluvial-plots-vs-sankey-diagrams and\n      https://datavizcatalogue.com/blog/sankey-diagrams-parallel-sets-alluvial-diagrams-whats-the-difference/ --\u003e\n    * *Bump diagram*. This is actually a special case of alluvial diagrams, where each node flows\n      only to a single next node. Usually, the stacking order of nodes in each stage is determined\n      by the size of the nodes\n  * Node:\n    * *Vertices*. Another commonly used term in the [graph theory](https://en.wikipedia.org/wiki/Graph_theory)\n    * *Stratum*. A term coined for alluvial diagrams\n  * Edge:\n    * *Flow*. Sometimes also refers to the interaction between stages. In the present package it is used\n      only as a synonym for 'edge'.\n    * *Alluvium*. A term used in alluvial diagrams\n    * *Line*. Another commonly used albeit generic term in the [graph theory](https://en.wikipedia.org/wiki/Graph_theory)\n    * *Link*. Although commonly used in the [graph theory](https://en.wikipedia.org/wiki/Graph_theory),\n    we avoid its use in this context as it may get confused\n    with a link in a cause-effect chain, which is better reflected\n    by the stages\n  * Connector:\n    * *Lode*. A term used in alluvial diagrams\n  * Stage:\n    * *Link*. Not used in the present package to avoid confusion with edges (see above)\n    \n## Usage\n\nLike any other ggplot, you start by calling `ggplot2::ggplot2()`, provide the data for\nplotting and specify aesthetics (`aes`). Layers with Sankey edges and nodes are simply added\nto the plot using the `+`-operator:\n\n```{r general_illustration, fig.width=5, fig.height=2, eval=TRUE}\ndata(\"ecosystem_services\")\n\nggplot(ecosystem_services_pivot1,\n       aes(x = stage, y = RCSES, group = node,\n           connector = connector, edge_id = edge_id)) +\n  geom_sankeyedge(v_space = \"auto\") +\n  geom_sankeynode(v_space = \"auto\")\n```\n\nFor consistency with aesthetics used in other `ggplot2::ggplot()` layers, the stage variable\nshould be assigned to `x`, the quantity of the nodes and edges to `y` and the node identifier\nto `group`. In addition to these 'standard' aesthetics, you also need to specify a\n`connector` specifying the direction of an edge (one of `'from'` or `'to'`); and an\n`edge_id` which is used to determine which connector ends should be paired together.\n\n### Data management\n\nNote that the plotting routines require data organised in a `data.frame`, with in each\nrow a 'connector'. A connector is either the start or an end of an edge. This allows\nyou to provide different characteristics for each of these ends. However, in most\ncases this is not the type of data you will be working with. Check\n`vignette(\"data_management\")`, on how to rearrange your data for displaying it in a\nSankey diagram.\n\n### Positioning nodes and edges\n\nThe package gives you much control on the positioning of elements in the diagram. Think of:\n\n  * spacing between and sizing of nodes and edges\n  * aligning nodes vertically\n  * introducing a horizontal split in nodes\n  * stacking order of nodes and edges\n\n`vignette(\"positioning\")` will show you how.\n\n### Decorating nodes and edges\n\nWhen creating your own Sankey diagrams you may want to alter its\nappearance. You may want to:\n\n  * assign meaningful decorations (such as colours) using aesthetics\n    to nodes and edges\n  * add keys and legends to guide your audience\n  * add additional layers (such as text)\n  * change the edge curve shape\n  * use different themes\n\nCheck `vignette(\"decorating\")` to discover how this is done.\n\n## Code of Conduct\n\nPlease note that the `ggsankeyfier` project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.\n\n## Acknowledgements\n\nThis package was development as part of the EU GES4SEAS project\n(EU call HORIZON-CL6-2021-BIODIV-01-04, grant agreement\n[101059877](https://doi.org/10.3030/101059877)) and the\nWUR Knowledge Base Research program KB-36-003-022 “The use of ecosystem services\nto conserve biodiversity in the North Sea” that is supported by finance from the\nDutch Ministry of Agriculture, Nature and Food Quality \n\n## Resources\n\n * Piet GJ, Jongbloed RH, Bentley JW, Grundlehner A, Tamis JE, De Vries P (_in prep._)\n A Cumulative Impact Assessment on the North Sea Capacity to Supply Ecosystem Services\n [DOI:10.2139/ssrn.4760674](http://dx.doi.org/10.2139/ssrn.4760674)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpepijn-devries%2Fggsankeyfier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpepijn-devries%2Fggsankeyfier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpepijn-devries%2Fggsankeyfier/lists"}