diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml index d839dacf..c7c2fcf5 100644 --- a/.github/workflows/R-CMD-check.yaml +++ b/.github/workflows/R-CMD-check.yaml @@ -42,3 +42,14 @@ jobs: - name: Test run: ./run.sh run_tests + + - name: Upload snapshot review (on failure) + if: failure() + uses: actions/upload-artifact@v4 + with: + name: tinysnapshot-review-${{ matrix.name }} + path: | + *.Rcheck/**/_tinysnapshot_review/** + *.Rcheck/00check.log + if-no-files-found: ignore + retention-days: 7 diff --git a/NAMESPACE b/NAMESPACE index 9f5d98a1..b089312d 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -4,6 +4,7 @@ S3method(tinyplot,data.frame) S3method(tinyplot,default) S3method(tinyplot,density) S3method(tinyplot,formula) +S3method(tinyplot,ts) export(draw_legend) export(get_saved_par) export(plt) @@ -135,6 +136,7 @@ importFrom(stats,reformulate) importFrom(stats,setNames) importFrom(stats,spline) importFrom(stats,terms) +importFrom(stats,time) importFrom(stats,weighted.mean) importFrom(tools,file_ext) importFrom(utils,globalVariables) diff --git a/NEWS.md b/NEWS.md index 811ba218..0bfdec0e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -148,7 +148,9 @@ Theme fixes: subtitle, and legend stack correctly above the plot region with proper spacing. (#605) -### New plot types +### New features + +#### New plot types - `type_chull()` (equivalently, `type = "chull"`) for drawing convex hulls around grouped points. Uses `grDevices::chull()` under the hood and delegates @@ -158,10 +160,10 @@ Theme fixes: ellipses around grouped points. Like `type_chull`, works well as a filled layer, e.g. `plt_add(type = "ellipse", fill = 0.2)`. (#610 @grantmcdermott) -### Other new features +#### New `tinyplot.*` methods -- A new top-level `tinypairs()` function, together with a dedicated - `tinyplot.data.frame()` method now supports direct plotting of data frames, +- A top-level `tinypairs()` function, together with a dedicated + `tinyplot.data.frame()` method, now supports direct plotting of data frames, with or without a formula. Combining with a formula is mostly useful insofar as it facilitates piping, e.g. @@ -174,7 +176,20 @@ Theme fixes: variables will yield a `pairs()`-style grid of all variable combinations. Thanks to @mthulin for the suggestion and original implementation idea. (#613, #640 @zeileis @grantmcdermott) -- New top-level `tinyplot()`/`plt()` arguments: +- New dedicated `tinyplot.ts()` method for `ts` time series, e.g. + + ```r + plt(EuStockMarkets) + ``` + + Produces a line plot by default, although users can override by passing an + explicit `type` argument. Similarly, multivariate series are faceted by + default, but users can also override to obtain, say, a single frame with + direct labels. (#558 @zeileis @grantmcdermott) + +#### Other new features + +- New and updated top-level `tinyplot()`/`plt()` arguments: - `cap = ` for adding a caption to your plots. Captions are drawn at the bottom of the plot and are best paired with dynamic themes (since separation from `sub` is guaranteed). Appearance is customizable via @@ -211,33 +226,37 @@ Theme fixes: ``` The `labels` arg is silently ignored for non-text types. (#639 @grantmcdermott) -- The `grid` argument (and `tpar("grid")`) now accepts character strings to - control axis-specific grids at different resolutions. Uppercase letters - (`"X"`, `"Y"`, `"XY"`) draw grid lines at the standard tick positions, while - lowercase letters (`"x"`, `"y"`, `"xy"`) draw a finer grid with additional - lines at the midpoints between ticks. Thanks to @zeileis for the suggestion. - (#578 @grantmcdermott) -- Facet formulas now support `1` as a convenience syntax for single row or - column arrangements. (#562 @zeileis) - - `plt(..., facet = z ~ 1)` <-> `plt(..., facet = ~z, facet.args = list(ncol = 1))` - - `plt(..., facet = 1 ~ z)` <-> `plt(..., facet = ~z, facet.args = list(nrow = 1))`. -- `type_barplot()` gains an `offset` argument for shifting bar baselines away - from zero. (#611, #615 @grantmcdermott @zeileis) - - If the offset is an unnamed scalar or numeric vector, it shifts the bars - positionally by the given values. Useful for creating waterfall plots and - floating bars. - - If the offset is a character or named numeric vector, it instead "sets - aside" the named level(s) of the `by` group, pulling them out of the stack - and drawing them as standalone bars. This is useful for Likert plots, where - you want to show a neutral categories (e.g., "Unsure") apart from the - diverging stack. Thanks to @strengejacke for the suggestion. -- `type_text()` gains two new arguments: - - a `labeller` argument that is passed to `tinylabel()` for formatting the - text labels. (#620 @grantmcdermott) - - a `repel` argument that automatically nudges overlapping text labels apart. - One limitation is that the repulsion logic operates with groups. So there - may still be some overlapping text for for grouped data. - (#621 @grantmcdermott) + - The `grid` argument (and `tpar("grid")`) now accepts character strings to + control axis-specific grids at different resolutions. Uppercase letters + (`"X"`, `"Y"`, `"XY"`) draw grid lines at the standard tick positions, while + lowercase letters (`"x"`, `"y"`, `"xy"`) draw a finer grid with additional + lines at the midpoints between ticks. Thanks to @zeileis for the suggestion. + (#578 @grantmcdermott) + - Facet formulas now support `1` as a convenience syntax for single row or + column arrangements. (#562 @zeileis) + - `plt(..., facet = z ~ 1)` <-> `plt(..., facet = ~z, facet.args = list(ncol = 1))` + - `plt(..., facet = 1 ~ z)` <-> `plt(..., facet = ~z, facet.args = list(nrow = 1))`. +- Type-specific updates: + - `type_barplot()` gains an `offset` argument for shifting bar baselines away + from zero. (#611, #615 @grantmcdermott @zeileis) + - If the offset is an unnamed scalar or numeric vector, it shifts the bars + positionally by the given values. Useful for creating waterfall plots and + floating bars. + - If the offset is a character or named numeric vector, it instead "sets + aside" the named level(s) of the `by` group, pulling them out of the stack + and drawing them as standalone bars. This is useful for Likert plots, + where you want to show a neutral categories (e.g., "Unsure") apart from + the diverging stack. Thanks to @strengejacke for the suggestion. + - `type_text()` gains two new arguments: + - a `labeller` argument that is passed to `tinylabel()` for formatting the + text labels. (#620 @grantmcdermott) + - a `repel` argument that automatically nudges overlapping text labels + apart. One limitation is that the repulsion logic operates with groups. So + there may still be some overlapping text for for grouped data. + (#621 @grantmcdermott) + - Model-fit and various distribution types gain a `weights` argument; although + this is best provided from the top-level `tinyplot()`/`plt()` call. See + above. ### Bug fixes diff --git a/R/tinyplot.data.frame.R b/R/tinyplot.data.frame.R index f8f86f11..1633a471 100644 --- a/R/tinyplot.data.frame.R +++ b/R/tinyplot.data.frame.R @@ -37,6 +37,8 @@ #' to disambiguate from `frame.plot`. #' @param ... further arguments passed to `tinyplot`. #' +#' @returns No return value, called for the side effect of producing a plot. +#' #' @examples #' ## using tinyplot() with data frames #' tinyplot(cars) diff --git a/R/tinyplot.ts.R b/R/tinyplot.ts.R new file mode 100644 index 00000000..b578dc8e --- /dev/null +++ b/R/tinyplot.ts.R @@ -0,0 +1,119 @@ +#' tinyplot Method for Plotting ts Objects (Time Series) +#' +#' @description Convenience interface for visualizing \code{\link[stats]{ts}} +#' (time series) objects with tinyplot. +#' +#' @details Internally the time series object is converted to a long +#' data frame with columns `Time` (time index), `Value` (observations), +#' and `Series` (factor with column labels). Depending on the settings +#' of `facet` this data frame is visualized either with the formula +#' `Value ~ Time` or `Value ~ Time | Series`. See the `facet` argument +#' description for more details and the Examples below for some illustrations. +#' +#' An exception is made if the user explicitly supplies a distribution `type` +#' argument (i.e, one of `"histogram"`, `"density"`, `"boxplot"`, `"violin"`, +#' `"qq"`, `"ridge"`, or `"rug"`). These summarize the series values and +#' ignore the time index, so they are visualized with the one-sided +#' formula `~ Value` (or `~ Value | Series` for multivariate series). This +#' preserves base-R-compatible behaviour such as +#' `tinyplot(Nile, type = "histogram")`. +#' +#' @param x an object of class `"ts"`. +#' @param facet specification of `facet` for `tinyplot.formula`. The +#' default in the `tinyplot` method is to use `facet = NULL` for univariate +#' series and `facet = ~ Series` (equivalent to `facet = "by"`) for +#' multivariate series. +#' @param type,facet.args,xlab,ylab,... further arguments passed to `tinyplot`. +#' +#' @returns No return value, called for the side effect of producing a plot. +#' +#' @examples +#' ## univariate series +#' tinyplot(Nile) +#' +#' # exception: expicitly passing a distribution type on a univariate series +#' # still triggers the corresponding transformation +#' tinyplot(Nile, type = "histogram") +#' +#' ## multivariate series (generally, these also look better with a theme) +#' tinytheme("clean2") +#' tinyplot(EuStockMarkets) ## faceted, free scales, same color +#' tinyplot(EuStockMarkets, facet.args = NULL) ## faceted, same scale, same color +#' tinyplot(EuStockMarkets, facet = "by") ## faceted, free scales, diff colors +#' tinyplot(EuStockMarkets, facet = NULL) ## single frame, diff colors +#' +#' ## further variations +#' tinyplot(EuStockMarkets, facet = NULL, legend = list("direct", repel = TRUE)) +#' tinyplot(EuStockMarkets, facet = "by", facet.args = NULL) +#' tinyplot(EuStockMarkets, facet.args = list(free = TRUE, ncol = 1)) +#' +#' ## pass additional tinyplot args through `...` for further customization +#' tinyplot(EuStockMarkets, +#' facet.args = NULL, +#' type = "area", xlab = NA, yaxl = ",", +#' main = "European stock indices") +#' +#' tinytheme() ## reset +#' +#' @importFrom stats time +#' @export +tinyplot.ts = function(x, facet, type = "l", facet.args = list(free = TRUE), xlab = NULL, ylab = NA, ...) { + ## basic object properties + n = NROW(x) + k = NCOL(x) + lab = deparse(substitute(x)) + if (k > 1L) lab = paste(lab, 1L:k, sep = ".") + if (!is.null(colnames(x))) lab = colnames(x) + + single = k == 1L + + ## convert to long data.frame + df = data.frame( + Time = rep.int(as.numeric(time(x)), k), + Value = as.numeric(x), + Series = factor(rep(1L:k, each = n), labels = lab) + ) + + ## Distribution types summarize the series *values* and ignore the time index, + ## so they dispatch with a one-sided formula (`~ Value`, or `~ Value | Series` + ## when multivariate) rather than `Value ~ Time`, and skip the time-series + ## `ylab` default so tinyplot's own label (e.g. "Frequency") shows. This + ## preserves base-R-compatible behaviour like `tinyplot(Nile, type = "histogram")`. + dist_types = c("histogram", "hist", "density", "boxplot", "box", + "violin", "qq", "ridge", "rug") + ## normalize to a type name to catch both the string ("histogram") and the + ## type object (`type_histogram()`, whose `$name` is the canonical "histogram") + type_name = if (inherits(type, "tinyplot_type")) { + type[["name"]] + } else if (is.character(type) && length(type) == 1L) { + type + } else { + NA_character_ + } + is_dist = !is.na(type_name) && type_name %in% dist_types + + ## default for facet + if(missing(facet)) { + auto = TRUE + facet = if(single || is_dist) NULL else ~ Series + } else { + auto = FALSE + } + if (is.null(facet)) facet.args = NULL + + ## dispatch formula and axis labels + if (is_dist) { + fml = if (single) ~ Value else ~ Value | Series + if (single && is.null(xlab)) xlab = lab + ## use tinyplot's own ylab default (e.g. "Frequency") unless caller set one + if (missing(ylab)) ylab = NULL + } else if (single || (!is.null(facet) && auto)) { + fml = Value ~ Time + } else { + fml = Value ~ Time | Series + } + + ## call tinyplot + tinyplot(fml, data = df, type = type, facet = facet, facet.args = facet.args, + xlab = xlab, ylab = ylab, ...) +} diff --git a/altdoc/pkgdown.yml b/altdoc/pkgdown.yml index c535a9f5..0349cfa4 100644 --- a/altdoc/pkgdown.yml +++ b/altdoc/pkgdown.yml @@ -2,7 +2,7 @@ altdoc: 0.7.2 pandoc: '3.10' pkgdown: 2.1.3 pkgdown_sha: ~ -last_built: 2026-06-22T18:44:13+0000 +last_built: 2026-06-23T18:52:00+0000 urls: reference: https://grantmcdermott.com/tinyplot/man article: https://grantmcdermott.com/tinyplot/vignettes diff --git a/altdoc/quarto_website.yml b/altdoc/quarto_website.yml index 8e4e1a58..c6ce09b2 100644 --- a/altdoc/quarto_website.yml +++ b/altdoc/quarto_website.yml @@ -62,12 +62,6 @@ website: file: man/tinyplot.qmd - text: tinyplot_add file: man/tinyplot_add.qmd - - text: tinypairs - file: man/tinyplot.data.frame.qmd - # - section: "Methods" - # contents: - # - text: tinyplot.data.frame - # file: man/tinyplot.data.frame.qmd - section: "Types" contents: - section: Shapes @@ -166,6 +160,8 @@ website: contents: - text: tinyplot.data.frame file: man/tinyplot.data.frame.qmd + - text: tinyplot.ts + file: man/tinyplot.ts.qmd format: html: diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-by-direct.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-by-direct.svg new file mode 100644 index 00000000..335ce941 --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-by-direct.svg @@ -0,0 +1,74 @@ + + + + + + + + + + + + + +Time + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + + + + + + + + + + + + + + + +Series 1 +Series 2 +Series 3 +Series 4 +Series 5 + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-by-free.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-by-free.svg new file mode 100644 index 00000000..d7394fe0 --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-by-free.svg @@ -0,0 +1,260 @@ + + + + + + + + + + + + + + + + + + +Series +Series 1 +Series 2 +Series 3 +Series 4 +Series 5 + + + + + + + +Time + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +-2 +0 +2 +4 + +Series 1 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-10 +-8 +-6 +-4 +-2 +0 + +Series 2 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-2 +0 +2 +4 +6 +8 + +Series 3 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +-2 +0 +2 +4 + +Series 4 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + + +-6 +-4 +-2 +0 +2 +4 +6 + +Series 5 + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-by-same.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-by-same.svg new file mode 100644 index 00000000..9e2b98c6 --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-by-same.svg @@ -0,0 +1,242 @@ + + + + + + + + + + + + + + + + + + +Series +Series 1 +Series 2 +Series 3 +Series 4 +Series 5 + + + + + + + +Time + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 1 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 2 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 3 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 4 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 5 + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-column.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-column.svg new file mode 100644 index 00000000..f96bb8ad --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-column.svg @@ -0,0 +1,228 @@ + + + + + + + + + + + + + +Time + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +0 +4 + +Series 1 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-10 +-4 +0 + +Series 2 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-2 +2 +6 + +Series 3 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +0 +4 + +Series 4 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + + +-6 +0 +4 + +Series 5 + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-free.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-free.svg new file mode 100644 index 00000000..e78e4aae --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-free.svg @@ -0,0 +1,242 @@ + + + + + + + + + + + + + +Time + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +-2 +0 +2 +4 + +Series 1 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-10 +-8 +-6 +-4 +-2 +0 + +Series 2 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + +-2 +0 +2 +4 +6 +8 + +Series 3 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +-2 +0 +2 +4 + +Series 4 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + + + +-6 +-4 +-2 +0 +2 +4 +6 + +Series 5 + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-same.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-same.svg new file mode 100644 index 00000000..70456390 --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-same.svg @@ -0,0 +1,224 @@ + + + + + + + + + + + + + +Time + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 1 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 2 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 3 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 4 + + + + + + + + + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + +Series 5 + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-multivariate-single.svg b/inst/tinytest/_tinysnapshot/ts-multivariate-single.svg new file mode 100644 index 00000000..09ddd416 --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-multivariate-single.svg @@ -0,0 +1,87 @@ + + + + + + + + + + + + + + + + + + +Series +Series 1 +Series 2 +Series 3 +Series 4 +Series 5 + + + + + + + +Time + + + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + +-10 +-5 +0 +5 + + + + + + + + + + + + + + + + diff --git a/inst/tinytest/_tinysnapshot/ts-univariate.svg b/inst/tinytest/_tinysnapshot/ts-univariate.svg new file mode 100644 index 00000000..1266463e --- /dev/null +++ b/inst/tinytest/_tinysnapshot/ts-univariate.svg @@ -0,0 +1,65 @@ + + + + + + + + + + + + + +Time + + + + + + + +0 +20 +40 +60 +80 +100 + + + + + + +-4 +-2 +0 +2 +4 + + + + + + + + + + + + diff --git a/inst/tinytest/test-ts.R b/inst/tinytest/test-ts.R new file mode 100644 index 00000000..ee1c9f97 --- /dev/null +++ b/inst/tinytest/test-ts.R @@ -0,0 +1,51 @@ +source("helpers.R") +using("tinysnapshot") + +## five random walks +set.seed(0) +x = ts(replicate(cumsum(c(0, rnorm(100))), n = 5), start = 0) + +## univariate + +f = function() { + tinyplot(x[, 1]) +} +expect_snapshot_plot(f, label = "ts-univariate") + +## multivariate + +f = function() { + tinyplot(x) +} +expect_snapshot_plot(f, label = "ts-multivariate-free") + +f = function() { + tinyplot(x, facet.args = NULL) +} +expect_snapshot_plot(f, label = "ts-multivariate-same") + +f = function() { + tinyplot(x, facet = "by") +} +expect_snapshot_plot(f, label = "ts-multivariate-by-free") + +## Currently triggers a false positive on the devcontainer +# f = function() { +# tinyplot(x, facet = "by", facet.args = NULL) +# } +# expect_snapshot_plot(f, label = "ts-multivariate-by-same") + +f = function() { + tinyplot(x, facet = NULL, legend = list("direct", repel = TRUE)) +} +expect_snapshot_plot(f, label = "ts-multivariate-by-direct") + +f = function() { + tinyplot(x, facet = NULL) +} +expect_snapshot_plot(f, label = "ts-multivariate-single") + +f = function() { + tinyplot(x, facet.args = list(free = TRUE, ncol = 1)) +} +expect_snapshot_plot(f, label = "ts-multivariate-column") diff --git a/man/tinyplot.data.frame.Rd b/man/tinyplot.data.frame.Rd index 41bd46c7..933f471e 100644 --- a/man/tinyplot.data.frame.Rd +++ b/man/tinyplot.data.frame.Rd @@ -36,6 +36,9 @@ to disambiguate from \code{frame.plot}.} \item{...}{further arguments passed to \code{tinyplot}.} } +\value{ +No return value, called for the side effect of producing a plot. +} \description{ Convenience interface for visualizing \code{\link[base]{data.frame}} objects with tinyplot. diff --git a/man/tinyplot.ts.Rd b/man/tinyplot.ts.Rd new file mode 100644 index 00000000..2efaed63 --- /dev/null +++ b/man/tinyplot.ts.Rd @@ -0,0 +1,78 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/tinyplot.ts.R +\name{tinyplot.ts} +\alias{tinyplot.ts} +\title{tinyplot Method for Plotting ts Objects (Time Series)} +\usage{ +\method{tinyplot}{ts}( + x, + facet, + type = "l", + facet.args = list(free = TRUE), + xlab = NULL, + ylab = NA, + ... +) +} +\arguments{ +\item{x}{an object of class \code{"ts"}.} + +\item{facet}{specification of \code{facet} for \code{tinyplot.formula}. The +default in the \code{tinyplot} method is to use \code{facet = NULL} for univariate +series and \code{facet = ~ Series} (equivalent to \code{facet = "by"}) for +multivariate series.} + +\item{type, facet.args, xlab, ylab, ...}{further arguments passed to \code{tinyplot}.} +} +\value{ +No return value, called for the side effect of producing a plot. +} +\description{ +Convenience interface for visualizing \code{\link[stats]{ts}} +(time series) objects with tinyplot. +} +\details{ +Internally the time series object is converted to a long +data frame with columns \code{Time} (time index), \code{Value} (observations), +and \code{Series} (factor with column labels). Depending on the settings +of \code{facet} this data frame is visualized either with the formula +\code{Value ~ Time} or \code{Value ~ Time | Series}. See the \code{facet} argument +description for more details and the Examples below for some illustrations. + +An exception is made if the user explicitly supplies a distribution \code{type} +argument (i.e, one of \code{"histogram"}, \code{"density"}, \code{"boxplot"}, \code{"violin"}, +\code{"qq"}, \code{"ridge"}, or \code{"rug"}). These summarize the series values and +ignore the time index, so they are visualized with the one-sided +formula \code{~ Value} (or \code{~ Value | Series} for multivariate series). This +preserves base-R-compatible behaviour such as +\code{tinyplot(Nile, type = "histogram")}. +} +\examples{ +## univariate series +tinyplot(Nile) + +# exception: expicitly passing a distribution type on a univariate series +# still triggers the corresponding transformation +tinyplot(Nile, type = "histogram") + +## multivariate series (generally, these also look better with a theme) +tinytheme("clean2") +tinyplot(EuStockMarkets) ## faceted, free scales, same color +tinyplot(EuStockMarkets, facet.args = NULL) ## faceted, same scale, same color +tinyplot(EuStockMarkets, facet = "by") ## faceted, free scales, diff colors +tinyplot(EuStockMarkets, facet = NULL) ## single frame, diff colors + +## further variations +tinyplot(EuStockMarkets, facet = NULL, legend = list("direct", repel = TRUE)) +tinyplot(EuStockMarkets, facet = "by", facet.args = NULL) +tinyplot(EuStockMarkets, facet.args = list(free = TRUE, ncol = 1)) + +## pass additional tinyplot args through `...` for further customization +tinyplot(EuStockMarkets, + facet.args = NULL, + type = "area", xlab = NA, yaxl = ",", + main = "European stock indices") + +tinytheme() ## reset + +} diff --git a/vignettes/gallery_figs/line-eustockmarkets.R b/vignettes/gallery_figs/line-eustockmarkets.R index a71b8a16..dacb4b70 100644 --- a/vignettes/gallery_figs/line-eustockmarkets.R +++ b/vignettes/gallery_figs/line-eustockmarkets.R @@ -1,21 +1,11 @@ -## note: replace with tinyplot.ts method once #558 is merged - data("EuStockMarkets", package = "datasets") -eu = data.frame( - time = rep(time(EuStockMarkets), ncol(EuStockMarkets)), - market = rep(colnames(EuStockMarkets), each = nrow(EuStockMarkets)), - value = as.numeric(EuStockMarkets) -) - library("tinyplot") + +## demos the tinyplot.ts method (#558) tinyplot( - value ~ time | market, - data = eu, - facet = "by", legend = FALSE, - type = "l", - theme = "clean2", - main = "EU stock markets performance", - xlab = NA, ylab = NA, - yaxl = "," + EuStockMarkets, + yaxl = ",", + main = "EU stock markets performance", + theme = "clean2" )