labeling-manual.tex (13334B)
1 \nonstopmode{} 2 \documentclass[letterpaper]{book} 3 \usepackage[times,inconsolata,hyper]{Rd} 4 \usepackage{makeidx} 5 \usepackage[utf8,latin1]{inputenc} 6 % \usepackage{graphicx} % @USE GRAPHICX@ 7 \makeindex{} 8 \begin{document} 9 \chapter*{} 10 \begin{center} 11 {\textbf{\huge Package `labeling'}} 12 \par\bigskip{\large \today} 13 \end{center} 14 \begin{description} 15 \raggedright{} 16 \item[Type]\AsIs{Package} 17 \item[Title]\AsIs{Axis Labeling} 18 \item[Version]\AsIs{0.4.3} 19 \item[Date]\AsIs{2023-08-29} 20 \item[Author]\AsIs{Justin Talbot,} 21 \item[Maintainer]\AsIs{Nuno Sempere }\email{nuno.semperelh@gmail.com}\AsIs{} 22 \item[Description]\AsIs{Functions which provide a range of axis labeling algorithms.} 23 \item[License]\AsIs{MIT + file LICENSE | Unlimited} 24 \item[Collate]\AsIs{'labeling.R'} 25 \item[NeedsCompilation]\AsIs{no} 26 \item[Imports]\AsIs{stats, graphics} 27 \end{description} 28 \Rdcontents{\R{} topics documented:} 29 \inputencoding{utf8} 30 \HeaderA{labeling-package}{Axis labeling}{labeling.Rdash.package} 31 \aliasA{labeling}{labeling-package}{labeling} 32 \keyword{dplot}{labeling-package} 33 % 34 \begin{Description}\relax 35 Functions for positioning tick labels on axes 36 \end{Description} 37 % 38 \begin{Details}\relax 39 40 \Tabular{ll}{ Package: & labeling\\{} Type: & 41 Package\\{} Version: & 0.4.3\\{} Date: & 2023-08-29\\{} 42 License: & Unlimited\\{} LazyLoad: & yes\\{} } 43 44 Implements a number of axis labeling schemes, including 45 those compared in An Extension of Wilkinson's Algorithm 46 for Positioning Tick Labels on Axes by Talbot, Lin, and 47 Hanrahan, InfoVis 2010. 48 \end{Details} 49 % 50 \begin{Author}\relax 51 Justin Talbot \email{justintalbot@gmail.com} 52 \end{Author} 53 % 54 \begin{References}\relax 55 Heckbert, P. S. (1990) Nice numbers for graph labels, 56 Graphics Gems I, Academic Press Professional, Inc. 57 Wilkinson, L. (2005) The Grammar of Graphics, 58 Springer-Verlag New York, Inc. Talbot, J., Lin, S., 59 Hanrahan, P. (2010) An Extension of Wilkinson's Algorithm 60 for Positioning Tick Labels on Axes, InfoVis 2010. 61 \end{References} 62 % 63 \begin{SeeAlso}\relax 64 \code{\LinkA{extended}{extended}}, \code{\LinkA{wilkinson}{wilkinson}}, 65 \code{\LinkA{heckbert}{heckbert}}, \code{\LinkA{rpretty}{rpretty}}, 66 \code{\LinkA{gnuplot}{gnuplot}}, \code{\LinkA{matplotlib}{matplotlib}}, 67 \code{\LinkA{nelder}{nelder}}, \code{\LinkA{sparks}{sparks}}, 68 \code{\LinkA{thayer}{thayer}}, \code{\LinkA{pretty}{pretty}} 69 \end{SeeAlso} 70 % 71 \begin{Examples} 72 \begin{ExampleCode} 73 heckbert(8.1, 14.1, 4) # 5 10 15 74 wilkinson(8.1, 14.1, 4) # 8 9 10 11 12 13 14 15 75 extended(8.1, 14.1, 4) # 8 10 12 14 76 # When plotting, extend the plot range to include the labeling 77 # Should probably have a helper function to make this easier 78 data(iris) 79 x <- iris$Sepal.Width 80 y <- iris$Sepal.Length 81 xl <- extended(min(x), max(x), 6) 82 yl <- extended(min(y), max(y), 6) 83 plot(x, y, 84 xlim=c(min(x,xl),max(x,xl)), 85 ylim=c(min(y,yl),max(y,yl)), 86 axes=FALSE, main="Extended labeling") 87 axis(1, at=xl) 88 axis(2, at=yl) 89 \end{ExampleCode} 90 \end{Examples} 91 \inputencoding{utf8} 92 \HeaderA{extended}{An Extension of Wilkinson's Algorithm for Position Tick Labels on Axes}{extended} 93 % 94 \begin{Description}\relax 95 \code{extended} is an enhanced version of Wilkinson's 96 optimization-based axis labeling approach. It is 97 described in detail in our paper. See the references. 98 \end{Description} 99 % 100 \begin{Usage} 101 \begin{verbatim} 102 extended(dmin, dmax, m, Q = c(1, 5, 2, 2.5, 4, 3), 103 only.loose = FALSE, w = c(0.25, 0.2, 0.5, 0.05)) 104 \end{verbatim} 105 \end{Usage} 106 % 107 \begin{Arguments} 108 \begin{ldescription} 109 \item[\code{dmin}] minimum of the data range 110 111 \item[\code{dmax}] maximum of the data range 112 113 \item[\code{m}] number of axis labels 114 115 \item[\code{Q}] set of nice numbers 116 117 \item[\code{only.loose}] if true, the extreme labels will be 118 outside the data range 119 120 \item[\code{w}] weights applied to the four optimization 121 components (simplicity, coverage, density, and 122 legibility) 123 \end{ldescription} 124 \end{Arguments} 125 % 126 \begin{Value} 127 vector of axis label locations 128 \end{Value} 129 % 130 \begin{Author}\relax 131 Justin Talbot \email{justintalbot@gmail.com} 132 \end{Author} 133 % 134 \begin{References}\relax 135 Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of 136 Wilkinson's Algorithm for Positioning Tick Labels on 137 Axes, InfoVis 2010. 138 \end{References} 139 \inputencoding{utf8} 140 \HeaderA{extended.figures}{Generate figures from An Extension of Wilkinson's Algorithm for Position Tick Labels on Axes}{extended.figures} 141 % 142 \begin{Description}\relax 143 Generates Figures 2 and 3 from our paper. 144 \end{Description} 145 % 146 \begin{Usage} 147 \begin{verbatim} 148 extended.figures(samples = 100) 149 \end{verbatim} 150 \end{Usage} 151 % 152 \begin{Arguments} 153 \begin{ldescription} 154 \item[\code{samples}] number of samples to use (in the paper we 155 used 10000, but that takes awhile to run). 156 \end{ldescription} 157 \end{Arguments} 158 % 159 \begin{Value} 160 produces plots as a side effect 161 \end{Value} 162 % 163 \begin{Author}\relax 164 Justin Talbot \email{justintalbot@gmail.com} 165 \end{Author} 166 % 167 \begin{References}\relax 168 Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of 169 Wilkinson's Algorithm for Positioning Tick Labels on 170 Axes, InfoVis 2010. 171 \end{References} 172 \inputencoding{utf8} 173 \HeaderA{gnuplot}{gnuplot's labeling algorithm}{gnuplot} 174 % 175 \begin{Description}\relax 176 gnuplot's labeling algorithm 177 \end{Description} 178 % 179 \begin{Usage} 180 \begin{verbatim} 181 gnuplot(dmin, dmax, m) 182 \end{verbatim} 183 \end{Usage} 184 % 185 \begin{Arguments} 186 \begin{ldescription} 187 \item[\code{dmin}] minimum of the data range 188 189 \item[\code{dmax}] maximum of the data range 190 191 \item[\code{m}] number of axis labels 192 \end{ldescription} 193 \end{Arguments} 194 % 195 \begin{Value} 196 vector of axis label locations 197 \end{Value} 198 % 199 \begin{Author}\relax 200 Justin Talbot \email{justintalbot@gmail.com} 201 \end{Author} 202 % 203 \begin{References}\relax 204 \url{http://www.gnuplot.info/} 205 \end{References} 206 \inputencoding{utf8} 207 \HeaderA{heckbert}{Heckbert's labeling algorithm}{heckbert} 208 % 209 \begin{Description}\relax 210 Heckbert's labeling algorithm 211 \end{Description} 212 % 213 \begin{Usage} 214 \begin{verbatim} 215 heckbert(dmin, dmax, m) 216 \end{verbatim} 217 \end{Usage} 218 % 219 \begin{Arguments} 220 \begin{ldescription} 221 \item[\code{dmin}] minimum of the data range 222 223 \item[\code{dmax}] maximum of the data range 224 225 \item[\code{m}] number of axis labels 226 \end{ldescription} 227 \end{Arguments} 228 % 229 \begin{Value} 230 vector of axis label locations 231 \end{Value} 232 % 233 \begin{Author}\relax 234 Justin Talbot \email{justintalbot@gmail.com} 235 \end{Author} 236 % 237 \begin{References}\relax 238 Heckbert, P. S. (1990) Nice numbers for graph labels, 239 Graphics Gems I, Academic Press Professional, Inc. 240 \end{References} 241 \inputencoding{utf8} 242 \HeaderA{matplotlib}{Matplotlib's labeling algorithm}{matplotlib} 243 % 244 \begin{Description}\relax 245 Matplotlib's labeling algorithm 246 \end{Description} 247 % 248 \begin{Usage} 249 \begin{verbatim} 250 matplotlib(dmin, dmax, m) 251 \end{verbatim} 252 \end{Usage} 253 % 254 \begin{Arguments} 255 \begin{ldescription} 256 \item[\code{dmin}] minimum of the data range 257 258 \item[\code{dmax}] maximum of the data range 259 260 \item[\code{m}] number of axis labels 261 \end{ldescription} 262 \end{Arguments} 263 % 264 \begin{Value} 265 vector of axis label locations 266 \end{Value} 267 % 268 \begin{Author}\relax 269 Justin Talbot \email{justintalbot@gmail.com} 270 \end{Author} 271 % 272 \begin{References}\relax 273 \url{https://matplotlib.org/} 274 \end{References} 275 \inputencoding{utf8} 276 \HeaderA{nelder}{Nelder's labeling algorithm}{nelder} 277 % 278 \begin{Description}\relax 279 Nelder's labeling algorithm 280 \end{Description} 281 % 282 \begin{Usage} 283 \begin{verbatim} 284 nelder(dmin, dmax, m, 285 Q = c(1, 1.2, 1.6, 2, 2.5, 3, 4, 5, 6, 8, 10)) 286 \end{verbatim} 287 \end{Usage} 288 % 289 \begin{Arguments} 290 \begin{ldescription} 291 \item[\code{dmin}] minimum of the data range 292 293 \item[\code{dmax}] maximum of the data range 294 295 \item[\code{m}] number of axis labels 296 297 \item[\code{Q}] set of nice numbers 298 \end{ldescription} 299 \end{Arguments} 300 % 301 \begin{Value} 302 vector of axis label locations 303 \end{Value} 304 % 305 \begin{Author}\relax 306 Justin Talbot \email{justintalbot@gmail.com} 307 \end{Author} 308 % 309 \begin{References}\relax 310 Nelder, J. A. (1976) AS 96. A Simple Algorithm for 311 Scaling Graphs, Journal of the Royal Statistical Society. 312 Series C., pp. 94-96. 313 \end{References} 314 \inputencoding{utf8} 315 \HeaderA{rpretty}{R's pretty algorithm implemented in R}{rpretty} 316 % 317 \begin{Description}\relax 318 R's pretty algorithm implemented in R 319 \end{Description} 320 % 321 \begin{Usage} 322 \begin{verbatim} 323 rpretty(dmin, dmax, m = 6, n = floor(m) - 1, 324 min.n = n%/%3, shrink.sml = 0.75, high.u.bias = 1.5, 325 u5.bias = 0.5 + 1.5 * high.u.bias) 326 \end{verbatim} 327 \end{Usage} 328 % 329 \begin{Arguments} 330 \begin{ldescription} 331 \item[\code{dmin}] minimum of the data range 332 333 \item[\code{dmax}] maximum of the data range 334 335 \item[\code{m}] number of axis labels 336 337 \item[\code{n}] number of axis intervals (specify one of 338 \code{m} or \code{n}) 339 340 \item[\code{min.n}] nonnegative integer giving the 341 \emph{minimal} number of intervals. If \code{min.n == 0}, 342 \code{pretty(.)} may return a single value. 343 344 \item[\code{shrink.sml}] positive numeric by a which a default 345 scale is shrunk in the case when \code{range(x)} is very 346 small (usually 0). 347 348 \item[\code{high.u.bias}] non-negative numeric, typically 349 \code{> 1}. The interval unit is determined as 350 \code{\{1,2,5,10\}} times \code{b}, a power of 10. Larger 351 \code{high.u.bias} values favor larger units. 352 353 \item[\code{u5.bias}] non-negative numeric multiplier favoring 354 factor 5 over 2. Default and 'optimal': \code{u5.bias = 355 .5 + 1.5*high.u.bias}. 356 \end{ldescription} 357 \end{Arguments} 358 % 359 \begin{Value} 360 vector of axis label locations 361 \end{Value} 362 % 363 \begin{Author}\relax 364 Justin Talbot \email{justintalbot@gmail.com} 365 \end{Author} 366 % 367 \begin{References}\relax 368 Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) 369 \emph{The New S Language}. Wadsworth \& Brooks/Cole. 370 \end{References} 371 \inputencoding{utf8} 372 \HeaderA{sparks}{Sparks' labeling algorithm}{sparks} 373 % 374 \begin{Description}\relax 375 Sparks' labeling algorithm 376 \end{Description} 377 % 378 \begin{Usage} 379 \begin{verbatim} 380 sparks(dmin, dmax, m) 381 \end{verbatim} 382 \end{Usage} 383 % 384 \begin{Arguments} 385 \begin{ldescription} 386 \item[\code{dmin}] minimum of the data range 387 388 \item[\code{dmax}] maximum of the data range 389 390 \item[\code{m}] number of axis labels 391 \end{ldescription} 392 \end{Arguments} 393 % 394 \begin{Value} 395 vector of axis label locations 396 \end{Value} 397 % 398 \begin{Author}\relax 399 Justin Talbot \email{justintalbot@gmail.com} 400 \end{Author} 401 % 402 \begin{References}\relax 403 Sparks, D. N. (1971) AS 44. Scatter Diagram Plotting, 404 Journal of the Royal Statistical Society. Series C., pp. 405 327-331. 406 \end{References} 407 \inputencoding{utf8} 408 \HeaderA{thayer}{Thayer and Storer's labeling algorithm}{thayer} 409 % 410 \begin{Description}\relax 411 Thayer and Storer's labeling algorithm 412 \end{Description} 413 % 414 \begin{Usage} 415 \begin{verbatim} 416 thayer(dmin, dmax, m) 417 \end{verbatim} 418 \end{Usage} 419 % 420 \begin{Arguments} 421 \begin{ldescription} 422 \item[\code{dmin}] minimum of the data range 423 424 \item[\code{dmax}] maximum of the data range 425 426 \item[\code{m}] number of axis labels 427 \end{ldescription} 428 \end{Arguments} 429 % 430 \begin{Value} 431 vector of axis label locations 432 \end{Value} 433 % 434 \begin{Author}\relax 435 Justin Talbot \email{justintalbot@gmail.com} 436 \end{Author} 437 % 438 \begin{References}\relax 439 Thayer, R. P. and Storer, R. F. (1969) AS 21. Scale 440 Selection for Computer Plots, Journal of the Royal 441 Statistical Society. Series C., pp. 206-208. 442 \end{References} 443 \inputencoding{utf8} 444 \HeaderA{wilkinson}{Wilkinson's labeling algorithm}{wilkinson} 445 % 446 \begin{Description}\relax 447 Wilkinson's labeling algorithm 448 \end{Description} 449 % 450 \begin{Usage} 451 \begin{verbatim} 452 wilkinson(dmin, dmax, m, 453 Q = c(1, 5, 2, 2.5, 3, 4, 1.5, 7, 6, 8, 9), 454 mincoverage = 0.8, 455 mrange = max(floor(m/2), 2):ceiling(6 * m)) 456 \end{verbatim} 457 \end{Usage} 458 % 459 \begin{Arguments} 460 \begin{ldescription} 461 \item[\code{dmin}] minimum of the data range 462 463 \item[\code{dmax}] maximum of the data range 464 465 \item[\code{m}] number of axis labels 466 467 \item[\code{Q}] set of nice numbers 468 469 \item[\code{mincoverage}] minimum ratio between the the data 470 range and the labeling range, controlling the whitespace 471 around the labeling (default = 0.8) 472 473 \item[\code{mrange}] range of \code{m}, the number of tick 474 marks, that should be considered in the optimization 475 search 476 \end{ldescription} 477 \end{Arguments} 478 % 479 \begin{Value} 480 vector of axis label locations 481 \end{Value} 482 % 483 \begin{Note}\relax 484 Ported from Wilkinson's Java implementation with some 485 changes. Changes: 1) m (the target number of ticks) is 486 hard coded in Wilkinson's implementation as 5. Here we 487 allow it to vary as a parameter. Since m is fixed, 488 Wilkinson only searches over a fixed range 4-13 of 489 possible resulting ticks. We broadened the search range 490 to max(floor(m/2),2) to ceiling(6*m), which is a larger 491 range than Wilkinson considers for 5 and allows us to 492 vary m, including using non-integer values of m. 2) 493 Wilkinson's implementation assumes that the scores are 494 non-negative. But, his revised granularity function can 495 be extremely negative. We tweaked the code to allow 496 negative scores. We found that this produced better 497 labelings. 3) We added 10 to Q. This seemed to be 498 necessary to get steps of size 1. It is possible for 499 this algorithm to find no solution. In Wilkinson's 500 implementation, instead of failing, he returns the 501 non-nice labels spaced evenly from min to max. We want 502 to detect this case, so we return NULL. If this happens, 503 the search range, mrange, needs to be increased. 504 \end{Note} 505 % 506 \begin{Author}\relax 507 Justin Talbot \email{justintalbot@gmail.com} 508 \end{Author} 509 % 510 \begin{References}\relax 511 Wilkinson, L. (2005) The Grammar of Graphics, 512 Springer-Verlag New York, Inc. 513 \end{References} 514 \printindex{} 515 \end{document}