-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathREADME.qmd
157 lines (128 loc) · 6.18 KB
/
README.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "70%",
fig.width = 8,
dpi = 300,
asp = 0.625
)
```
# tinyplot <img src="man/figures/logo.png" align="right" height="139" alt="" />
<!-- badges: start -->
<a href="https://CRAN.R-project.org/package=tinyplot"><img src="https://www.r-pkg.org/badges/version/tinyplot" class="img-fluid" alt="CRAN version"></a>
<a href="https://grantmcdermott.r-universe.dev"><img src="https://grantmcdermott.r-universe.dev/badges/tinyplot" class="img-fluid" alt="R-universe status badge"></a>
<a href="https://CRAN.R-project.org/package=tinyplot"><img src="https://tinyverse.netlify.app/badge/tinyplot" class="img-fluid" alt="Dependencies"></a>
<a href="https://github.com/grantmcdermott/tinyplot/actions/workflows/R-CMD-check.yaml"><img src="https://github.com/grantmcdermott/tinyplot/actions/workflows/R-CMD-check.yaml/badge.svg" class="img-fluid" alt="ci"></a>
<a href = "https://github.com/grantmcdermott/tinyplot/blob/main/LICENSE.md" target = "_blank"><img src="https://img.shields.io/badge/license-Apache2.0-blue"></a>
<a href="https://grantmcdermott.com/tinyplot/index.html"><img src="https://img.shields.io/badge/docs-homepage-blue.svg" class="img-fluid" alt="Docs"></a>
<!-- badges: end -->
## What
A lightweight extension of the base R graphics system, with support for
automatic grouping, legends, facets, themes, and various other enhancements.
The stable version of **tinyplot** is available on CRAN.
``` r
install.packages("tinyplot")
```
Or, you can grab the latest development version from R-universe.
``` r
install.packages("tinyplot", repos = "https://grantmcdermott.r-universe.dev")
```
## Why
R users are spoiled for choice when it comes to visualization frameworks. The
options, of course, include **ggplot2** and **lattice**; say nothing of the
bewildering array of extensions built around, on top of, and in between these
amazing packages.^[You could make a strong case that **ggplot2**, in particular,
is the most influential graphics library of the last two decades, across any
programming language. Both **ggplot2** and **lattice** are built on top of the
lower-level **grid** package, which was incorporated into the base R
distribution way back in R 2.0.0.]
Given the wealth of options, it is perhaps understandable that even avid R users
can overlook the base R **graphics** system. This is unfortunate, because base R
offers very powerful and flexible plotting facilities.^[Just type
`demo(graphics)` or `demo(persp)` into your R console to get an idea. Or, take a
look at
[these](https://github.com/karoliskoncevicius/r_notes/blob/main/baseplotting.md)
[two](https://poisonalien.github.io/basegraphics/baseplots.html)
excellent tutorials.]
The downside of this power and flexibility is that base R plotting can require a
lot of manual tinkering. A case in point is plotting grouped data with an
appropriate legend. Doing so with the generic `plot()` function can require
several function calls or a loop, fiddling with your plot regions, and then
generating the legend manually.
The **tinyplot** package aims to remove this overhead. It provides a lightweight
extension of the base R graphics system that preserves the same core logic and
syntax, but with numerous convenience features to make base R plotting a more
user-friendly experience. For example, the core `tinyplot()` function---or its
shorthand alias `plt()`---makes it easy to plot grouped datasets and generate
automatic legends in a single function call. Or, you can display groups in
separate facets without having to worry about manually setting plot regions.
While **tinyplot** offers these and various other enhancements, it tries as far
as possible to be a drop-in replacement for the equivalent base plotting
function. Users should generally be able to swap out a valid `plot()` call for
`tinyplot()`/`plt()` without any changes to the expected output.
It is worth emphasizing that **tinyplot** requires _only_ base R. It has zero
recursive dependencies and we have been careful to keep its installation size
down to a minimum. **tinyplot** should thus provide an attractive and
lightweight option for package developers (or regular R users!) who would like
to produce convenient and sophisticated plots, combined with a minimal
footprint.
## Quickstart
The **tinyplot** website includes a detailed
[introductory tutorial](https://grantmcdermott.com/tinyplot/vignettes/introduction.html),
with numerous examples. But here are some quickstart examples of the package in
action.
```{r quickstart1}
library(tinyplot)
```
Grouped scatterplot with automatic legend:
```{r quickstart2}
# with(iris, tinyplot(x = Petal.Length, y = Sepal.Length, by = Species)) # atomic
tinyplot(Sepal.Length ~ Petal.Length | Species, data = iris) # formula
```
If you would prefer to save on a few keystrokes, you can use the shorthand
`plt()` alias instead instead of typing out `tinyplot()` in full. Here's the
same plot with this shorthand alias, plus a few aesthetic tweaks:
```{r quickstart3}
plt(
Sepal.Length ~ Petal.Length | Species,
data = iris,
palette = "dark", pch = 16,
grid = TRUE, frame = FALSE
)
```
Speaking of aesthetic tweaks, **tinyplot** also provides a set of built-in
themes for convenient plot customization:
```{r quickstart_theme}
tinytheme("clean2")
plt(Sepal.Length ~ Petal.Length | Species, data = iris)
```
Themes are persistent and will be applied to subsequent plots. For example, here
is a grouped grouped density plot:
```{r quickstart4}
plt(
~ Petal.Length | Species,
data = iris,
type = "density",
fill = "by",
main = "Distribution of petal lengths",
sub = "Grouped by species"
)
```
Grouped scatterplot with (continuous) gradient legend, combined with facet
layout:
```{r quickstart5}
plt(
Sepal.Length ~ Petal.Length | Sepal.Length, data = iris,
facet = ~Species, pch = 19,
main = "Faceted flowers", sub = "Brought to you by tinyplot"
)
```
```{r quickstart6}
# reset the theme
tinytheme()
```
Hopefully, these have been enough to pique your interest. Head over to the
[intro tutorial](https://grantmcdermott.com/tinyplot/vignettes/introduction.html)
for many more examples, including model-based and custom plot types.