txtimage {txtplot}

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)

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 NAs.

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.

See Also

symnum, image

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)