txtimage: Display a Text Image of a Matrix
In txtplot: Text Based Plots

Description Usage Arguments Details Value Note Author(s) References See Also Examples

View source: R/txtimage.R

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

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

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

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) = sinc(x) sinc(x/a) |x|<a

S[i, j] = sum(s[k, l] * tcrossprod(L(i - k/r), L(j - l/r)))

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

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

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.

Ivan Krylov

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

symnum, image

  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)

01111111111111111111111111111111111111111111000010000000000000000000000000000000
11111111111111111111111111222211111111111111111111100000000000000000000000000000
11111111111111111222333333333332222211111111111111111110000000000000000000000000
11111111122222223344444445544444332222222222111111111100000000000000000000000000
11111112222333444555566666666555443333222222222211111111110000000000000000000000
11111112223344555667777888877766655443333222222222111111111110000000000000000000
11112223334445566778888888888877665444333333333222222222222111100000000000000000
11122334445566677889888888888887665544433333333333334444332222111100000000000000
11223444555677788999888877778777666555444444444444444444443322211111000000000000
12233445566778899999877766666777766665554444444444444444433332221111111000000000
12233445667788999999877665555667777766665555555555444444433332222211111110000000
11233455667788999999876665555667777777666666665555544444433333222222211111110000
11223445667788899999877666666677788887766666666655554444444333332222221111111100
11222334566778899999988777777778888887777777776665555555444443333322222111111110
11122233456677889999998888888888888887777777777666555555555554433332221111111100
01112223455677888899999888888887777777766677777666655555555555444333221111000000
00111223345667777888888888877766666666666666666666555555555555544432211000000000
01111122334566666777777777766655555555555555555555555555555555544332111000000000
00111112223344555566676666665555554444444444444444445555555555444322111110000000
00011111122333344445566665555444443333333333344444444444444444433332211110000000
00000111112222333344455555544433332222223333333333333333333333333322111110000000
00001111111222233334444444443332222222222222222222222222222233322221111100000000
00011111111122223333444444333222222212222222222222222222222222222211111000000000
00011111111122222333333333222211111111111122222222211122222222222211100000000000
00001111111112222222233322222111111111111111122221111111222222222111100000000000

 94 ‘0’ 104 ‘1’ 114 ‘2’ 124 ‘3’ 134 ‘4’ 144 ‘5’ 154 ‘6’ 164 ‘7’ 174 ‘8’ 184 ‘9’ 194 
                                                                                
                          ░░░░                                                  
                 ░░░░░░░░░░░░░░░░░░░                                            
         ░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░░                                    
       ░░░░░░░▒▒▒▒▒▒▒▓▓▓▓▓▓▓▓▒▒▒▒▒░░░░░░░░░░░░░░                                
       ░░░░░▒▒▒▒▒▓▓▓▓▓▓████▓▓▓▓▓▓▒▒▒▒░░░░░░░░░░░░░                              
    ░░░░░░▒▒▒▒▒▓▓▓▓███████████▓▓▓▓▒▒▒▒░░░░░░░░░░░░░░░░░░░░░                     
   ░░░░▒▒▒▒▒▓▓▓▓▓██████████████▓▓▓▒▒▒▒▒░░░░░░░░░░░░░▒▒▒▒░░░░░░                  
  ░░░▒▒▒▒▒▒▓▓▓▓█████████▓▓▓▓█▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░                 
 ░░░░▒▒▒▒▓▓▓▓████████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░                
 ░░░░▒▒▒▓▓▓▓█████████▓▓▓▓▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░              
  ░░░▒▒▒▓▓▓▓█████████▓▓▓▓▒▒▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░░           
  ░░░▒▒▒▓▓▓▓█████████▓▓▓▓▓▓▓▓▓▓▓▓████▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░          
  ░░░░░▒▒▓▓▓▓██████████▓▓▓▓▓▓▓▓██████▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░         
   ░░░░░▒▒▓▓▓▓███████████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░          
    ░░░░▒▒▒▓▓▓█████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░          
     ░░░░▒▒▓▓▓▓▓▓██████████▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░           
      ░░░░▒▒▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░            
       ░░░░░▒▒▒▒▒▒▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░            
         ░░░░░░▒▒▒▒▒▒▓▓▓▓▒▒▒▒▒▒▒▒▒░░░░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░           
          ░░░░░░░░▒▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░            
           ░░░░░░░░▒▒▒▒▒▒▒▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░             
            ░░░░░░░░▒▒▒▒▒▒░░░░░░░░░░ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░              
            ░░░░░░░░░░░░░░░░░░            ░░░░░░░░░   ░░░░░░░░░░░░              
             ░░░░░░░░░░░░░░░░                ░░░░       ░░░░░░░░░               

 94 ‘ ’ 114 ‘░’ 134 ‘▒’ 154 ‘▓’ 174 ‘█’ 194