pointLabel             package:maptools             R Documentation

_L_a_b_e_l _p_l_a_c_e_m_e_n_t _f_o_r _p_o_i_n_t_s _t_o _a_v_o_i_d _o_v_e_r_l_a_p_s

_D_e_s_c_r_i_p_t_i_o_n:

     Use optimization routines to find good locations for point labels
     without overlaps.

_U_s_a_g_e:

     pointLabel(x, y = NULL, labels = seq(along = x), cex = 1,
                method = c("SANN", "GA"),
                allowSmallOverlap = FALSE,
                trace = FALSE,
                doPlot = TRUE,
                ...)

_A_r_g_u_m_e_n_t_s:

    x, y: as with 'plot.default', these provide the x and y coordinates
          for the point labels.  Any reasonable way of defining the
          coordinates is acceptable.  See the function 'xy.coords' for
          details. 

  labels: as with 'text', a character vector or expression specifying
          the text to be written.  An attempt is made to coerce other
          language objects (names and calls) to expressions, and
          vectors and other classed objects to character vectors by
          'as.character'. 

     cex: numeric character expansion factor as with 'text'. 

  method: the optimization method, either "SANN" for simulated
          annealing (the default) or "GA" for a genetic algorithm. 

allowSmallOverlap: logical; if 'TRUE', labels are allowed a small
          overlap. The overlap allowed is 2% of the diagonal distance
          of the plot area.

   trace: logical; if 'TRUE', status updates are given as the
          optimization algorithms progress.

  doPlot: logical; if 'TRUE', the labels are plotted on the existing
          graph with 'text'.

     ...: arguments passed along to 'text' to specify labeling
          parameters such as 'col'. 

_D_e_t_a_i_l_s:

     Eight positions are candidates for label placement, either
     horizontally, vertically, or diagonally offset from the points.
     The default position for labels is the top right diagonal relative
     to the point (considered the preferred label position). 

     With the default settings, simulating annealing solves faster than
     the genetic algorithm. It is an open question as to which settles
     into a global optimum the best (both algorithms have parameters
     that may be tweaked).

     The label positioning problem is NP-hard (nondeterministic
     polynomial-time hard). Placement becomes difficult and slows
     considerably with large numbers of points. This function places
     all labels, whether overlaps occur or not. Some placement
     algorithms remove labels that overlap.

     Note that only 'cex' is used to calculate string width and height
     (using 'strwidth' and 'strheight'), so passing a different font
     may corrupt the label dimensions. You could get around this by
     adjusting the font parameters with 'par' prior to running this
     function.

_V_a_l_u_e:

     An 'xy' list giving the 'x' and 'y' positions of the label as
     would be placed by 'text(xy, labels)'.

_A_u_t_h_o_r(_s):

     Tom Short, EPRI, tshort@epri.com

_R_e_f_e_r_e_n_c_e_s:

     <URL: http://en.wikipedia.org/wiki/Automatic_label_placement>

     <URL:
     http://i11www.iti.uni-karlsruhe.de/map-labeling/bibliography/>

     <URL:
     http://www.eecs.harvard.edu/~shieber/Projects/Carto/carto.html>

     <URL:
     http://www.szoraster.com/Cartography/PracticalExperience.htm>

     The genetic algorithm code was adapted from the python code at 

     <URL: http://meta.wikimedia.org/wiki/Map_generator>.

     The simulated annealing code follows the algorithm and guidelines
     in:

     Jon Christensen, Joe Marks, and Stuart Shieber. Placing text
     labels on maps and diagrams. In Paul Heckbert, editor, Graphics
     Gems IV, pages 497-504. Academic Press, Boston, MA, 1994. <URL:
     http://www.eecs.harvard.edu/~shieber/Biblio/Papers/jc.label.pdf>

_S_e_e _A_l_s_o:

     'text', 'thigmophobe.labels' in package 'plotrix'

_E_x_a_m_p_l_e_s:

     n <- 50
     x <- rnorm(n)*10
     y <- rnorm(n)*10
     plot(x, y, col = "red", pch = 20)
     pointLabel(x, y, as.character(round(x,5)), offset = 0, cex = .7)

     plot(x, y, col = "red", pch = 20)
     pointLabel(x, y, expression(over(alpha, beta[123])), offset = 0, cex = .8)

