EXTRACT_REGION Name
EXTRACT_REGION Purpose
This function extracts regional data from a [longitude,latitude,time] data
file. Category
Geographical Calling Sequence
Result = extract_region( Data )
Inputs
Data: An array containing gridded data in a
[longitude,latitude,something] format. Of size N_LON_0*N_LAT_0*....
GIORGI, IPCC, LAT, LON, NOSHRINK, REGION
Keyword Parameters
COVERAGE: An N_LON*N_LAT*... array containing the fractional data
coverage of each cell in Data. Returns a modified array in which
values have been modified to reflect the fraction of the cells with
the requested region. Thus coverage fractions will be multiplied by 1
for cells entirely in the region, by between 0 and 1 for cells
straddling the border of the region, and by 0 for cells outside the
region (for which the corresponding elements of Data will have a NaN
value).
GIORGI: An obsolete input. Use REGION keyword instead.
IPCC: An obsolute input. Use REGION keyword instead.
LAT: A vector of length N_LAT_0 containing the latitude coordinates of
the latitude dimension in Data. Returns a vector of length N_LAT
containing the latitude coordinates of the regional data in the output
array Result.
LON: A vector of length N_LON_0 containing the longitude coordinates of
the longitude dimension in Data. Returns a vector of length N_LON
containing the longitude coordinates of the regional data in the
output array Result.
NAME: Returns a string containing the/a full name of the requested region.
NOSHRINK: If set, the data is returned on the original global grid with
all values outside the region(s) set to NaN. The default is to return
the data on a grid consisting of the minimum extracted box that
contains all of the region(s).
REGION: If a string is input then it contains the abbreviated name of a
region to request, as defined in ipcc_regions.pro. If a vector is
given, or a list of names separated by commas, then data from all
requested regions is included in the output. If it is a floating
point vector of length 4 then it contains the geographical boundaries
of the box defining the desired region, in the form
[ westernmost longitude, southernmost latitude, $
easternmost longitude, northernmost latitude ].
If a 4*N_REGION array is given then data from all N_REGION regions
will be returned.
If this keyword (and obsolete related inputs) are not given and
NOSHRINK is not set then Result will return the data on a grid
consisting of the minimum extracted box that contains all of the
non-NaN data.
Outputs
Result: Returns an array of size N_LON*N_LAT*... containing the requested
regional component of Data. If multiple box regions have been
requested, then the boundary will be larger than the regions with data
outside the regions replaced with NaNs.
COVERAGE, LAT, LON, NAME, REGION Uses
ipcc_regions.pro
var_type.pro
Procedure
This function extracts a sub-array from the input array.
Example
Create an array of global, 1x1 degree annual data.
data = randomn( seed, 360, 180, 100 )
lon = findgen( 360 ) + 0.5
lat = findgen( 180 ) - 90. + 0.5
Extract data from the region bordered between longitudes 10W and 20E and
latitudes 30N and 40N.
result = extract_region( data, region=[-10.,30,20,40], lon=lon, lat=lat )
This should return:
RESULT as a 30*10*100 floating point array
LON as findgen( 30 ) - 10. + 0.5
LAT as findgen( 10 ) + 30. + 0.5
Modification History
Written by: Daithi A. Stone (stoned@atm.ox.ac.uk), 2005-03-16
Modified: DAS, 2005-09-09 (Added GIORGI and NAME keywords; updated
documentation)
Modified: DAS, 2005-09-21 (Allowed negative longitudes in REGION)
Modified: DAS, 2006-01-21 (Switched from using giorgi_regions.pro to
ipcc_regions.pro; Added IPCC input keyword; Allowed definition of
multiple region boxes for selecting non-rectangular regions)
Modified: DAS, 2006-06-08 (Allowed inclusion of cells even if coverage
is only partial, instead of requiring full coverage)
Modified: DAS, 2006-07-26 (Allowed negative longitudes in LON; added
COVERAGE keyword)
Modified: DAS, 2006-12-05 (Added comma-separated list capability to
IPCC keyword)
Modified: DAS, 2008-03-19 (Absorbed IPCC keyword input into REGION
keyword input; updated code style)
Modified: DAS, 2008-04-07 (Changed spatial shrinking to the area
defined by the region borders rather than the area with data within
those borders)
Modified: DAS, 2008-05-15 (Switched to a less memory-intensive method
of copying the large data array)
Modified: DAS, 2009-04-07 (Altered to accept data with N_LON=1 and/or
N_LAT=1; removed assumptions about extra dimensions; allowed
COVERAGE to be an input too)
Modified: DAS, 2010-02-10 (Altered border restriction comparison
estimation, ie lt to le, to hopefully handle numerical precision
issues better; edited documentation formatting)
Modified: DAS, 2010-02-26 (Allowed no regions to be specified)
Modified: DAS, 2010-03-02 (Fixed bug with region flagging resulting
from 2010-02-26 modification)
Modified: DAS, 2010-03-09 (Fixed bug which removed gaps in latitude)