Skip to content

Commit

Permalink
Clean-up docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@aphalo
aphalo committed May 3, 2024
1 parent 05fdf95 commit c6b5397
Show file tree
Hide file tree
Showing 5 changed files with 84 additions and 81 deletions.
4 changes: 2 additions & 2 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
@@ -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")),
Expand Down
12 changes: 6 additions & 6 deletions NEWS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand Down
44 changes: 22 additions & 22 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,38 +27,38 @@ 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: (<https://ggrepel.slowkow.com>) 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: (<https://ggrepel.slowkow.com>) 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

### Geometries

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 |
|-------------|-------------|---------------------------------|-------------|
Expand All @@ -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()`<sup>1</sup> | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes |
| `geom_plot()`<sup>1</sup>, `geom_grob()`<sup>1</sup> | 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'. <sup>1</sup> NPC versions exist for these geometries, as well as for `geom_text()` and `geom_label()`, used mainly for plot annotations.

## Position functions

Expand Down Expand Up @@ -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()`,
Expand All @@ -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

Expand Down
81 changes: 43 additions & 38 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,49 +28,54 @@ 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

### Geometries

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()`<sup>1</sup> | data labels | x, y, label, size, family, font face, colour, alpha, group, angle, vjust, hjust | yes |
| `geom_plot()`<sup>1</sup>, `geom_grob()`<sup>1</sup> | 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’. <sup>1</sup> NPC versions exist
for these geometries, as well as for `geom_text()` and `geom_label()`,
used mainly for plot annotations.

## Position functions

Expand Down Expand Up @@ -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()`,
Expand All @@ -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

Expand Down
Loading

0 comments on commit c6b5397

Please sign in to comment.