MASK_LONLATMONTH

Name

MASK_LONLATMONTH

Purpose

This procedure returns a version of the input lon-lat-month data set
Data which has been masked according to Mask and other selected
criteria. It will also do some area and time averaging.

Calling Sequence

mask_lonlatmonth, Data, Mask

Inputs

Data: A array of data to be masked. Of dimensions NLON*NLAT*NTIME.
Missing data should be denoted by NaN. Note this is also an
output.
Mask: A masking array of dimensions NMASKLON*NMASKLAT or
NLON*NLAT*NTIME. Values are 1 (keep) or NaN (discard).
ANOMALY, BASEPERIOD, DESEASONALISE, FRACAREAGOOD, FRACBASEGOOD,
FRACINTERPOLATEGOOD, FRACMEANLATGOOD, FRACMEANLONGOOD, FRACSEASGOOD,
LAT, LON, MASKLAT, MASKLON, MEANAREA, MEANLAT, MEANLON, SEASLEN,
SEASON, TIME

Keyword Parameters

ANOMALY: If set then the anomalies from the BASEPERIOD average are
returned. The default is not set.
AREAGOOD: Returns the fraction of the domain (or of FRACMASKAREA or
of the weighting in COVERAGE if either is given) with
non-missing data as a function of time, in a vector of length
NTIME.
BASEPERIOD: A vector of length two defining the climatological base
period. The first/second elements give the first/last year of
the period. See months_to_seasons.pro for more information.
COVERAGE: An array of size NLON*NLAT containing the fraction of each
cell to include when spatially averaging. This is useful for
instance if a spatial subset of Data is being averaged and a
certain cell straddles the border of that subset. Values
range from 0 (omit) to 1 (include fully).
DESEASONALISE: If set then the seasonal cycle is removed from the
data before the seasonal values are calculated. See
months_to_seasons.pro for more information.
FRACAREAGOOD: The fraction of the total area (or of FRACMASKAREA if
it is given) that needs non-missing data in order to be
spatially averaged when MEANAREA is set. The default is 0.5.
FRACBASEGOOD: The fraction of years in the base period required to
have non-missing values in order for the base value to be
calculated. The default is 0.5.
FRACINTERPOLATEGOOD: The fraction of the area in a new grid cell that
needs non-missing data in the old grid cells being
interpolated in order for the interpolation to be carried out
(as against being counted as missing data). The default is
0.5.
FRACMASKAREA: The fraction of the total area to be considered when
checking if the FRACAREAGOOD criterion has been passed. If
set to -1 then the mask coverage over the climatological base
period is used, and this fraction of the total area is
returned. The default is to use the actual total area covered
by the grid covered by LAT and LON.
FRACSEASGOOD: The fraction of the season that needs non-missing data
in order to be averaged when seasonal averaging is selected.
The default is 0.5.
LAT: A vector of latitude values for Data. Of length NLAT. This is
required if MEANLAT or MEANAREA is set. Also returns the
vector of latitude values for the returned masked Data, of
length NOUTLAT.
LON: A vector of longitude values for Data. Of length NLON. Also
returns the vector of longitude values for the returned masked
Data, of length NOUTLON.
MASKLAT: A vector of the latitude values of the mask. Of length
NMASKLAT. If not set then MASKLAT is assumed to equal LAT.
MASKLON: A vector of the longitude values of the mask. Of length
NMASKLON. If not set then MASKLON is assumed to equal LON.
MEANAREA: If set then the spatial mean is returned. The default is
not set.
MEANDATA: Returns an array of the time average of the masked Data
averaged over BASEPERIOD. Of size NOUTLON*NOUTLAT.
MEANLAT: If set then the zonal mean is returned. The default is not
set.
MEANLON: If set then the meridional mean is returned. The default is
not set.
SEASLEN: The length of the season for returning seasonal data. See
months_to_seasons.pro (SEASONLEN) for more information.
SEASON: If a value is given, then the function returns seasonal mean
or total data for the desired season of length SEASLEN. See
months_to_seasons.pro for more information.
TIME: A vector of time values for Data in units of years. Of length
NTIME. Also returns the vector of time values for the
returned masked (maybe seasonally averaged) Data, of length
NOUTTIME.

Outputs

Data: Returns the desired masked data set. Of size
NOUTLON*NOUTLAT*NOUTTIME. If MEANAREA or MEANLON is set then
NOUTLON=1, otherwise NOUTLON=NMASKLON. If MEANAREA or
MEANLAT is set then NOUTLAT=1, otherwise NOUTLAT=NMASKLAT. If
SEASON is set then NOUTTIME=NTIME/12, otherwise
NOUTTIME=NTIME.
AREAGOOD, FRACMASKAREA, LAT, LON, MEANDATA, TIME

Uses

dimension.pro
months_to_seasons.pro

Procedure

Example

Modification History

Written by: Daithi A. Stone (stoned@atm.ox.ac.uk), 2006-05-12
Modified: DAS, 2006-06-08 (added input quality checks)
Modified: DAS, 2006-08-16 (replaced MEADGLOBE keyword with
MEANAREA, FRACMEANGLOBEGOOD with FRACAREAGOOD,
NBASEGOOD with FRACBASEGOOD; changed default
FRACAREAGOOD and FRACINTERPOLATEGOOD to 0.5; added
AREAGOOD, COVERAGE, MEANLAT, MEANLON, FRACMASKAREA
keywords; allowed no input of Data and Mask; some
cleaning of code; allowed NTIME to be 1; changed
to skip interpolation if MASK and DATA longitude and
latitude coordinates are identical; removed
dependency on var_type.pro)
Modified: DAS, 2007-01-22 (fixed a bug in MEANDATA output)