map                   package:maps                   R Documentation

_D_r_a_w _G_e_o_g_r_a_p_h_i_c_a_l _M_a_p_s

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

     Draw lines and polygons as specified by a map database.

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

     map(database, regions)  # simple form
     map(database = "world", regions = ".", exact = FALSE, boundary = TRUE,
       interior = TRUE, projection = "", parameters = NULL, orientation = NULL,
       fill = FALSE, col = 1, plot = TRUE, add = FALSE, namesonly = FALSE,
       xlim = NULL, ylim = NULL, wrap = FALSE, resolution = if(plot) 1 else 0,
       type = "l", bg = par("bg"), mar = c(0, 0, par("mar")[3], 0.1),
       border = 0.01, ...)

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

database: character string naming a geographical database, or a list of
          'x', 'y', and 'names' obtained from a previous call to 'map'.
          The string choices include a 'world' map, three USA databases
          ('usa', 'state', 'county'), and more (see the package index).
           The location of the map databases may be overridden by
          setting the 'R_MAP_DATA_DIR' environment variable.  See
          'world' for further details. 

 regions: character vector that names the polygons to draw. Each
          database is composed of a collection of polygons, and each
          polygon has a unique name. When a region is composed of more
          than one polygon, the individual polygons have the name of
          the region, followed by a colon and a qualifier, as in
          'michigan:north' and 'michigan:south'. Each element of
          'regions' is matched against the polygon names in the
          database and, according to 'exact', a subset is selected for
          drawing. The default selects all polygons in the database. 

   exact: If 'TRUE', only exact matches with 'regions' are selected for
          drawing. If 'FALSE', each element of 'regions' is matched as
          a regular expression against the polygon names in the
          database and all matches are selected for drawing. 

boundary: If 'FALSE', boundary segments are not drawn. A boundary
          segment is a line segment of the map that bounds only one of
          the polygons to be drawn. This argument is ignored if 'fill'
          is 'TRUE'. 

interior: If 'FALSE', interior segments are not drawn. An interior
          segment is a line segment of the map that bounds two of the
          polygons to be drawn. This argument is ignored if 'fill' is
          'TRUE'. 

projection: character string that names a map projection to use. See
          'mapproject' (in the 'mapproj' library). The default is to
          use a rectangular projection with the aspect ratio chosen so
          that longitude and latitude scales are equivalent at the
          center of the picture. 

parameters: numeric vector of parameters for use with the 'projection'
          argument. This argument is optional only in the sense that
          certain projections do not require additional parameters. If
          a projection does require additional parameters, these must
          be given in the 'parameters' argument. 

orientation: a vector 'c(latitude, longitude, rotation)' describing
          where the map should be centered and a clockwise rotation (in
          degrees) about this center. 

    fill: logical flag that says whether to draw lines or fill areas.
          If 'FALSE', the lines bounding each region will be drawn (but
          only once, for interior lines). If 'TRUE', each region will
          be filled using colors from the 'col =' argument, and
          bounding lines will not be drawn. 

     col: vector of colors. If 'fill' is 'FALSE', the first color is
          used for plotting all lines, and any other colors are
          ignored. Otherwise, the colors are matched one-one with the
          polygons that get selected by the 'region' argument (and are
          reused cyclically, if necessary). A color of 'NA' causes the
          corresponding region to be deleted from the list of polygons
          to be drawn. Polygon colors are assigned _after_ polygons are
          deleted due to values of the 'xlim' and 'ylim' arguments. 

    plot: logical flag that specifies whether plotting should be done.
          If 'plot' is 'TRUE' the return value of 'map' will not be
          printed automatically . 

     add: logical flag that specifies whether to add to the current
          plot. If 'FALSE', a new plot is begun, and a new coordinate
          system is set up. 

namesonly: If 'TRUE', the return value will be a character vector of
          the names of the selected polygons.  See the Value section
          below. 

    xlim: two element numeric vector giving a range of longitudes,
          expressed in degreees, to which drawing should be restricted.
          Longitude is measured in degrees east of Greenwich, so that,
          in particular, locations in the USA have negative longitude.
          If 'fill = TRUE', polygons selected by 'region' must be
          entirely inside the 'xlim' range. The default value of this
          argument spans the entire longitude range of the 'database'. 

    ylim: two element  numeric vector giving a range of latitudes,
          expressed in degrees, to which drawing should be restricted.
          Latitude is measured in degrees north of the equator, so
          that, in particular, locations in the USA have positive
          latitude. If 'fill = TRUE', polygons selected by 'region'
          must be entirely inside the 'ylim' range. The default value
          of this argument spans the entire latitude range of the
          'database'. 

    wrap: If TRUE, lines that cross too far across the map (due to a
          strange projection) are omitted.

resolution: number that specifies the resolution with which to draw the
          map. Resolution 0 is the full resolution of the database.
          Otherwise, just before polylines are plotted they are
          thinned: roughly speaking, successive points on the polyline
          that are within 'resolution' device pixels of one another are
          collapsed to a single point (see the Reference for further
          details). 

    type: character string that controls drawing of the map. Aside from
          the default 'type = "l"', the value 'type = "n"' can be used
          to set up the coordinate system and projection for a map that
          will be added to in later calls. 

      bg: background color. 

     mar: margins, as in 'par'. 

  border: scalar or vector of length 2 specifying the porportion of the
          plot to add to the defined or computed limits as borders. 

     ...: Extra arguments passed to 'polygon' or 'lines'.

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

     If 'plot = TRUE', a plot is made where  the polygons selected from
     'database', through the 'regions', 'xlim', and 'ylim' arguments,
     are outlined ('fill' is 'FALSE') or filled ('fill' is 'TRUE') with
     the colors in 'col'.  

     The return value is a list with 'x', 'y', 'range', and 'names'
     components.   This object can be used as a 'database' for
     successive calls to 'map' and functions. If 'fill' is 'FALSE', the
     'x' and 'y' vectors are the coordinates of successive polylines,
     separated by 'NA's.  If 'fill' is 'TRUE', the 'x' and 'y' vectors
     have coordinates of successive polygons, again separated by 'NA's.
     Thus the return value can be handed directly to 'lines' or
     'polygon', as appropriate.

     When 'namesonly' is 'TRUE', only the names component is returned.

     After a call to 'map' for which the 'projection' argument was
     specified there will be a global variable '.Last.projection'
     containing information about the projection used. This will be
     consulted in subsequent calls to 'map' which use 'projection =
     '''.

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

     Richard A. Becker, and Allan R. Wilks, "Maps in S", _AT&T Bell
     Laboratories Statistics Research Report [93.2], 1993._ <URL:
     http://public.research.att.com/areas/stat/doc/93.2.ps>

     Richard A. Becker, and Allan R. Wilks, "Constructing a
     Geographical Database", _AT&T Bell Laboratories Statistics
     Research Report [95.2], 1995._ <URL:
     http://public.research.att.com/areas/stat/doc/95.2.ps>

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

     'map.text', 'map.axes', 'map.scale', 'map.grid' (in the 'mapproj'
     library)

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

     map()   # low resolution map of the world
     map('usa')      # national boundaries
     map('county', 'new jersey')     # county map of New Jersey
     map('state', region = c('new york', 'new jersey', 'penn'))      # map of three states
     map("state", ".*dakota", border = 0)    # map of the dakotas
     map.axes()                              # show the effect of border = 0
     if(require(mapproj))
       map('state', proj = 'bonne', param = 45)      # Bonne equal-area projection of states

     # names of the San Juan islands in Washington state
     map('county', 'washington,san', names = TRUE, plot = FALSE)

     # national boundaries in one linetype, states in another
     # (figure 5 in the reference)
     map("state", interior = FALSE)
     map("state", boundary = FALSE, lty = 2, add = TRUE)

     # plot the ozone data on a base map
     # (figure 4 in the reference)
     data(ozone)
     map("state", xlim = range(ozone$x), ylim = range(ozone$y))
     text(ozone$x, ozone$y, ozone$median)
     box()

