Merge pull request #29 from pepijn-devries/work-in-progress

Fancier README

Author: pepijn-devries

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: ggsankeyfier
 Type: Package
 Title: Create Sankey and Alluvial Diagrams Using 'ggplot2'
-Version: 0.1.8.0013
+Version: 0.1.8.0014
 Authors@R: c(person("Pepijn", "de Vries", role = c("aut", "cre", "dtc"),
     email = "pepijn.devries@outlook.com",
     comment = c(ORCID = "0000-0002-7961-6646")),
@@ -37,6 +37,7 @@ Imports:
     tidyr,
     vwline
 Suggests:
+    gganimate,
     knitr,
     ragg,
     rmarkdown,

NEWS.md

@@ -1,4 +1,4 @@
-ggsankeyfier v0.1.8.0013
+ggsankeyfier v0.1.8.0014
 -------------
 
  * Added better stacking order features

README.Rmd

@@ -16,7 +16,8 @@ data("ecosystem_services")
 theme_set(theme_light())
 ```
 
-> `ggsankeyfier` Go with the data flow
+# ggsankeyfier <a href="https://pepijn-devries.github.io/ggsankeyfier/"><img src="man/figures/logo.svg" align="right" height="139" alt="ggsankeyfier website" /></a>
+> Go with the data flow
 
 ## Overview
 
@@ -29,8 +30,6 @@ theme_set(theme_light())
 [![codecov](https://codecov.io/gh/pepijn-devries/ggsankeyfier/graph/badge.svg?token=2AK9YA9UXR)](https://codecov.io/gh/pepijn-devries/ggsankeyfier)
 <!-- badges: end -->
 
-<img src="man/figures/logo.png" align="right" alt = "logo" />
-
 The `ggsankeyfier` packages allows you to visualise your data as Sankey or Alluvial diagrams.
 A Sankey diagram is essentially a stacked bar plot, where the bands connect bars across
 stages (on the x-axis), to show how quantities flow between them.
@@ -44,6 +43,21 @@ to add all sorts of other layers, such as text and labels.
 Furthermore, the data model used by the package allows you to visualise flows that skip stages
 or even feedback loops.
 
+And last but not least, in contrast to other packages, `ggsankeyfier` uses proportionate bands.
+In alluvial and Sankey diagrams data quantity flows are represented by
+bands that flow across stages. In order to effectively visualise quantities, the width of the
+band needs to be proportionate to the quantity. Other packages use a vertically oriented
+brush to plot the bands, making them narrow when the slope is steep. The `ggsankeyfier` package
+uses a brush that is perpendicular to the direction of the flow. This keeps the width along
+the band constant and proportionate with its representing quantity.
+
+This is illustrated in the animation below where both panels visualise the same quantity.
+As a reference a horizontal band representing the same quantity is shown. Note that the
+orientation of the brush affects its appearance.
+
+![Effectively visualising data flows requires a brush perpendicular to its path](https://raw.githubusercontent.com/pepijn-devries/ggsankeyfier/refs/heads/master/data-raw/brushangle.gif)
+
+
 ## Installation
 
 > Get CRAN version

README.md

@@ -1,5 +1,7 @@
 
-> `ggsankeyfier` Go with the data flow
+# ggsankeyfier <a href="https://pepijn-devries.github.io/ggsankeyfier/"><img src="man/figures/logo.svg" align="right" height="139" alt="ggsankeyfier website" /></a>
+
+> Go with the data flow
 
 ## Overview
 
@@ -15,8 +17,6 @@ badge](https://pepijn-devries.r-universe.dev/badges/ggsankeyfier)](https://pepij
 [![codecov](https://codecov.io/gh/pepijn-devries/ggsankeyfier/graph/badge.svg?token=2AK9YA9UXR)](https://codecov.io/gh/pepijn-devries/ggsankeyfier)
 <!-- badges: end -->
 
-<img src="man/figures/logo.png" align="right" alt = "logo" />
-
 The `ggsankeyfier` packages allows you to visualise your data as Sankey
 or Alluvial diagrams. A Sankey diagram is essentially a stacked bar
 plot, where the bands connect bars across stages (on the x-axis), to
@@ -32,6 +32,29 @@ and labels.
 Furthermore, the data model used by the package allows you to visualise
 flows that skip stages or even feedback loops.
 
+And last but not least, in contrast to other packages, `ggsankeyfier`
+uses proportionate bands. In alluvial and Sankey diagrams data quantity
+flows are represented by bands that flow across stages. In order to
+effectively visualise quantities, the width of the band needs to be
+proportionate to the quantity. Other packages use a vertically oriented
+brush to plot the bands, making them narrow when the slope is steep. The
+`ggsankeyfier` package uses a brush that is perpendicular to the
+direction of the flow. This keeps the width along the band constant and
+proportionate with its representing quantity.
+
+This is illustrated in the animation below where both panels visualise
+the same quantity. As a reference a horizontal band representing the
+same quantity is shown. Note that the orientation of the brush affects
+its appearance.
+
+<figure>
+<img
+src="https://raw.githubusercontent.com/pepijn-devries/ggsankeyfier/refs/heads/master/data-raw/brushangle.gif"
+alt="Effectively visualising data flows requires a brush perpendicular to its path" />
+<figcaption aria-hidden="true">Effectively visualising data flows
+requires a brush perpendicular to its path</figcaption>
+</figure>
+
 ## Installation
 
 > Get CRAN version