This package, as the name suggests, will become a "sort of" port of [[https://ggplot2.tidyverse.org/][ggplot2]] for Nim.
It is based on the [[https://github.com/vindaar/ginger/][ginger]] package.
If you're unfamiliar with the Grammar of Graphics to create plots, one of the best resources is probably Hadley Wickham's book on =ggplot2=, for which also an online version exists at: https://ggplot2-book.org/
In general this library tries (and will continue to do so) to stay mostly compliant with the =ggplot2= syntax. So searching for a solution in =ggplot2= should hopefully be applicable to this (unless the feature isn't implemented yet of course).
** Note on version =v0.4.0=
The dataframe implementation that was part of this library until version =v0.4.0= is now in its own repository under the name of =Datamancer=:
[[https://github.com/SciNim/Datamancer]]
This library imports and exports =Datamancer=, as such you don't need to change any code, even if you only imported =ggplotnim= to access the dataframe.
** Recipes
For a more nimish approach, check out the [[file:recipes.org][recipes]], which should give you examples for typical use cases and things I encountered and the solutions I found. Please feel free to add examples to this file to help other people!
Note that all recipes shown there are part of the test suite. So it's guaranteed that the plots shown there for a given version actually produce the shown result!
** Documentation
The documentation is found at:
https://vindaar.github.io/ggplotnim
** Installation & dependencies
Installation should be just a
nimble install ggplotnim
away. Maybe consider installing the =#head=, since new version probably won't be released after every change, due to rapid development still ongoing.
Since this library is written from scratch there is only a single external dependency, which is =cairo=.
*** Windows
Using =ggplotnim= on Windows is made slightly more problematic, because of the default =cairo= backend. Installing =cairo= on Windows is not as straightforward as on Linux or OSX.
There are multiple options, from most complicated to easiest:
Personally I would recommend the last option. Note however that the standalone DLL is called =cairo.dll=, but =ggplotnim= expects the name =libcairo-2.dll=. I would recommend to put the DLL in some sane place and adding that location to your Windows PATH variable:
Simple text only instructions on how to do that:
After saving those changes and restarting PowerShell / the command prompt everything should work.
** Currently working features
Geoms:
Facets:
Scales:
** Examples
Consider looking at the [[file:recipes.org][recipes]] in addition to the below to get a fuller picture!
The following is a short example from the recipe section that shows multiple features:
import ggplotnim
let df = toDf(readCsv("data/mpg.csv"))
let dfMax = df.mutate(f{"mpgMean" ~ (cty + hwy) / 2.0})
.arrange("mpgMean")
.tail(1)
ggplot(df, aes("hwy", "displ")) +
geom_point(aes(color = "cty")) + # set point specific color mapping
geom_text(data = dfMax, aes = aes(y = f{c"displ" - 0.2}, text = "model")) +
geom_text(data = dfMax, aes = aes(y = f{c"displ" + 0.2}, text = "mpgMean")) + theme_opaque() + ggsave("media/recipes/rAnnotateMaxValues.png")
[[./media/recipes/rAnnotateMaxValues.png]]
* Experimental* Vega-Lite backend
From the beginning one of my goals for this library was to provide not only a Cairo backend, but also to support [[https://vega.github.io/vega-lite/][Vega-Lite]] (or possibly Vega) as a backend. To share plots and data online (and possibly add support for interactive features) is much easier in such a way.
An experimental version is implemented in [[https://github.com/Vindaar/ggplotnim/blob/master/src/ggplotnim/ggplot_vega.nim][ggplot_vega.nim]], which provides most functionality of the native backend, with the exception of support for facetted plots.
See the [[https://github.com/Vindaar/ggplotnim/blob/master/recipes.org#simple-vega-lite-example][full example in the recipe here]].
Creating a vega plot is done by also importing the =ggplot_vega= submodule and then just replacing a =ggsave= call by a =ggvega= call:
import ggplotnim
import ggplotnim/ggplot_vega
let mpg = toDf(readCsv("data/mpg.csv"))
ggplot(mpg, aes(x = "displ", y = "cty", color = "class")) +
geom_point() +
ggtitle("ggplotnim in Vega-Lite!") +
ggvega("media/recipes/rSimpleVegaLite.html") # w/o arg creates a /tmp/vega_lite_plot.html
This recipe gives us the following plot:
[[media/recipes/rSimpleVegaLite.png]]
To view it as an interactive plot in the Vega viewer, [[https://vega.github.io/editor/?#/gist/0bef3ed0cf7c6d26da927732f1c81582/rSimpleVegaLite.json][click here]].