\name{PlotEquiMap}
\alias{PlotEquiMap}
\title{
Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection
}
\description{
Map a two dimensional matrix with (longitude, latitude) dimensions on a cylindrical equidistant latitude and longitude projection.
}
\usage{
PlotEquiMap(var, lon, lat, varu = NULL, varv = NULL,
            toptitle = '', sizetit = 1, units = '', 
            brks = NULL, cols = NULL, square = TRUE, 
            filled.continents = TRUE, contours = NULL, 
            brks2 = NULL, dots = NULL, 
            arr_subsamp = 1, arr_scale = 1,
            arr_ref_len = 15, arr_units = "m/s",
            arr_scale_shaft = 1, arr_scale_shaft_angle = 1,
            axelab = TRUE, labW = FALSE, 
            intylat = 20, intxlon = 20, drawleg = TRUE, 
            boxlim = NULL, boxcol = "purple2", boxlwd = 10,
            subsampleg = 1, numbfig = 1, colNA = 'white', 
            fileout = NULL, ...)
}
\arguments{
  \item{var}{
Matrix to plot with (longitude, latitude) dimensions.
  }
  \item{lon}{
Array of longitudes.
  }
  \item{lat}{
Array of latitudes.
  }
  \item{varu}{
Matrix of the zonal component of wind/current/other field with (longitude, 
latitude) dimensions (not compatible with square = FALSE and 
drawleg = TRUE, optional).
  }
  \item{varv}{
Matrix of the meridional component of wind/current/other field with (longitude, 
latitude) dimensions (not compatible with square = FALSE and 
drawleg = TRUE, optional).
  }
  \item{toptitle}{
Title, optional.
  }
  \item{sizetit}{
Multiplicative factor to increase title size, optional.
  }
  \item{units}{
Units, optional.
  }
  \item{brks}{
Colour levels, optional.
  }
  \item{cols}{
List of colours, optional.
  }
  \item{square}{
Field coloured with squares (TRUE) for each grid cell or spatial smoothing (FALSE).\cr
Default: TRUE.
  }
  \item{filled.continents}{
Continents filled in grey (TRUE) or represented by a black line (FALSE).\cr
Default = TRUE.\cr
Filling unavailable if crossing Greenwich.\cr
Filling unavailable if square = FALSE.
  }
  \item{contours}{
Matrix to be added to the plot and shown with contours. Default = NULL.
  }
  \item{brks2}{
Contour levels, optional.
  }
  \item{dots}{
Matrix with TRUE / FALSE flags to add black dots over the maps (to show where a 
score is significant for example). Option only available if square = TRUE.
  }
  \item{arr_subsamp}{
If varu and varv set, arr_subsamp defines the interval between two arrows in grid 
point (Default: 2, in other words an arrow is plotted every 2 grid points).
  }
  \item{arr_scale}{
Scale for the arrow, default = 1
  }
  \item{arr_ref_len}{
Length of the refence arrow (in same unit as varu and varv, only affects the 
legend for the wind or variable in these arrays. Default: 15).
  }
  \item{arr_units}{
Unit of varu and varv (for the legend, default: m/s).
  }
  \item{arr_scale_shaft}{
Parameter for the scale of the shaft of the arrows (which also depend on the 
number of figures and the arr_scale parameter, Default: 1).
  }
  \item{arr_scale_shaft_angle}{
Parameter for the scale of the angle of the shaft of the arrows (which also 
depend on the number of figure and the arr_scale parameter, Default: 1).
  }
  \item{axelab}{
TRUE/FALSE, label the axis. Default = TRUE.
  }
  \item{labW}{
Label the longitude axis with W instead of minus. Default = FALSE. 
  }
  \item{intylat}{
Interval between latitude ticks on y-axis. Default = 20deg.
  }
  \item{intxlon}{
Interval between longitude ticks on x-axis. Default = 20deg.
  }
  \item{drawleg}{
Draw a colorbar. Can be FALSE only if square = FALSE.\cr
Must be FALSE if numbfig > 1. Default = TRUE.
  }
  \item{boxlim}{
The area over which to draw a rectangle over the map.\cr
A vector of length 4 such that: c(western boundary, southern boundary, eastern boundary, northern boundary)
  }
  \item{boxcol}{
Color of the rectangle. Default: 'purple2'.
  }
  \item{boxlwd}{
Thickness of the rectangle side. Default: 10.
  }
  \item{subsampleg}{
Supsampling factor of the interval between ticks on colorbar.\cr
Default = 1 = every colour level.
  }
  \item{numbfig}{
Number of figures in the final multipanel.
  }
  \item{colNA}{
Color used to represent NA. Default = 'white'
  }
  \item{fileout}{
Name of output file. Extensions allowed: eps/ps, jpeg, png, pdf, bmp 
and tiff. \cr
Default = NULL
  }
  \item{...}{
    Arguments to be passed to the method. Only accepts the following
    graphical parameters:

    adj ann ask bg bty cex.sub cin col.axis col.lab col.main col.sub cra crt csi cxy err family fg font font.axis font.lab font.main font.sub lend lheight ljoin lmitre mex mfcol mfrow mfg mkh omd omi page pch pin plt pty smo srt tcl usr xaxp xaxs xaxt xlog xpd yaxp yaxs yaxt ylbias ylog
    
    For more information about the parameters see `par`
  }
}
\examples{
# See examples on Load() to understand the first lines in this example
  \dontrun{
data_path <- system.file('sample_data', package = 's2dverification')
expA <- list(name = 'experiment', path = file.path(data_path,
             'model/$EXP_NAME$/$STORE_FREQ$_mean/$VAR_NAME$_3hourly',
             '$VAR_NAME$_$START_DATE$.nc'))
obsX <- list(name = 'observation', path = file.path(data_path,
             '$OBS_NAME$/$STORE_FREQ$_mean/$VAR_NAME$',
             '$VAR_NAME$_$YEAR$$MONTH$.nc'))

# Now we are ready to use Load().
startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
sampleData <- Load('tos', list(expA), list(obsX), startDates,
                   leadtimemin = 1, leadtimemax = 4, output = 'lonlat',
                   latmin = 27, latmax = 48, lonmin = -12, lonmax = 40)
  }
  \dontshow{
startDates <- c('19851101', '19901101', '19951101', '20001101', '20051101')
sampleData <- s2dverification:::.LoadSampleData('tos', c('experiment'),
                                                c('observation'), startDates,
                                                leadtimemin = 1,
                                                leadtimemax = 4,
                                                output = 'lonlat',
                                                latmin = 27, latmax = 48,
                                                lonmin = -12, lonmax = 40)
  }
PlotEquiMap(sampleData$mod[1, 1, 1, 1, , ], sampleData$lon, sampleData$lat, 
            toptitle = 'Predicted sea surface temperature for Nov 1960 from 1st Nov',
            sizetit = 0.5)
}
\author{
  History:
  0.1  -  2011-11  (V. Guemas, \email{virginie.guemas@ic3.cat})  -  Original code
  0.2  -  2013-04  (R. Saurral \email{ramiro.saurral@ic3.cat}) - LabW
  1.0  -  2013-09  (N. Manubens, \email{nicolau.manubens@ic3.cat})  -  Formatting to R CRAN
  1.1  -  2013-09  (C. Prodhomme, \email{chloe.prodhomme@ic3.cat})  - add winds
}
\keyword{dynamic}
