Package 'txtplot' reference manual

Title:	Text Based Plots
Description:	Provides functions to produce rudimentary ascii graphics directly in the terminal window. Provides a basic plotting function (and equivalents of curve, density, acf and barplot) as well as boxplot and image functions.
Authors:	Bjoern Bornkamp [aut, cre], Ivan Krylov [ctb] (txtimage)
Maintainer:	Bjoern Bornkamp <[email protected]>
License:	LGPL
Version:	1.0-4
Built:	2024-11-09 02:50:50 UTC
Source:	https://github.com/bbnkmp/txtplot

Text based boxplot

Description

Produces rudimentary ascii boxplots. The boxplot statistics are produced using the boxplot.stats function.

Usage

txtboxplot(..., range = 1.5, legend = NULL, xlab = NULL,
           width = round(options()$width * 0.8))
txtboxplot(..., range = 1.5, legend = NULL, xlab = NULL,
           width = round(options()$width * 0.8))

Arguments

`...`	Numeric vectors for which a boxplot should be produced
`range`	This determines how far the plot whiskers extend out from the box. See `boxplot.stats` and the `coef` function for details.
`legend`	Logical determining whether a legend should be drawn. If `legend` is NULL there will be a legend drawn in case there is more than one boxplot.
`xlab`	label for x-axis of boxplot, if NULL no x-label will be plotted
`width`	Width of the plot

Note

Due to rounding to a relatively crude grid results can only be approximate. E.g. the equally spaced axis ticks may be non-equally spaced in the plot.

Author(s)

Bjoern Bornkamp

Examples

  rand1 <- rnorm(100, 1, 2)
  rand2 <- rnorm(50, 2, 2)
  rand3 <- rnorm(50, 2, 5)
  txtboxplot(rand1)
  txtboxplot(rand1, rand2, rand3)
rand1 <- rnorm(100, 1, 2)
  rand2 <- rnorm(50, 2, 2)
  rand3 <- rnorm(50, 2, 5)
  txtboxplot(rand1)
  txtboxplot(rand1, rand2, rand3)

Display a Text Image of a Matrix

Description

Print a rudimentary image of a matrix on the R console using a user-supplied alphabet as a palette of sorts.

Usage

txtimage(z, width, height, yaxis = c('up', 'down'), transpose = TRUE,
         legend = TRUE, na.char = ' ', alphabet = 0:9, Lanczos = 3)
txtimage(z, width, height, yaxis = c('up', 'down'), transpose = TRUE,
         legend = TRUE, na.char = ' ', alphabet = 0:9, Lanczos = 3)

Arguments

`z`	Numeric matrix containing values to be plotted. `NA` and `NaN` are allowed, but infinities, being impossible to scale, cause an error.
`width`	Desired width in characters. Defaults to full screen (by means of `getOption('width')`) or number of columns (rows if transposed) in `z`, whichever is less. Asking for more characters than there is in the supplied matrix results in an error.
`height`	Desired height in characters. Defaults to $25/80$ of `width` or number of rows (columns if transposed) in `z`, whichever is less. Asking for more characters than there is in the supplied matrix results in an error.
`yaxis`	Direction of the Y axis, `"up"` or `"down"`. Defaults to 'up' like in `image`.
`transpose`	Whether to arrange rows by the X axis, like `image` does. Defaults to `TRUE`.
`legend`	Whether to print the legend under the plot. If set, the returned object will have the `'cuts'` and `'alphabet'` attributes set containing the values separating the intervals and characters used for the intervals, respectively.
`na.char`	Character to substitute for values satisfying `is.na`. A warning is produced if `na.char` is found in the `alphabet` in presence of `NA` in `z`.
`alphabet`	Symbols to compose the plot of, linear scale. Either a single multi-character string or a vector of single-character strings. Defaults to `0:9`.
`Lanczos`	Positive integer defining the size of the Lanczos filter kernel. Given a value of $a$ , the windowed sinc kernel will have $2a-1$ lobes. Increasing the value may lead to better frequency response, but cause worse performance and wider undefined zones when the input contains `NA`s.

Details

By default, txtimage mimics the behaviour of image, drawing the rows of the matrix along the X axis and making the Y axis grow from bottom to the top of the plot. The function can be made to mimic matrix print instead (rows arranged vertically from top to bottom) by specifying yaxis and image.transpose arguments.

If requested width or height is different from dimensions of the matrix, it is resampled using the Lanczos filter for a given downsampling ratio $r$ and window parameter $a$ :

$% L(x) = \mathrm{sinc}(x) \, \mathrm{sinc}(x/a) \, | x | < a$

$% S_{ij} = \sum_{k, l} s_{kl} % L \left( i - \frac{k}{r} \right) % L \left( j - \frac{l}{r} \right)$

When resampling, the rows and columns are assumed to correspond to a uniform linear grid.

Value

The function is called for its side effect of printing the textual plot on the R console using cat, but it also invisibly returns the resulting character matrix. If legend is TRUE, the 'cuts' attribute contains the values separating the intervals used for characters in the alphabet (the copy of which is stored in the 'alphabet' attribute).

Note

Resampling constant signals may produce rounding errors that get greatly amplified after scaling them to diff(range(z)). For constant signals this is compensated by not allowing the resampling process to increase the range of the signal, but if the range of the matrix values is already really small (comparable to .Machine$double.eps, but not zero), the result of resampling process may not make sense.

Resampling high frequency signals (e.g. outer(1:200, 1:200, function(x,y) cos(x*y))) might give hard-to-interpret results.

Author(s)

Ivan Krylov

References

Szeliski, R. (2010) Computer Vision: Algorithms and Applications. Section 3.5.2: Decimation.

Examples

  txtimage(datasets::volcano)
  ## Not run: 
  ## try this if your terminal supports shade/block characters
  txtimage(datasets::volcano, alphabet = " \u2591\u2592\u2593\u2588")
  
## End(Not run)
txtimage(datasets::volcano)
  ## Not run: 
  ## try this if your terminal supports shade/block characters
  txtimage(datasets::volcano, alphabet = " \u2591\u2592\u2593\u2588")
  
## End(Not run)

Ascii graphics

Description

Provides a function to produce rudimentary ascii graphics directly in the terminal window.

txtplot provides the basic plotting function of two numeric vectors. All other functions below are based on this.
txtcurve is a text based equivalent of the curve function
txtdensity is a text based density estimation function based on the density function
txtacf is a text based equivalent of the acf function and based on the acf function.
txtbarchart is a text based barplot and plots the relative frequences of the occurences of the different levels of a factor (in percent)

Usage

txtplot(x, y = NULL, pch = "*", width = round(options()$width*0.8),
        height = round(0.25*width), xlab = NULL, ylab = NULL,
        xlim = NULL, ylim = NULL)

txtcurve(expr, from = NULL, to = NULL, n = 101,
         pch = "*", width = round(options()$width*0.8),
         height = round(0.25*width), xlab = NULL, ylab = NULL)

txtdensity(x, pch = "*", width = round(options()$width*0.8),
        height = round(0.25*width), xlab = NULL, ylab = NULL)

txtacf(x, pch = "*", lag.max = 20, type = c("correlation", "covariance", "partial"),
       na.action = na.fail, demean = TRUE, width = round(options()$width*0.8),
       height = round(0.25*width), xlab = NULL, ylab = NULL)

txtbarchart(x, pch = "*", width = round(options()$width*0.8),
            height = round(0.25*width), ylab = NULL)
txtplot(x, y = NULL, pch = "*", width = round(options()$width*0.8),
        height = round(0.25*width), xlab = NULL, ylab = NULL,
        xlim = NULL, ylim = NULL)

txtcurve(expr, from = NULL, to = NULL, n = 101,
         pch = "*", width = round(options()$width*0.8),
         height = round(0.25*width), xlab = NULL, ylab = NULL)

txtdensity(x, pch = "*", width = round(options()$width*0.8),
        height = round(0.25*width), xlab = NULL, ylab = NULL)

txtacf(x, pch = "*", lag.max = 20, type = c("correlation", "covariance", "partial"),
       na.action = na.fail, demean = TRUE, width = round(options()$width*0.8),
       height = round(0.25*width), xlab = NULL, ylab = NULL)

txtbarchart(x, pch = "*", width = round(options()$width*0.8),
            height = round(0.25*width), ylab = NULL)

Arguments

`x`	numeric containing the x-values to plot (for `txtbarchart` this needs to be of class factor). NA, NaN are removed for plotting. Infinities cause an error
`y`	numeric containing the x-values to plot (needs to be of the same length as x). If NULL the numeric `x` is plotted against `1:length(x)`. NA, NaN are removed for plotting. Infinities cause an error
`pch`	Plotting symbol
`width`, `height`	Width and height of the plots in points
`xlab`, `ylab`	labels for x and y axis
`xlim`, `ylim`	limits for x and y axis in plot, if equal to NULL automatically determined from x and y.
`expr`	An expression to plot (containing x)
`from`, `to`	Defines boundaries of plotting region for expr in txtcurve
`n`	integer specifying the number of x values between from and to
`lag.max`, `type`, `na.action`, `demean`	arguments for call of `acf` function, see ?acf for details

Note

Due to rounding to a relatively crude grid results can only be approximate! The equally spaced axis ticks, for example, may be non-equally spaced in the plot.

Due to the crude grid also there might be several points per pixel. The function uses the same plotting symbol no matter how many points coincide on one pixel

Author(s)

Bjoern Bornkamp

Examples

  ## basic plotting function
  require(stats)
  txtplot(cars[,1], cars[,2])
  ## can include axis labels when desired
  txtplot(cars[,1], cars[,2], xlab = "speed", ylab = "distance")

  ## text based density plot
  txtdensity(rnorm(500))

  ## text based plotting of functions
  txtcurve(x/(x+1), 0, 4, xlab = "Emax model")

  ## text based acf
  txtacf(rnorm(100))

  ## text based barchart
  x <- factor(c("orange", "orange", "red", "green", "green", "red",
               "yellow", "purple", "purple", "orange"))
  txtbarchart(x)

  ## text based boxplots
  rand1 <- rnorm(100, 1, 2)
  rand2 <- rnorm(50, 2, 2)
  rand3 <- rnorm(50, 2, 5)
  txtboxplot(rand1)
  txtboxplot(rand1, rand2, rand3)

## basic plotting function
  require(stats)
  txtplot(cars[,1], cars[,2])
  ## can include axis labels when desired
  txtplot(cars[,1], cars[,2], xlab = "speed", ylab = "distance")

  ## text based density plot
  txtdensity(rnorm(500))

  ## text based plotting of functions
  txtcurve(x/(x+1), 0, 4, xlab = "Emax model")

  ## text based acf
  txtacf(rnorm(100))

  ## text based barchart
  x <- factor(c("orange", "orange", "red", "green", "green", "red",
               "yellow", "purple", "purple", "orange"))
  txtbarchart(x)

  ## text based boxplots
  rand1 <- rnorm(100, 1, 2)
  rand2 <- rnorm(50, 2, 2)
  rand3 <- rnorm(50, 2, 5)
  txtboxplot(rand1)
  txtboxplot(rand1, rand2, rand3)

Package 'txtplot'

Help Index

Text based boxplot

Description

Usage

Arguments

Note

Author(s)

See Also

Examples

Display a Text Image of a Matrix

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

Ascii graphics

Description

Usage

Arguments

Note

Author(s)

See Also

Examples