diff --git a/DESCRIPTION b/DESCRIPTION index 4dfdf34..3075f12 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: ggpp Type: Package Title: Grammar Extensions to 'ggplot2' -Version: 0.5.6.9001 -Date: 2024-04-27 +Version: 0.5.6.9002 +Date: 2024-05-03 Authors@R: c( person("Pedro J.", "Aphalo", email = "pedro.aphalo@helsinki.fi", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-3385-972X")), diff --git a/NEWS.md b/NEWS.md index 807e6dc..30998c5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,11 +6,11 @@ editor_options: wrap: 72 --- -# ggpp 0.5.7/0.6.0 +# ggpp 0.5.7 -Track changes in 'ggplot2' 3.5.0. Fix a couple of minor incompatibilities. -Add some new features matching those new in 'ggplot2'. General improvements -and bug fixes. +Track changes in 'ggplot2' 3.5.0 and 3,5,1. Fix a couple of minor +incompatibilities. Add some new features matching those new in 'ggplot2'. +General improvements and bug fixes. - This version depends on 'ggplot2' >= 3.5.0. - Add helper function `wrap_labels()`, useful to insert new lines into @@ -28,7 +28,7 @@ to its most frequently used direction, even if opposite to the default for `geom_text_s()` and `geom_label_s()`. - Update `geom_text_s()`, `geom_label_s()`. `geom_text_pairwise()` and `geom_label_pairwise()` adding parameter `size.unit` tracking change in -`geom_text()` and `geom_label()` in 'ggplot2' 3.5.0. +`geom_text()` and `geom_label()` in 'ggplot2' >= 3.5.0. - Update `geom_text_s()`, `geom_label_s()`. `geom_text_pairwise()` and `geom_label_pairwise()` so that graphic elements in the keys match those in the plot, even when using the additional features available in 'ggplot2' in @@ -38,7 +38,7 @@ the plot, even when using the additional features available in 'ggplot2' in color defintions. - Fix in `geom_text_s()`, `geom_label_s()`. `geom_text_pairwise()` and `geom_label_pairwise()` an infrequent problem with incomplete guides in -'ggplot2' 3.5.0. +'ggplot2' >= 3.5.0. - Fix bug in `geom_point_s()`, `alpha_target = "point"` ignored. - Fix bug in `geom_label_s()`, `colour_target = "box.line"` ignored. diff --git a/README.Rmd b/README.Rmd index 14bb1db..2796a40 100644 --- a/README.Rmd +++ b/README.Rmd @@ -27,19 +27,18 @@ version](https://www.r-pkg.org/badges/version/ggpp)](https://cran.r-project.org/ ## Purpose -Package '**ggpp**' provides a set of building blocks that extend the -Grammar of Graphics implemented in package 'ggplot2' (\>= 3.5.0). The -extensions enhance the support of data labels and annotations in plots. -Position functions implement -new approaches to nudging usable with any geometry, but especially -useful together with `geom_text_s()` and `geom_label_s()` from this -package and `geom_text_repel()` and `geom_label_repel()` from package -'ggrepel' (\>= 0.9.2). See: () for -installation instructions and news about releases. +Package '**ggpp**' provides a set of building blocks that extend the Grammar of +Graphics implemented in package 'ggplot2' (\>= 3.5.0). The extensions enhance +the support of data labels and annotations in plots. Position functions +implement new approaches to nudging usable with any geometry, but especially +useful together with `geom_text_s()` and `geom_label_s()` from this package and +`geom_text_repel()` and `geom_label_repel()` from package 'ggrepel' (\>= 0.9.2). +See: () for installation instructions and news +about releases. ## NPC support in ggplot2 -**`npc` coordinates are supported natively by 'ggplot2' starting from version 3.5.0 by means of the identity function `I()`. However, this works only when continuous variables are mapped to the _x_ and/or _y_ aesthetics. This new approach should work with almost every normal geom. If support for factors and other discrete variables is added in the future to 'ggplot2', all the `_npc` geometries from 'ggpp' could become redundant. Meanwhile, the layer functions from 'ggpp' still fill a gap, albeit a smaller one, in the support of NPC by 'ggplot2'.** +**Normalised Parent Coordinates (NPC) are supported natively by 'ggplot2' >= 3.5.0 by means of R's identity function `I()`. This new approach does not require special geometries as it should work with almost every existing geometry. However, currently this works only when continuous variables are mapped to the _x_ and/or _y_ aesthetics. If this mechanism is extended to support factors and other discrete variables in the future , all the `_npc` geometries from 'ggpp' could become redundant. Meanwhile, these special geometries from 'ggpp' still fill a gap, albeit a smaller one, in the support of NPC by 'ggplot2'.** ## Extended Grammar of graphics @@ -47,18 +46,19 @@ installation instructions and news about releases. The distinction between observations or data mapped to *x* and *y* aesthetics and data labels is that data labels are linked to a the -coordinates of the data, but own location is usually nearby but not +coordinates of the data, but their own location is usually nearby but not exactly that of the data. In other words the location of a data label in *x* and *y* coordinates is flexible as long as the link to a data observation can be inferred. In the case of annotations the location on the plotting area is arbitrary, dictated by available graphic design considerations and the requirement of not occluding data observations. -In the table below we list the geometries defined in package 'ggpp', -whether they are intended to for data labels, annotations or data, the -aesthetics and pseudo-aesthetic they obey and whether the can connect -the original data position to the displaced position where the data -label is anchored. These requires also a change in the behaviour of -position functions, that we will describe in the next section. +In the table below we list for the geometries defined in package 'ggpp': +1) whether they are intended for data labels, annotations or data, 2) the +aesthetics and pseudo-aesthetics they obey, and 3) whether they can connect +the original data position to the displaced position. The drawing of +connecting segments or arrows between the displaced and original positions, +those of the observation and the displaced label, requires also a change in +the data returned by position functions (see the next section). | Geometry | Main use | Aesthetics | Segment | |-------------|-------------|---------------------------------|-------------| @@ -67,13 +67,13 @@ position functions, that we will describe in the next section. | `geom_text_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | horiz. | | `geom_label_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, fill, alpha, linewidth, linetype, group, vjust, hjust | horiz. | | `geom_point_s()` | data labels | x, y, size, colour, fill, alpha, shape, stroke, group | yes | -| `geom_table()` | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | -| `geom_plot()` , `geom_grob()` | data labels | x, y, label, group, angle, vjust, hjust | yes | +| `geom_table()`1 | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | +| `geom_plot()`1, `geom_grob()`1 | data labels | x, y, label, group, angle, vjust, hjust | yes | | `geom_margin_arrow()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | | `geom_margin_point()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | | `geom_margin_grob()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | | `geom_quadrant_lines()` , `geom_vhlines()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | | -: Geometries defined in package 'ggpp' +: Geometries defined in package 'ggpp'. 1 NPC versions exist for these geometries, as well as for `geom_text()` and `geom_label()`, used mainly for plot annotations. ## Position functions @@ -101,7 +101,7 @@ the the observations. Position functions `position_stacknudge()`, `position_fillnudge()`, `position_jitternudge()`, `position_dodgenudge()` and -`position_dodge2nudge()` each combines the roles of two *position* +`position_dodge2nudge()` combine each the roles of two *position* functions. They make it possible to easily nudge labels in plot layers that use stacking, dodging or jitter. Functions `position_jitter_keep()`, `position_stack_keep()`, @@ -127,7 +127,7 @@ keep in the `data` object the original coordinates. | `position_dodgenudge()` | dodge + nudge | combined, see above | data labels in column plots | | `position_dodge2nudge()` | dodge2 + nudge | combined, see above | data labels in box plots | -: Position functions defined in package 'ggpp' +: Position functions defined in package 'ggpp'. ### Statistics diff --git a/README.md b/README.md index baee27f..3ff7111 100644 --- a/README.md +++ b/README.md @@ -28,14 +28,15 @@ about releases. ## NPC support in ggplot2 -**`npc` coordinates are supported natively by ‘ggplot2’ starting from -version 3.5.0 by means of the identity function `I()`. However, this -works only when continuous variables are mapped to the *x* and/or *y* -aesthetics. This new approach should work with almost every normal geom. -If support for factors and other discrete variables is added in the -future to ‘ggplot2’, all the `_npc` geometries from ‘ggpp’ could become -redundant. Meanwhile, the layer functions from ‘ggpp’ still fill a gap, -albeit a smaller one, in the support of NPC by ‘ggplot2’.** +**Normalised Parent Coordinates (NPC) are supported natively by +‘ggplot2’ \>= 3.5.0 by means of R’s identity function `I()`. This new +approach does not require special geometries as it should work with +almost every existing geometry. However, currently this works only when +continuous variables are mapped to the *x* and/or *y* aesthetics. If +this mechanism is extended to support factors and other discrete +variables in the future , all the `_npc` geometries from ‘ggpp’ could +become redundant. Meanwhile, these special geometries from ‘ggpp’ still +fill a gap, albeit a smaller one, in the support of NPC by ‘ggplot2’.** ## Extended Grammar of graphics @@ -43,34 +44,38 @@ albeit a smaller one, in the support of NPC by ‘ggplot2’.** The distinction between observations or data mapped to *x* and *y* aesthetics and data labels is that data labels are linked to a the -coordinates of the data, but own location is usually nearby but not -exactly that of the data. In other words the location of a data label in -*x* and *y* coordinates is flexible as long as the link to a data -observation can be inferred. In the case of annotations the location on -the plotting area is arbitrary, dictated by available graphic design -considerations and the requirement of not occluding data observations. -In the table below we list the geometries defined in package ‘ggpp’, -whether they are intended to for data labels, annotations or data, the -aesthetics and pseudo-aesthetic they obey and whether the can connect -the original data position to the displaced position where the data -label is anchored. These requires also a change in the behaviour of -position functions, that we will describe in the next section. - -| Geometry | Main use | Aesthetics | Segment | -|--------------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------|---------| -| `geom_text_s()` | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | -| `geom_label_s()` | data labels | x, y, label, size, family, font face, colour, fill, alpha, linewidth, linetype, group, vjust, hjust | yes | -| `geom_text_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | horiz. | -| `geom_label_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, fill, alpha, linewidth, linetype, group, vjust, hjust | horiz. | -| `geom_point_s()` | data labels | x, y, size, colour, fill, alpha, shape, stroke, group | yes | -| `geom_table()` | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | -| `geom_plot()` , `geom_grob()` | data labels | x, y, label, group, angle, vjust, hjust | yes | -| `geom_margin_arrow()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | -| `geom_margin_point()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | -| `geom_margin_grob()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | -| `geom_quadrant_lines()` , `geom_vhlines()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | - -Geometries defined in package ‘ggpp’ +coordinates of the data, but their own location is usually nearby but +not exactly that of the data. In other words the location of a data +label in *x* and *y* coordinates is flexible as long as the link to a +data observation can be inferred. In the case of annotations the +location on the plotting area is arbitrary, dictated by available +graphic design considerations and the requirement of not occluding data +observations. In the table below we list for the geometries defined in +package ‘ggpp’: 1) whether they are intended for data labels, +annotations or data, 2) the aesthetics and pseudo-aesthetics they obey, +and 3) whether they can connect the original data position to the +displaced position. The drawing of connecting segments or arrows between +the displaced and original positions, those of the observation and the +displaced label, requires also a change in the data returned by position +functions (see the next section). + +| Geometry | Main use | Aesthetics | Segment | +|------------------------------------------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------|---------| +| `geom_text_s()` | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | +| `geom_label_s()` | data labels | x, y, label, size, family, font face, colour, fill, alpha, linewidth, linetype, group, vjust, hjust | yes | +| `geom_text_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | horiz. | +| `geom_label_pairwise()` | data labels | x, xmin, xmax, y, label, size, family, font face, colour, fill, alpha, linewidth, linetype, group, vjust, hjust | horiz. | +| `geom_point_s()` | data labels | x, y, size, colour, fill, alpha, shape, stroke, group | yes | +| `geom_table()`1 | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes | +| `geom_plot()`1, `geom_grob()`1 | data labels | x, y, label, group, angle, vjust, hjust | yes | +| `geom_margin_arrow()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | +| `geom_margin_point()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | +| `geom_margin_grob()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | +| `geom_quadrant_lines()` , `geom_vhlines()` | data labels, scale labels, data | xintercept, yintercept, label, size, family, font face, colour, alpha, group, vjust, hjust | no | + +Geometries defined in package ‘ggpp’. 1 NPC versions exist +for these geometries, as well as for `geom_text()` and `geom_label()`, +used mainly for plot annotations. ## Position functions @@ -99,7 +104,7 @@ the the observations. Position functions `position_stacknudge()`, `position_fillnudge()`, `position_jitternudge()`, `position_dodgenudge()` and -`position_dodge2nudge()` each combines the roles of two *position* +`position_dodge2nudge()` combine each the roles of two *position* functions. They make it possible to easily nudge labels in plot layers that use stacking, dodging or jitter. Functions `position_jitter_keep()`, `position_stack_keep()`, @@ -125,7 +130,7 @@ keep in the `data` object the original coordinates. | `position_dodgenudge()` | dodge + nudge | combined, see above | data labels in column plots | | `position_dodge2nudge()` | dodge2 + nudge | combined, see above | data labels in box plots | -Position functions defined in package ‘ggpp’ +Position functions defined in package ‘ggpp’. ### Statistics diff --git a/_pkgdown.yml b/_pkgdown.yml index d1d4758..2c2d6e0 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -9,12 +9,12 @@ reference: contents: - '`ggpp-package`' - title: Scales - desc: Scales control de mapping of data to aesthetics. + desc: Scales control de mapping of values in data to values of an aesthetic, or the propeerties of the plot's graphic elements. contents: - scale_continuous_npc - compute_npcx - title: Geoms - desc: Geoms, short for geometric objects, describe the type of plot you will produce. + desc: Geoms, short for geometric objects, describe the type of plot you will produce. They add a plot layer containing graphic elements representing values in the data, contents: - annotate - geom_text_npc @@ -31,7 +31,7 @@ reference: - ttheme_gtdefault - ttheme_set - title: Statistics - desc: It is often useful to summarize data before plotting, and that is what these transformations do. + desc: It is often useful to summarize data before plotting, e.g., fiting models or computing means, or modifying the data in some other way. contents: - stat_dens1d_filter - stat_dens1d_labels @@ -43,7 +43,7 @@ reference: - stat_apply_group - stat_functions - title: Positions - desc: Advanced nudge functions + desc: It is often useful to displace plot elements away from their original positions to obtain stacked, side-by-side or non-overlapping plot elements. contents: - position_nudge_keep - position_nudge_to @@ -53,9 +53,15 @@ reference: - position_stacknudge - position_jitternudge - title: Plot creation - desc: Additional ggplot methods + desc: Additional ggplot methods for specific classes of data objects. contents: - ggplot + - title: Helper functions + desc: Additional functions that can be useful when creating plots. + contents: + - dark_or_light + - try_data_frame + - wrap_labels - title: Example data desc: Data sets as R objects. The data are used for examples in the documentation. contents: @@ -64,14 +70,6 @@ reference: - quadrant_example.df - volcano_example.df - weather_18_june_2019.df - - title: Fortify or Try - desc: Convert R objects containing observations in other formats into 'tibble' objects suitable for plotting. - contents: - - try_data_frame - - title: Utilities - desc: Utility functions - contents: - - dark_or_light navbar: structure: