Detect AR appearances from THR output¶
Definition of AR occurrence¶
An AR occurrence at a given time point is defined using these following rules:
- A connected region in the IVT anomaly field (\(I - \delta(I)\), computed in the section “The Top-hat by Reconstruction (THR) algorithm”) where its values is greater than 0.
- The centroid (weighted by IVT values of the grid cells) of the region is north of \(20 ^{\circ} N\) (or south of \(20 ^{\circ} S\) for the Southern Hemisphere), and south of \(80 ^{\circ} N\) (or north of \(80 ^{\circ} S\) for the Southern Hemisphere), i.e. we are only interested in mid-latitude systems.
- The region’s area has to be within \(50 - 1800 \times 10^4 km^2\).
- After the computation of this AR candidates axis (see Find the axis from detected AR) and the effective width (defined as area/length ratio), the length has to be \(\ge\, 1500 km\), and length/width ratio has to be \(\ge \,2\) if length is below \(2000\, km\).
Note
API is provided to control all these parameters.
Input data¶
These are the input data required for AR occurrence detection:
- u- and v- components of the integrated vapor fluxes (\(F_u\) and \(F_v\)).
- IVT (as \(\sqrt{F_u^2 + F_v^2}\)), see Compute IVT for more.
- The output from the THR process: the reconstruction component (\(\delta(I)\)) and the anomaly component (\(I - \delta(I)\)). See The Top-hat by Reconstruction (THR) algorithm for more.
Additional inputs:
- latitude, longitude and time axis. See Metadata for more.
- detection parameters, see below.
PARAM_DICT={
# kg/(m*s), define AR candidates as regions >= than this anomalous ivt.
'thres_low' : 1,
# km^2, drop AR candidates smaller than this area.
'min_area': 50*1e4,
# km^2, drop AR candidates larger than this area.
'max_area': 1800*1e4,
# float, min length/width ratio, applied only when length<min_length.
'min_LW': 2,
# degree, exclude systems whose centroids are lower than this latitude.
'min_lat': 20,
# degree, exclude systems whose centroids are higher than this latitude.
'max_lat': 80,
# km, ARs shorter than this length is treated as relaxed.
'min_length': 2000,
# km, ARs shorter than this length is discarded.
'min_length_hard': 1500,
# degree lat/lon, error when simplifying axis using rdp algorithm.
'rdp_thres': 2,
# grids. Remove small holes in AR contour.
'fill_radius': None,
# do peak partition or not, used to separate systems that are merged
# together with an outer contour.
'single_dome': False,
# max prominence/height ratio of a local peak. Only used when SINGLE_DOME=True
'max_ph_ratio': 0.6,
# minimal proportion of flux component in a direction to total flux to
# allow edge building in that direction
'edge_eps': 0.4
}
Usage in Python scripts¶
The following snippet shows the detection function calls:
from ipart.AR_detector import findARs
time_idx, labelsNV, anglesNV, crossfluxesNV, result_df = findARs(ivtNV.data,
ivtrecNV.data, ivtanoNV.data, quNV.data, qvNV.data, latax, lonax,
times=timeax, **PARAM_DICT)
where these input arguments are:
ivtNV
is aipart.utils.NCVAR
data object, which is a rudimentary wrapper object designed to achieve a tighter bound between data values and metadata. Same for the other variables with anNV
suffix.ivtNV.data
is the IVT data values innumpy.ndarray
format, with dimensions of(time, level, latitude, longitude)
or(time, latitude, longitude)
.ivtrecNV
is \(\delta(I)\), andivtanoNV
is \(I-\delta(I)\), see The Top-hat by Reconstruction (THR) algorithm for more details.quNV
: is \(F_u\), andqvNV
is \(F_v\).latax
: is an 1d array storing the latitude coordinates ofivtNV
and others.lonax
: is an 1d array storing the longitude coordinates ofivtNV
and others.timeax
is a list of pythondatetime
objects storing time stamps of the data inivtNV
and others.PARAM_DICT
is the parameter dictionary as defined above.
The return values are:
time_idx
is a list of indices of the time dimension when any AR is found.labelsNV
is aipart.utils.NCVAR
object, whosedata
attribute is an ndarray variable saving the numerical labels of all found ARs in each time step. It has shape of(time, lat, lon)
.anglesNV
is aipart.utils.NCVAR
object storing an ndarray variable saving the difference in the orientation of IVT vectors in all found ARs, wrt the AR axis.crossfluxesNV
is aipart.utils.NCVAR
object storing an ndarray variable saving the cross-sectional IVT flux, computed as the projection of IVT vectors onto the AR axis, using angles in angles.- The
result_df
return value is apandas.DataFrame
object saving in a table the various attributes of all detected ARs at this time point.
AR records DataFrame¶
The rows of ardf
are different AR records, the columns of ardf
are listed below:
id
: integer numeric id for this AR at this particular time point. ARs at different time points can share the same id, and an AR can be uniquely identified with the combination of time stamp + id.time
: time stamp in the YYYY-MM-DD HH:mm:ss format.contour_y
: list of floats, the y-coordinates (latitudes) of the AR contour in degrees North.contour_x
: list of floats, the x-coordinates (longitude) of the AR contour in degrees North.centroid_y
: float, latitude of the AR centroid, weighted by the IVT value.centroid_x
: float, longitude of the AR centroid, weighted by the IVT value.axis_y
: list of floats, latitudes of the AR axis.axis_x
: list of floats, longitude of the AR axis.axis_rdp_y
: list of floats, latitude of the simplified AR axis.axis_rdp_x
: list of floats, longitude of the simplified AR axis.area
: float, area of the AR in \(km^2\).length
: float, length of the AR in \(km\).width
: float, effective width in \(km\), as area/length.LW_ratio
: float, length/width ratio.strength
: float, spatially averaged IVT value within the AR region, in \(kg/(m \cdot s)\).strength_ano
: float, spatially averaged anomalous IVT value within the AR region, in \(kg/(m \cdot s)\).strength_std
: float, standard deviation of IVT within the AR region, in \(kg/(m \cdot s)\).max_strength
: float, maximum IVT value within the AR region, in \(kg/(m \cdot s)\).mean_angle
: float, spatially averaged angle between the IVT vector and the AR axis, in degrees.is_relaxed
: True or False, whether the AR is flagged as “relaxed”.qv_mean
: float, spatially averaged meridional integrated vapor flux, in \(kg/(m \cdot s)\).
Dedicated Python script¶
You can use the scripts/detect_ARs.py
or
scripts/detect_ARs_generator_version.py
script (check them out in the
github repo).
for AR detection process in
production. The former does the computation and returns all outpus in one go,
and the latter yields results at each time step separately, so the outputs can
be saved to disk rather than accumulating in RAM. Note that this process is
essentially time-independent, i.e. the computation of one time point does not
rely on another, therefore you can potentially parallelize this process to
achieve greater efficiency.
Example output¶
The resultant detected ARs can be visualized using the following snippet:
import matplotlib.pyplot as plt
from ipart.utils import plot
import cartopy.crs as ccrs
plot_vars=[slab,slabrec,slabano]
titles=['IVT', 'Reconstruction', 'THR']
iso=plot.Isofill(plot_vars,12,1,1,min_level=0,max_level=800)
figure=plt.figure(figsize=(12,10),dpi=100)
for jj in range(len(plot_vars)):
ax=figure.add_subplot(3,1,jj+1,projection=ccrs.PlateCarree())
pobj=plot.plot2(plot_vars[jj],iso,ax,
xarray=lonax, yarray=latax,
title='%s %s' %(timett_str, titles[jj]),
fix_aspect=False)
plot.plotAR(ardf,ax,lonax)
figure.show()
See also
One example output figure is shown below: