PROCESS_LONLATMONTH

Name

PROCESS_LONLATMONTH

Purpose

This procedure returns a processed version of the input lon-lat-month data
set. Processing includes lon-lat interpolation masking, taking anomalies,
and taking averages.

Calling Sequence

process_lonlatmonth, data

Inputs

Data: A array of data to be processed. Of dimensions N_LON*N_LAT*N_TIME.
Missing data should be denoted by NaN. Returns the processed data
array.
ANOMALY, DATA_MEAN, DESEASONALISE, FRAC_INTERPOLATE_THRESH,
FRAC_BASE_THRESH, FRAC_SEASON_THRESH, LAT, LEN_SEASON, LON, MASK_DATA,
MASK_LON, MASK_LAT, PERIOD_BASE, SEASON, TIME

Keyword Parameters

ANOMALY: If set then anomalies with respect to the PERIOD_BASE
climatology are returned. If set to 'absolute' then the absolute
anomalies are returned. If set to 'fractional' then the fractional
anomalies are returned. The default is not set (no anomalies).
COVERAGE: An optional input floating array containing the fractional data
coverage of each element in Data. Returns an altered array according
to interpolation and masking operations. Of same dimensions as Data.
DATA_MEAN: Returns an array of the temporal average of Data over the
PERIOD_BASE period. Of size N_LON_OUT*N_LAT_OUT. This is if
DATA_MEAN is set or if ANOMALY is set.
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.
FRAC_COVERAGE_THRESH: The minimum fraction of (weighted) data that must
be defined (i.e. not NaN) in order to proceed with an integration
command. If the criterion is not met then a NaN is returned from that
calculation. The default is 0.
FRAC_INTERPOLATE_THRESH: The threshold fraction of the area in a new
spatial cell with non-missing data in the old spatial cells being
interpolated required for the interpolation to be carried out (as
against being counted as missing data). The default is 0.
FRAC_BASE_THRESH: The fraction of time steps in the base period required
to have non-missing (non-NaN) values in order for the base value to be
calculated. If this criterion is not satisfied then a NaN is
recorded. The default is 0.
FRAC_SEASON_THRESH: The fraction of the season that needs non-missing
data in order to be averaged when seasonal averaging is selected. The
default is 0.
INTEGRATE: A string array containing integration instructions to run in
array_total.pro through the Instruct keyword. See array_total.pro for
further details. 'mean=1,2' gives the spatial average, 'total=1'
gives the zonal total, 'mean=2' gives the meridional average, 'mean=3'
gives the temporal average.
INTERPOLATE_TOTAL: If set then when interpolating to the MASK_LAT and/or
MASK_LON coordinates the area-weighted total of all values in the new
grid cells that are overlapping the area in the new grid cell is
taken. The default is to return the area-weighted average.
LAT: A vector of latitude values for Data. Of length N_LAT. Returns the
vector of latitude values for the returned processed Data, length
N_LAT_OUT.
LEN_SEASON: The length of the season for returning seasonal data. See
months_to_seasons.pro (SEASONLEN) for more information.
LON: A vector of longitude values for Data. Of length N_LON. Returns
the vector of longitude values for the returned processed Data, of
length N_LON_OUT.
MASK_DATA: A masking array of dimensions N_LON_MASK*N_LAT_MASK or
N_LON_MASK*N_LAT_MASK*N_TIME. Values are 1 (keep) or NaN (discard).
MASK_LAT: A vector of the latitude coordinates for the mask. Of length
N_LAT_MASK. If not given then MASK_LAT is assumed to equal LAT.
MASK_LON: A vector of the longitude coordinates for the mask. Of length
N_LON_MASK. If not given then MASK_LON is assumed to equal LON.
MEAN_AREA: If set then the spatial mean is returned. The default is not
set.
MEAN_LAT: If set then the zonal mean is returned. The default is not set.
MEAN_LON: If set then the meridional mean is returned. The default is
not set.
PERIOD_BASE: A vector of length two defining the climatological base
period. The first/second elements give the first/last year of the
period. The default value is the full period in TIME.
SEASON: If a value is given, then the function returns seasonal mean or
total data for the desired season of length LEN_SEASLON. See
months_to_seasons.pro for more information.
TIME: A vector of time values for Data. Of length N_TIME. Returns the
vector of time values for the returned processed Data, of length
N_TIME_OUT.
WEIGHT: An array size N_LON_OUT*N_LAT_OUT*N_TIME_OUT of weightings to use
when taking an average over one or more dimensions, as requested in
INTEGRATE or MEAN_*. Note this should not include the area weightings
for a polar grid, which are included automatically.

Outputs

Data
COVERAGE, DATA_MEAN, LAT, LON, TIME

Uses

add_dim.pro
array_total.pro
mask_lonlattime.pro
months_to_season.pro

Procedure

Example

Modification History

Written by: Daithi A. Stone (stoned@atm.ox.ac.uk), 2008-03-26, adapted
from mask_lonlatmonth.pro
Modified: DAS, 2008-04-14 (Added WEIGHT keyword; added default base
period to averaging section; added NGOOD=1 to months_to_season.pro
call for time)
Modified: DAS, 2009-04-07 (Corrected bug to allow anomaly calculation of
one-dimensional data)
Modified: DAS, 2011-03-30 (Fixed bug in recording lon and lat from
mask_lonlattime.pro when COVERAGE is undefined; modified formating;
added description for COVERAGE)