\name{PlotMap}
\alias{PlotMap}
\title{
  Plot Two Dimensional Data Matrix On A Map
}
\description{
  Map two dimensional data matrix, with first dimension p (longitude points)
  and second dimension q (latitude points), in either cylindrical equidistant 
  latitude and longitude projection or stereographic projection 
}
\usage{
  PlotMap(lon, lat, data, maintit = "", legtit = "", equi = TRUE, bw = FALSE, 
          cont = FALSE, reg = FALSE, ..., lonlim = c(0, 360), 
          latlim = c(50, 90), orientation = NULL, mapdat = "world", 
          xmaplim = c(-180, 180), ymaplim = c(50, 90), longrds = NULL, 
          latgrds = NULL, breaks = NULL, n = 11, colours = NULL)
}
\arguments{
  \item{lon}{
    Vector of p longitude coordinates in ascending order.
  }
  \item{lat}{
    Vector of q latitude coordinates in ascending order.
  }
  \item{data}{
    Matrix of p rows (longitudes) and q columns (latitudes) that contains the 
    data values to be plotted.
  }
  \item{maintit}{
    String with the main title of the plot. If not provided no title is 
    displayed.
  }
  \item{legtit}{
    String with the title of the colourbar. If not provided no title is 
    displayed.
  }
  \item{equi}{
    Logical. If FALSE produces stereographic projection plot. Default is TRUE.
  }
  \item{bw}{
    Logical. If TRUE produces black, gray and white plot. Default is FALSE.  
  }
  \item{cont}{
    Logical. If TRUE adds contours to the image plot. Default is FALSE.
  }
  \item{reg}{
    Logical. To be used only if plotting data in equidistant projection.
    If TRUE produces a plot using as much ares as possible of the display
    window. Default is FALSE (addequate to plot global data). 
  }
  \item{\dots}{
    Additional arguments passed to 'contour'.
  }
  \item{lonlim}{
    Range of longitudes where data will be plotted. 
    E.g. lonlim = c(0, 360) or lonlim = c(-180, 180)
  }
  \item{latlim}{
    Range of latitudes where data will be plotted. 
    E.g. latlim = c(50, 90) or latlim = c(-90, -50)
  }
  \item{orientation}{
    Orientation parameter of mapproject. For Europe as a whole a reasonable 
    setting is: orientation = c(45, 0, 7.5)
    The latter places the pole of projection to latitude 45 N.
    For the South Pole use, e.g. orientation = c(-90,0,0)
  }
  \item{mapdat}{
    Name of the dataset from which map data is taken from either maps or mpdata 
    packages for producing stereographic plots. 
    Default is "world". Other options could be for example 
    mapdat = "worldHires" plots high resolution map, mapdat = "none" no map.
  }
  \item{xmaplim}{
    Range of longitudes where the map data will be drawn. 
    In default, the map is drawn for the area of longitude and latitude 
    provided in vectors lon and lat. Sometimes it is useful to define e.g. 
    xmaplim = c(-180, 180), ymaplim = c(0,90), i.e. whole hemisphere. But this 
    will be very slow if invoked with madat = "worldHires".
  }
  \item{ymaplim}{
    Range of latitudes where the map data will be drawn.
  }
  \item{longrds}{
    NA
  }
  \item{latgrds}{
    NA
  }
  \item{breaks}{
    Vector of values for the colour bar. Must always be of length(n) + 1 (see 
    definition of n below). Default is NULL, meaning that the function produces 
    an automatic vector of breaks based on n and the range of values of the map 
    to be plotted.
  }
  \item{n}{
    Number of colours/intervals for the colour bar. Default is 11.
    For the default plot produced by this function n must be an odd number.
  }
  \item{colours}{
    Vector of colours of length n. Defauls is NULL, meaning that an 
    automatically chosen colour (or gray) scale is produced.
  }
}
\value{
  This function returns nothing.
}
\author{
  History:
  1.0  -  2005-11  (C. Coelho,                             -  Original code
       -            \email{c.a.d.s.coelho@reading.ac.uk})  -
       -  xxxx-xx  (D.J. Steinskog,                        -  ---
       -            \email{dag.johan.steinskog@nersc.no})  -       
}
\keyword{dynamic}
