\name{PlotEquiMap}
\alias{PlotEquiMap}
\title{
Maps A Two-Dimensional Variable On A Cylindrical Equidistant Projection
}
\description{
Map longitude-latitude array (on a regular rectangular or gaussian grid) on a cylindrical equidistant latitude and longitude world projection with coloured grid cells. Only the region for which data has been provided is displayed. A colour bar (legend) can be plotted and adjusted. It is possible to draw superimposed arrows, dots, symbols, contour lines and boxes. A number of options is provided to adjust the position, size and colour of the components. This plot function is compatible with figure layouts.
}
\usage{
PlotEquiMap(var, lon, lat, varu = NULL, varv = NULL, 
            toptitle = NULL, sizetit = NULL, units = NULL,
            brks = NULL, cols = NULL, bar_limits = NULL,
            colNA = 'white', triangle_ends = NULL,
            color_fun = clim.colors,
            square = TRUE, filled.continents = TRUE,
            coast_color = NULL, coast_width = 1,
            contours = NULL, brks2 = NULL, contour_lwd = 0.5,
            contour_color = 'black', contour_label_scale = 1,
            dots = NULL, dot_symbols = '.', dot_size = 1,
            arr_subsamp = floor(length(lon) / 30), 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,
            axes_tick_scale = 1, axes_label_scale = 1,
            drawleg = TRUE, subsampleg = NULL, 
            bar_extra_labels = NULL, draw_bar_ticks = TRUE, 
            draw_separators = FALSE, triangle_ends_scale = 1, 
            bar_label_digits = 4, bar_label_scale = 1, 
            units_scale = 1, bar_tick_scale = 1, 
            bar_extra_margin = rep(0, 4),
            boxlim = NULL, boxcol = 'purple2', boxlwd = 5,
            extra_margin = rep(0.5, 4), title_scale = 1,
            numbfig = NULL, fileout = NULL, ...)
}
\arguments{
  \item{var}{
Array with the values at each grid cell on a regular rectangular or gaussian grid. The array is expected to have two dimensions: c(latitude, longitude), longitudes in ascending or descending order and latitudes in any order. It can contain NA values (coloured with 'colNA'). Arrays with dimensions c(longitude, latitude) will also be accepted but 'lon' and 'lat' will be used to disambiguate so this alternative is not appropriate for square arrays. The data array can contain data for two adjacent regions that are s
  }
  \item{lon}{i
Numeric vector of longitude locations of the cell centers of the grid of 'var', in ascending or descending order (same as 'var'). Expected to be regularly spaced, within either of the ranges [-180, 180] or [0, 360]. Data for two adjacent regions split by the limits of the longitude range can also be provided, e.g. \code{lon = c(0:50, 300:360)} ('var' must be provided consitently).
  }
  \item{lat}{
Numeric vector of latitude locations of the cell centers of the grid of 'var', in any order (same as 'var'). Expected to be from a regular rectangular or gaussian grid, within the range [-90, 90].
  }
  \item{varu}{
Array of the zonal component of wind/current/other field with the same dimensions as 'var'.
  }
  \item{varv}{
Array of the meridional component of wind/current/other field with the same dimensions as 'var'.
  }
  \item{toptitle}{
Top title of the figure, scalable with parameter 'title_scale'.
  }
  \item{sizetit}{
Scale factor for the figure top title provided in parameter 'toptitle'. Deprecated. Use 'title_scale' instead.
  }
  \item{units}{
Title at the top of the colour bar, most commonly the units of the variable provided in parameter 'var'.
  }
  \item{brks,cols,bar_limits,triangle_ends}{
These parameters allow to define n breaks that define n - 1 intervals to classify each of the values in 'var'. The corresponding grid cell of a given value in 'var' will be coloured in function of the interval it belongs to. These parameters are sent to \code{ColorBar()} to generate the breaks and colours. Additional colours for values beyond the limits of the colour bar are also generated and applied to the plot if 'bar_limits' or 'brks' and 'triangle_ends' are properly provided to do so. See ?ColorBar for a full explanation.\cr
  }
  \item{colNA}{
Colour identifier to colour the NA values in 'var'. 'white' by default.
  }
  \item{color_fun,subsampleg,bar_extra_labels,draw_bar_ticks,draw_separators,triangle_ends_scale,bar_label_digits,bar_label_scale,units_scale,bar_tick_scale,bar_extra_margin}{
Set of parameters to control the visual aspect of the drawn colour bar. See ?ColorBar for a full explanation.
  }
  \item{square}{

  }
  \item{filled.continents}{

  }
  \item{coast_color}{

  }
  \item{coast_width}{

  }
  \item{contours}{

  }
  \item{brks2}{

  }
  \item{contour_lwd}{

  }
  \item{contour_color}{

  }
  \item{contour_label_scale}{

  }
  \item{dots}{

  }
  \item{dot_symbols}{

  }
  \item{dot_size}{

  }
  \item{arr_subsamp}{

  }
  \item{arr_scale}{

  }
  \item{arr_ref_len}{

  }
  \item{arr_units}{

  }
  \item{arr_scale_shaft}{

  }
  \item{arr_scale_shaft_angle}{

  }
  \item{axelab}{

  }
  \item{labW}{

  }
  \item{intylat}{

  }
  \item{intxlon}{

  }
  \item{axes_tick_scale}{

  }
  \item{axes_label_scale}{

  }
  \item{drawleg}{

  }
  \item{boxlim}{

  }
  \item{boxcol}{

  }
  \item{boxlwd}{

  }
  \item{extra_margin}{

  }
  \item{title_scale}{

  }
  \item{numbfig}{

  }
  \item{fileout}{

  }
  \item{\dots}{

  }


  \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.
If one of cols or breaks is provided, the missing one is computed automatically.
If none is provided, the breaks and the colours are computed automatically, with 21 breaks.
A single integer number can be provided as brks, and as many breaks as specified will be
generated, and brks-1 colours will be generated.
  }
  \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`
  }
}
\value{
  \item{brks}{
The break values used to cluster the coloured regions.
  }
  \item{cols}{
The colours used to colour each of the brks-1 regions.
  }
}
\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}
