Package 'ltxsparklines'

Lightweight Sparklines for a LaTeX Document

Description

Sparklines are small plots (about one line of text high), made popular by Edward Tufte. This package is the interface from R to the LaTeX package sparklines by Andreas Loeffer and Dan Luecking (<http://www.ctan.org/pkg/sparklines>). It can work with Sweave or knitr or other engines that produce TeX. The package can be used to plot vectors, matrices, data frames, time series (in ts or zoo format).

Details

The DESCRIPTION file:

Package:	ltxsparklines
Type:	Package
Title:	Lightweight Sparklines for a LaTeX Document
Version:	1.1.3
Authors@R:	c(person("Boris", "Veytsman", role = c("aut", "cre"), email = "[email protected]"))
Date:	2022-04-05
Description:	Sparklines are small plots (about one line of text high), made popular by Edward Tufte. This package is the interface from R to the LaTeX package sparklines by Andreas Loeffer and Dan Luecking (<http://www.ctan.org/pkg/sparklines>). It can work with Sweave or knitr or other engines that produce TeX. The package can be used to plot vectors, matrices, data frames, time series (in ts or zoo format).
Suggests:	zoo
License:	GPL-2 | GPL-3
URL:	https://github.com/borisveytsman/ltxsparklines
Repository:	https://borisveytsman.r-universe.dev
RemoteUrl:	https://github.com/borisveytsman/ltxsparklines
RemoteRef:	HEAD
RemoteSha:	5e60caabbe7ea37e570eda146841f94a5f5b2404
Author:	Boris Veytsman [aut, cre]
Maintainer:	Boris Veytsman <[email protected]>

Index of help topics:

ltxsparklines-package   Lightweight Sparklines for a LaTeX Document
sparkline               Create a Sparkline

Further information is available in the following vignettes:

ltxsparklines	sparklines (source, pdf)

There are several packages that produce sparklines in R: SparkTable by Alexander Kowarik, Bernhard Meindl, Matthias Templ (https://CRAN.R-project.org/package=sparkTable), sparklines by Bart (https://github.com/Bart6114/sparklines). However, they either provide HTML-only output, or require Java libraries. This is a lightweight and easy to use package for LaTeX users.

The package provides one function, sparkline, which outputs LaTeX code compatible with LaTeX package sparklines (Andreas Loeffer and Dan Luecking, http://www.ctan.org/pkg/sparklines).

Package options and setup

Do not forget to add \usepackage{sparklines} to the preamble of your TeX document.

There are two sets of options for sparklines in LaTeX: those which are set from TeX, and those which are set from R. The TeX options should be set with \renewcommand, \definecolor or \setlength, for example,

    % The height of the sparklines in ex units
    \renewcommand\sparklineheight{1.75} 
    % The line width
    \setlength\sparklinethickness{0.4pt}
    % The color of the sparkline
    \definecolor{sparklinecolor}{named}{blue}
    % The color of the sparkine rectangle when present
    \definecolor{sparkrectanglecolor}{gray}{0.8}
    % The dot width
    \setlength\sparkdotwidth{2pt}
    % The color of the spikes
    \definecolor{sparkspikecolor}{named}{red}
    % The color of the bottom line when present
    \definecolor{bottomlinecolor}{gray}{0.2}
    % The thickness of the bottom line
    \setlength\sparkbottomlinethickness{.2pt}
    % The clipping separation (need sparklines v1.7 or later)
    \setlength\sparklineclipsep{2pt}    
    

See the documentation for the LaTeX sparklines package.

Most options set from R define the defaults for sparkline command. They can be overriden by the corresponding argument of sparkline, for example, sparkline(...,width=20).

ltxsparklines.width

The width of the sparkline (10).

ltxsparklines.clip

Whether to clip the sparklines in the drawing region (FALSE). You need LaTeX sparklines package at least v1.7 for clip=TRUE.

ltxsparklines.na.rm

Whether to delete NA lines from the sparkline data (TRUE).

ltxsparklines.bottomline

Whether to add the bottom line (FALSE). You need LaTeX sparklines package at least v1.6 to draw bottom line.

ltxsparklines.bottomlinex

The dimensions of the extended bottom line (by default c(NA, NA), which means no extended bottom line). You need LaTeX sparklines package at least v1.7 to draw extended bottom line.

ltxsparklines.startdotcolor

The color of the dot at the start of the sparkline. If NA (the default), do not draw the dot.

ltxsparklines.enddotcolor

The color of the dot at the end of the sparkline. If NA (the default), do not draw the dot.

ltxsparklines.dotcolor

The color of dots in the sparkline (blue).

ltxsparklines.output

The output format (knitr).

Author(s)

Boris Veytsman

Maintainer: <[email protected]>

References

Andreas Loeffer and Dan Luecking, Sparklines, 2016, http://www.ctan.org/pkg/sparklines

See Also

sparkline vignette(ltxsparklines)

Examples

## Not run: 
sparkline(x=c(1,3,6),
          y=c(5,8,9),
          startdotcolor='blue',
          enddotcolor='red')

## End(Not run)
## Not run: 
sparkline(Nile)

## End(Not run)

---

Create a Sparkline

Description

The function creates a TeX expression for a sparkline from the data supplied.

Usage

sparkline(x = NULL, y = NULL, xspikes = NULL, yspikes = NULL,
          xdots = NULL, ydots = NULL, dotcolor = NULL,
          width = getOption("ltxsparklines.width"),
          rectangle = c(NA, NA),
          xlim = c(NA, NA), ylim = c(NA, NA),
          clip = getOption("ltxsparklines.clip"),
          na.rm = getOption("ltxsparklines.na.rm"),
          bottomline = getOption("ltxsparklines.bottomline"),
          bottomlinelength = NA,
          bottomlinex = getOption("ltxsparklines.bottomlinex"),
          startdotcolor = getOption("ltxsparklines.startdotcolor"),
          enddotcolor = getOption("ltxsparklines.enddotcolor"),
          output = getOption('ltxsparklines.output'))

Arguments

x	The data for sparkline. If both x and y are present, they must be vectors of the same length, and interpreted as x and y coordinates for a sparkline. If only x or y is present, then the result depends on its class: If it is a matrix or data frame, then its first column is assumed to be the x coordinate, and its second column is assumed to be the y coordinate. If it is a time series (either ts or zoo), then it is assumed to be the y coordinate, and time(x) is assumed to be the x coordinate. Otherwise it is assumed to be the y coordinate, and the sequence 1:length(x) is assumed to be x coordinate.
y	See x.
xspikes	The data for spikes: small bar chart similar to sparklines. If both xspikes and yspikes are present, they are x and y coordinates for spike. If only one is present, it is interpreted as x above.
yspikes	See xspikes above.
xdots	The data for dots: small dot chart similar to sparklines. If both xdots and ydots are present, they are x and y coordinates for dots. If only one is present, it is interpreted as x above with one addition: if xdots is a data frame, and has three or more columns, and dotcolor is not set, the third column is interpreted as the dot color.
ydots	See ydots above
dotcolor	The color of dots as a LaTeX color. A vector like c('red', 'blue', 'green'). If it is larger than the number of dots, it will be truncated. If it is shorted than the number of dots, it will be recycled. If it is not set, and data do not provide it, option('ltxsparklines.defaultdotcolor') is used.
width	The width of the sparline in ex of the current font. By default 10. To change the default, use option(ltxsparklines.width=...).
rectangle	A vector c(min,max) for the bottom and top of the background rectangle (for example, to show IQR of the data). If NA, no rectangle is drawn.
xlim	A vector c(min,max) of the x range of the data mapped to the c(0,1) interval. If any of its components is NA, the default, the actual range is used.
ylim	A vector c(min,max) of the y range of the data mapped to the c(0,1) interval. If any of its components is NA, the default, the actual range is used.
clip	Whether to clip the sparkline to the drawing region. The default is not clipping. To change the default, use option(ltxsparklines.clip=TRUE). You need LaTeX package at least v1.7 for clipping.
na.rm	Whether to delete NA lines from the spark data. If TRUE (the default), the sparkline is drawn over the gaps in the data. Otherwise gaps in the data lead to gaps in the line, so it is presented as a number of chunks. Note that continuous chunks of data must have at least two data points to be drawn. This parameter does not affect spikes or dots.
bottomline	Whether to draw a bottom line. By default, FALSE. To change the default, use option(ltxsparklines.bottomline=...). You need LaTeX package at least v1.6 for bottom lines.
bottomlinelength	The length of bottom line. If NA (the default), the bottom line extends to the end ot the spark rectangle.
bottomlinex	The dimensions of the extended bottom line. If c(NA, NA) (the default), the extended bottom line is not drawn. You need LaTeX package at least v1.7 for extended bottom lines.
startdotcolor	The color of the dot at the beginning of the spark line. If NA (the default), no dot is drawn. To change the default, use option(ltxsparklines.startdotcolor=...).
enddotcolor	The color of the dot at the end of the spark line. If NA (the default), no dot is drawn. To change the default, use option(ltxsparklines.enddotcolor=...).
output	The format of the output. Sweave uses special processing for inline (Sexpr) code. Thus you need to set output to inlineSweave if you use Sweave and Sexpr. If you use knitr or a Sweave chunk, set output to knitr. This is the default, to change it, use option(ltxsparklines.output='inlineSweave'). See Details below.

Details

Most of the parameters of the sparkline are defined by the TeX code. Thus all color values must be understandable to LaTeX. For example, you can put in the TeX file

\definecolor{startdot}{named}{red}

and then use it like sparkline(Nile, startdotcolor="startdot").

You should use LaTeX command to change sparkline parameters, for example,

\setlength\sparklinethickness{0.3pt}

The output of sparkline is also a TeX command, so you want to put it inside Sexpr or a code chunk. Note that Sweave use a special processing for Sexpr, so you need to set output="inlineSweave" for inline Sweave output. Use output="knitr" for knitr (both inline and chunks) and Sweave chunks.

The parameters xlim and ylim define the mapping between the data and the sparkline rectangle. If there are data points outside the rectangle, they may overplot the text. You may set clip to TRUE to prevent this.

Value

The function returns a string executable by TeX, to be used in \Sexpr, for example Nile level changed over the years: \Sexpr{sparkline(Nile)}.

Do not forget to add \usepackage{sparklines} to the preamble of your TeX document.

Author(s)

Boris Veytsman

See Also

ltxsparklines-package, vignette{ltxsparklines}

Examples

## Not run: 
sparkline(x=c(1,3,6),
          y=c(5,8,9),
          startdotcolor="blue",
          enddotcolor="red")

## End(Not run)
## Not run: 
sparkline(Nile)

## End(Not run)

---