Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Theming improvements, other fixes #176

Merged
merged 74 commits into from
Feb 11, 2024
Merged

Theming improvements, other fixes #176

merged 74 commits into from
Feb 11, 2024

Conversation

Vindaar
Copy link
Owner

@Vindaar Vindaar commented Jan 31, 2024

This turned into a massive PR, as it grew during writing of my thesis where I didn't have the time and motivation to properly finish individual things as a PR.

The majority of improvements are related to theming a plot. Essentially every aspect of a plot is now adjustable via the Theme object. In addition the theme can now also be changed at runtime based on a TOML file that describes the theme.

For example:

[Theme]
titleFont = "font(24.0)"
labelFont = "font(24.0)"
tickLabelFont = "font(18.0)"
tickLength = 10.0
tickWidth = 2.0
gridLineWidth = 2.0
legendFont = "font(18.0)"
legendTitleFont = "font(24.0, bold = true)"
facetHeaderFont = "font(24.0, alignKind = taCenter)"
baseLabelMargin = 0.5
annotationFont = "font(9.0, family = \"monospace\")"
continuousLegendHeight = 2.2
continuousLegendWidth = 0.6
plotMarginRight = 5.5
plotMarginLeft = 3.0
plotMarginTop = 1.0
plotMarginBottom = 2.5
canvasColor = "#7fa7ce"
baseScale = 1.5

This as a TOML file needs to be handed to the tomlTheme proc. It will apply all the theme fields to the plots.

Another very useful feature is WritePlotCsv. An optional compile time + runtime switch feature. If you ever wanted to easily share data for a plot, this is for you. By compiling with -d:WritePlotCsv you compile in a runtime check for a WRITE_PLOT_CSV=true environment variable value. If that value is set, ggplotnim will write CSV files for every data frame given to a ggplot call. One CSV file for each data frame to a call (meaning each geom with a custom DF as well) will be written with the same filename as the plot, but a .csv suffix. For additional geoms an additional geom suffix is added. It makes sharing data together with plots much easier. In the future I'll likely add some options to adjust the paths for the generated files and possibly allow merging of data files into binary (https://github.com/c-blake/nio) or HDF5 formats for cases of plots with massive input DFs.

Full changelog:

* v0.7.0
This release is a rather big one. The majority of features added
relates to customization of plots.
~Theme~ related improvements:
- ~baseLabelMargin~ field to adjust the default range between tick
  labels and labels in cm.
- allow adjustment of plot size via ~Theme~
- adjustment of annotation font via ~Theme~
- scale grid lines via ~Theme~
- add ~themeLatex~, a very useful helper when producing PDF plots via
  TikZ where the actual target is a TeX file. Its argument ~fWidth~
  combined with ~width~ (in pixel), ~textWidth~ (in pt of the actual
  ~\textwidth~ of the LaTeX document to be inserted) it allows to
  exactly specify font sizes of plots such that they match a given
  size in the resulting PDF. E.g. a plot to be inserted at
  ~0.9\textwidth~ using ~fWidth = 0.9~, a plot size of e.g. ~width =
  600~ pixel (for the standalone plot) and a ~textWidth~ of ~450 pt~
  (LaTeX pt) produces a resulting PDF after inserting the plot at the
  ~0.9\textwidth~ that matches exactly the font sizes given by
  ~ggplotnim~. The ~baseTheme~ is an argument of a procedure that
  returns the desired ~Theme~ to be used as a base.
  - ~singlePlot~ and ~sideBySide~ are two ~baseTheme~ procedures that
    produce nice looking graphs when inserting as a single or 2
    side-by-side setup in a TeX file.
- add ~coord_fixed~ option that creates the actual data portion of the
  plot in fixed ratio. E.g. an argument of ~1.0~ creates a plot of
  user given ~width~ where the height is computed precisely such that
  the data portion is of ratio 1:1. Useful for physical coordinates in
  a plot to correspond to the desired ratio.
- allow setting ~useTeX~ argument via ~Theme~ (to enable/disable TikZ
  backend)
- allow hiding x or y labels individually
- adjust styling of ridgeline plots
- add ~cool~ colormap
- fields ~discrete/continuousLegendWidth/Height~ fields to ~Theme~ to
  adjust the size of continuous / discrete legends
- add helper to add two ~Themes~ via ~+~
- respect user set margins in facet plots
- add ~tomlTheme~ to set a theme at runtime from a TOML file. Example
  given in PR description (PR #176)

- add ~dataAsBitmap~ feature for Cairo, TikZ backend. In a vector
  graphic target will draw all the actual data as a PNG, similar to in
  a raster plot. This makes plots with large amounts of data as a
  vector graphic feasible.
- make ~aes~ arguments to initial ~ggplot~ call optional. This of
  course implies arguments to ~geom_*~ calls are mandatory. There is a
  chance this is a breaking change in some contexts and decreases
  CT safety to some extent. But it can be very useful when combining
  different geoms that don't share column names as well as using
  different aesthetics.  
- add experimental (CT + RT) option ~WritePlotCsv~. If compiled with
  ~-d:WritePlotCsv~ and then a ~WRITE_PLOT_CSV=true~ environment
  variable set, ~ggplotnim~ will write CSV files for every plot
  produced. The filename is the filename of the plot with ~.csv~
  suffix. For each geom that has a separate dataframe an extra CSV
  file is produced. This allows for easy sharing of data that is used
  to produce a plot.
- add ~TEXT_PRECISION~ environment variable check for ~geom_text~ to
  adjust the precision used for floating point numbers.  
- allow assignment of facets in user given order by ~order~ argument
  to ~facet_wrap~
- add option ~gradient~ opposite to ~factor~ to force an aesthetic argument to
  be continuous
- adjust data scale in ~scale_fill/color_continuous/gradient~ procs
- allow annotations to be placed at ~top/right~ positions in addition
  to ~left/bottom~
- fixes to raster plots with other geoms resulting in bad data ranges
- better support for histograms with minimal values != 0
- use ~expandTilde~ in ~ggsave~
- improve logic detecting discreteness of arguments  
- better exception message when color parsing fails
- refactoring of facet logic
- fixes to legend heights in some setups
- better date logic for non facet plots  

Using the real height of each line causes alignment issues for
multiline text. Just use a placeholder height for multiline based on
`My` to have a tall letter and one going below baseline.
If compiled with `-d:WritePlotCsv` has the option to automatically
write out CSV files for input DF for each plot that is created (if
enabled via environment variable)
Before we used the entire scale of the viewport, which is wrong if
multiple geoms are used, some of which go beyond the raster image!
This can happen if the y limit is changed by hand or the user uses a
log10 plot with ~stat = "identity"~
The idea is: If any of the axes is *continuous* then all others should
be continuous too. This is important if adding a single geom that only
has 1 element (and such is `colConstant` -> "discrete") to get the
desired plot
Most processing is now done in `postprocess_scales` where it fits
better. Makes the `scale_x/y_date` logic work in facet plots by using
the relevant data and not the input `p.data` DF.
These have been made redundant. At some point in the future we may
wish to enable such a thing again, but that requires a bit of thought
where such an exception would then be thrown
(because we call ~ggcreate~ without calling save / handing a filename)
Recent version differences between my Void Cairo and standard ubuntu
seem to move the text a minute amount more than in the past? Something
is up, but debugging it is tricky. I verified the plots look fine by
eye on Ubuntu and there is only a very small difference between
expected and produced. These thresholds should be fine.
@Vindaar Vindaar merged commit 3b7ec3c into master Feb 11, 2024
18 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant