swirlspy.qpe package¶
Submodules¶
swirlspy.qpe._adjustText module¶

swirlspy.qpe._adjustText.
adjust_text
(texts, x=None, y=None, add_objects=None, ax=None, expand_text=(1.05, 1.2), expand_points=(1.05, 1.2), expand_objects=(1.05, 1.2), expand_align=(1.05, 1.2), autoalign='xy', va='center', ha='center', force_text=(0.1, 0.25), force_points=(0.2, 0.5), force_objects=(0.1, 0.25), lim=500, precision=0.01, only_move={'objects': 'xy', 'points': 'xy', 'text': 'xy'}, avoid_text=True, avoid_points=True, avoid_self=True, save_steps=False, save_prefix='', save_format='png', add_step_numbers=True, on_basemap=False, *args, **kwargs)¶ Iteratively adjusts the locations of texts.
Call adjust_text the very last, after all plotting (especially anything that can change the axes limits) has been done. This is because to move texts the function needs to use the dimensions of the axes, and without knowing the final size of the plots the results will be completely nonsensical, or suboptimal.
First moves all texts that are outside the axes limits inside. Then in each iteration moves all texts away from each other and from points. In the end hides texts and substitutes them with annotations to link them to the respective points.
Parameters: texts (list) – A list of
matplotlib.text.Text
objects to adjust.Other Parameters:  x (array_like) – xcoordinates of points to repel from; if not provided only uses text coordinates.
 y (array_like) – ycoordinates of points to repel from; if not provided only uses text coordinates
 add_objects (list or PathCollection) – a list of additional matplotlib objects to avoid; they must have a .get_window_extent() method; alternatively, a PathCollection or a list of Bbox objects.
 ax (matplotlib axe, default is current axe (plt.gca())) – axe object with the plot
 expand_text (array_like, default (1.05, 1.2)) – a tuple/list/… with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from each other.
 expand_points (array_like, default (1.05, 1.2)) – a tuple/list/… with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from points.
 expand_objects (array_like, default (1.05, 1.2)) – a tuple/list/… with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from other objects.
 expand_align (array_like, default (1.05, 1.2)) – a tuple/list/… with 2 multipliers (x, y) by which to expand the bounding box of texts when autoaligning texts.
 autoalign (str or boolean {‘xy’, ‘x’, ‘y’, True, False}, default ‘xy’) – Direction in wich the best alignement will be determined
 ‘xy’ or True, best alignment of all texts determined in all directions automatically before running the iterative adjustment (overriding va and ha),
 ‘x’, will only align horizontally,
 ‘y’, will only align vertically,
 False, do nothing (i.e. preserve va and ha)
 va (str, default ‘center’) – vertical alignment of texts
 ha (str, default ‘center’) – horizontal alignment of texts,
 force_text (tuple, default (0.1, 0.25)) – the repel force from texts is multiplied by this value
 force_points (tuple, default (0.2, 0.5)) – the repel force from points is multiplied by this value
 force_objects (float, default (0.1, 0.25)) – same as other forces, but for repelling additional objects
 lim (int, default 500) – limit of number of iterations
 precision (float, default 0.01) – iterate until the sum of all overlaps along both x and y are less than this amount, as a fraction of the total widths and heights, respectively. May need to increase for complicated situations.
 only_move (dict, default {‘points’:’xy’, ‘text’:’xy’, ‘objects’:’xy’}) – a dict to restrict movement of texts to only certain axes for certain types of overlaps. Valid keys are ‘points’, ‘text’, and ‘objects’. Valid values are ‘’, ‘x’, ‘y’, and ‘xy’. For example, only_move={‘points’:’y’, ‘text’:’xy’, ‘objects’:’xy’} forbids moving texts along the x axis due to overlaps with points.
 avoid_text (bool, default True) – whether to repel texts from each other.
 avoid_points (bool, default True) – whether to repel texts from points. Can be helpful to switch off in extremely crowded plots.
 avoid_self (bool, default True) – whether to repel texts from its original positions.
 save_steps (bool, default False) – whether to save intermediate steps as images.
 save_prefix (str, default ‘’) – if save_steps is True, a path and/or prefix to the saved steps.
 save_format (str, default ‘png’) – if save_steps is True, a format to save the steps into.
 add_step_numbers (bool, default True) – if save_steps is True, whether to add step numbers as titles to the images of saving steps.
 on_basemap (bool, default False) – whether your plot uses the basemap library, stops labels going over the edge of the map.
 args and kwargs – any arguments will be fed into obj:ax.annotate after all the optimization is done just for plotting the connecting arrows if required.
Returns: Number of iteration
Return type: int

swirlspy.qpe._adjustText.
float_to_tuple
(a)¶

swirlspy.qpe._adjustText.
get_bboxes
(objs, r, expand, ax)¶

swirlspy.qpe._adjustText.
get_bboxes_pathcollection
(sc, ax)¶ Function to return a list of bounding boxes in data coordinates for a scatter plot Thank you to ImportanceOfBeingErnest https://stackoverflow.com/a/55007838/1304161

swirlspy.qpe._adjustText.
get_midpoint
(bbox)¶

swirlspy.qpe._adjustText.
get_points_inside_bbox
(x, y, bbox)¶ Return the indices of points inside the given bbox.

swirlspy.qpe._adjustText.
get_renderer
(fig)¶

swirlspy.qpe._adjustText.
get_text_position
(text, ax=None)¶

swirlspy.qpe._adjustText.
move_texts
(texts, delta_x, delta_y, bboxes=None, renderer=None, ax=None)¶

swirlspy.qpe._adjustText.
optimally_align_text
(x, y, texts, expand=(1.0, 1.0), add_bboxes=[], renderer=None, ax=None, direction='xy')¶ For all text objects find alignment that causes the least overlap with points and other texts and apply it

swirlspy.qpe._adjustText.
overlap_bbox_and_point
(bbox, xp, yp)¶ Given a bbox that contains a given point, return the (x, y) displacement necessary to make the bbox not overlap the point.

swirlspy.qpe._adjustText.
repel_text
(texts, renderer=None, ax=None, expand=(1.2, 1.2), only_use_max_min=False, move=False)¶ Repel texts from each other while expanding their bounding boxes by expand (x, y), e.g. (1.2, 1.2) would multiply width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.

swirlspy.qpe._adjustText.
repel_text_from_axes
(texts, ax=None, bboxes=None, renderer=None, expand=None)¶

swirlspy.qpe._adjustText.
repel_text_from_bboxes
(add_bboxes, texts, renderer=None, ax=None, expand=(1.2, 1.2), only_use_max_min=False, move=False)¶ Repel texts from other objects’ bboxes while expanding their (texts’) bounding boxes by expand (x, y), e.g. (1.2, 1.2) would multiply width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.

swirlspy.qpe._adjustText.
repel_text_from_points
(x, y, texts, renderer=None, ax=None, expand=(1.2, 1.2), move=False)¶ Repel texts from all points specified by x and y while expanding their (texts’!) bounding boxes by expandby (x, y), e.g. (1.2, 1.2) would multiply both width and height by 1.2. Requires a renderer to get the actual sizes of the text, and to that end either one needs to be directly provided, or the axes have to be specified, and the renderer is then got from the axes object.
swirlspy.qpe.cal_zr module¶

swirlspy.qpe.cal_zr.
cal_zr
(reflectivity_rf, duration)¶ Calibrate the Z=aR^b relationship through deriving (a,b) by linear regression, also compute the correlation of 2 time series of reflectivity and rainfall
Parameters:  reflectivity_rf (array of tuples (reflectivity, rainfall_amount)) – reflectivity in dBZ, rainfall amount in mm
 duration (integer) – duration of rainfall accumulation in minutes, default to 60
Returns:  a (float)
 b (float) – a,b value in the Z=aR^b relationship
 correlation (float) – correlation of 2 time series of reflectivity and rainfall
swirlspy.qpe.rfmap module¶

swirlspy.qpe.rfmap.
comp_qpe
(area_def, rg_object=None, rg_interp=None, rad_rf=None, sat=None, rg_radius=10000, radar_radius=256000, sat_radius=None, r_sigma_ratio=2.5, max_truth={'radar': 0.1, 'rg': 1.0, 'sat': 0.01})¶ Calculate composite QPE from Rain Gauge, Radar and Satellite. The dimensions and coordinates of the input xarray.DataArrays must be the same. All data must also be in the same coordinate system.
Parameters:  area_def (pyresample.geometry.AreaDefinition) – AreaDefinition of the grid.
 rg_object (Rain) – Rain object containing raingauge data. The x, y values in rg_object must be in the same coordinate system as the other data.
 rg_interp (xarray.DataArray) – Contains rainfall values from rain gauge interpolated to userdefined grid or the same grid as rad_rf and/or sat.
 rad_rf (xarray.DataArray) – Contains rainfall derived from radar reflectivity.
 sat (xarray.DataArray) – Contains rainfall derived from satellite in userdefined grid or the same grid as rad_rf and/or rg_interpolate.
 rg_radius (int) – The radius of influence of raingauge. The “truthness” of a raingauge decreases normally with distance from the raingauge. Distance should be given in the units of the userdefined projection. Defaults to 10000m.
 radar_radius (int) – The radius of influence of radar. The “truthness” decreases normally with distance from the station. Defaults to 256000m.
 sat_radius (int) – The radius of influence of satellite.
 r_sigma_ratio (float) – The ratio between radius of influence and standard deviation. Defaults to 2.5.
 max_truth (dict of floats) – The maximum ‘truthness’ of raingauge, radar and satellite respectively. Defaults to {‘rg’: 1., ‘radar’: 0.1, ‘sat’: 0.01}.
Returns: wrf – The composite rainfall calculated from Rain Gauge, Radar and Satellite derived rainfall.
Return type: xarray.DataArray

swirlspy.qpe.rfmap.
overlay_pil
(filename_rfcontour, filename_overlay, dimension, position)¶ Overlay rainfall map with frame. then save as figure.
Parameters:  filename_rfcontour (string) – Filename of rainfall contour, returned from rfmap.savefig.
 filename_overlay (string) – Filename of overlaying frame/ basemap.
 dimension (tuples (width, height)) – dimension of the desired rainfall contour. Should be customised to fit the size overlaying frame/ basemap.
 position (tuples (x,y)) – position of the overlaying frame/ basemap, where the resized rainfall contour will be pasted.

swirlspy.qpe.rfmap.
rg_interpolate
(rg_object, area_def, interp_type, coord_label=['x', 'y'], gamma_value=2, minimum_neighbors=3, kappa_star=0.01, search_radius=None, rbf_func='multiquadric', rbf_smooth=0, kernel=None, alpha=1e10, n_restarts_optimizer=10, normalize_y=False)¶ Interpolate the rainfall on an area, based on metpy.interpolate.interpolate_to_points.
Parameters:  rg_object (Rain) – Rain object.
 area_def (pyresample.geometry.AreaDefinition) – AreaDefinition of the target grid.
 interp_type (str) –
 Type of interpolation to be used. Available options include:
 ”linear”, “nearest”, “cubic”, or “rbf” from scipy.interpolate.
 ”natural_neighbor”, “barnes”, or “cressman” from metpy.interpolate.
 ”ordinary_kriging” from sklearn.gaussian_processes.GaussianProcessRegressor.
 coord_label (list of strings) – Coordinate labels. Defaults to [‘x’, ‘y’].
 gamma_value (float, optional, Barnes) – Adjustable smoothing parameter for the barnes interpolation. Default 2.0.
 minimum_neighbors (int, optional, Barnes) – Minimum number of neighbors needed to perform barnes or cressman interpolation for a point. Default is 3. Adjustable.
 kappa_star (float, optional, Barnes) – Response parameter for barnes interpolation, specified nondimensionally in terms of the Nyquist. Default 0.01.
 search_radius (float, optional, Barnes) – A search radius to use for the barnes and cressman interpolation values. If search_radius is not specified, it will default to the average spacing of observations.
 rbf_func (str, optional, RBF) – Specifies which function to use for Rbf interpolation. Options include: ‘multiquadric’, ‘inverse’, ‘gaussian’, ‘linear’, ‘cubic’, ‘quintic’, and ‘thin_plate’. Default to ‘multiquadric’.
 rbf_smooth (float, optional, RBF) – Smoothing value applied to rbf interpolation. Higher values result in more smoothing. Defaults to 0.
 kernel (sklearn.gaussian_process.kernels, optional, OK) – The kernel specifying the covariance function of the GP for ordinary kriging. If None is passed, the kernel “1.0 * RBF(1.0)” is used as default. Note that the kernel’s hyperparameters are optimized during fitting. Defaults to None.
 alpha (float or arraylike, optional, OK) – For ordinary kriging. Value added to the diagonal of the kernel matrix during fitting. Larger values correspond to increased noise level in the observations. This can also prevent a potential numerical issue during fitting, by ensuring that the calculated values form a positive definite matrix. If an array is passed, it must have the same number of entries as the data used for fitting and is used as datapointdependent noise level. Note that this is equivalent to adding a WhiteKernel with c=alpha. Allowing to specify the noise level directly as a parameter is mainly for convenience and for consistency with Ridge. Defaults to 1e10.
 n_restarts_optimizer (int, optional, OK) – For ordinary kriging. The number of restarts of the optimizer for finding the kernel’s parameters which maximize the logmarginal likelihood. The first run of the optimizer is performed from the kernel’s initial parameters, the remaining ones (if any) from thetas sampled loguniform randomly from the space of allowed thetavalues. If greater than 0, all bounds must be finite. Note that n_restarts_optimizer == 0 implies that one run is performed. Defaults to 10.
 normalize_y (bool, optional, OK) – For ordinary kriging. Whether the target values y are normalized, i.e., the mean of the observed target values become zero. This parameter should be set to True if the target values’ mean is expected to differ considerable from zero. When enabled, the normalization effectively modifies the GP’s prior based on the data, which contradicts the likelihood principle; normalization is thus disabled per default. Defaults to False.
Returns: interpolated_rf – Interpolated values in 2D.
Return type: xarray.DataArray
Notes
Default values set in ‘minimum_neighbors’, ‘gamma’ and ‘kappa_star’, for Barnes interpolation and ‘kernel’, ‘alpha’, ‘n_restarts_optimizer’ and ‘normalize_y’ for Ordinary Kriging for shows best effect for Hong Kong rainfall map. May not be suitable for other countries / regions. Try other values to get the best effect.

swirlspy.qpe.rfmap.
show_raingauge
(rg_object, ax, show_value=True, color='k', zorder=10, fontsize=12, markersize=12, adjust_labels=False, force_points=0.2, force_text=0.2, expand_points=(1, 1), expand_text=(1, 1), arrowprops={'arrowstyle': '>', 'color': 'black', 'lw': 2})¶ Generates a scatter plot showing location and rainfall of raingauges.
Parameters:  rg_object (Rain) – Rain object.
 ax (matplotlib.axes.Axes or cartopy.mpl.geoaxes.GeoAxes) – The plot axes.
 show_value (bool) – Show rainfall values of raingauges. Defaults to True.
 color (str) – Color of text and markers. Defaults to ‘k’.
 fontsize (int) – Font size. Defaults to 12.
 markersize (int) – Marker size. Defaults to 12.
 adjust_labels (bool) – Choose whether further label adjustments are required. Defaults to False.
 force_points (float) – Repel force from points is multiplied by this value. Defaults to 0.2.
 force_text (float) – Repel force from text is multiplied by this value. Defaults to 0.2.
 expand_text (array_like) – a tuple/list/other sequence data type with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from each other. Defaults to (1, 1).
 expand_points (array_like) – a tuple/list/other sequence data type with 2 multipliers (x, y) by which to expand the bounding box of texts when repelling them from points. Defaults to (1, 1).
 arrowprops (dict) – Customize labelling arrows. Defaults to arrowprops=dict(arrowstyle=’‘, color=’black’, lw=0.5).
swirlspy.qpe.utils module¶

swirlspy.qpe.utils.
acc
(rf, ts, acc_period)¶ Calculate the past rainfall by accumulating rainfall amount. For example: to calculate the past 60 minute rainfall amount at 15:00:
 Create past 6min rainfall amount at 14:06, 14:12 … by rfn().
 Concatenate all xarray’s returned by rfn().
 Call acc(rf, pandas.Timestamp(‘15:00:00’), pandas.Timedelta(60, ‘m’)).
Parameters:  rf (xarray.DataArray) – Rainfall amount at various times.
 ts (pandas.Timestamp) – End time of the rainfall accumulation period.
 acc_period (pandas.Timedelta) – Rainfall accumulation period.
Returns: acc_rf – accumulated rainfall amount over the designated period
Return type: xarray.DataArray

swirlspy.qpe.utils.
dbz2rr
(dbz, a=200.0, b=1.6)¶ Convert reflectivity to rainfall rate by the ZR relationship. Default a & b are MarshallPlalmer. You may wish to refer to the ZR relationship page for more information on the choice of a & b.
Parameters:  dbz (xarray.DataArray) – xarray containing the reflectivity xarray in dBZ to convert
 a (float) – a in Z = aR^b relationship
 b (float) – b in Z = aR^b relationship
Returns: rainrate – xarray containing the rainfall rate converted by the Z=aR^b relationship
Return type: xarray.DataArray

swirlspy.qpe.utils.
locate_file
(directory, pattern)¶ Locate a file under path that contains the timestamp string. Certain radar systems generates radar output files with names other than fixed prefix/suffix and timestamp, e.g. TMS180822171807.RAWULST. This utility helps locate the file. If more than one file is located, a list of strings is returned.
Parameters:  directory (str) – Directory in which the file is located
 pattern (str) – Pattern in the filename, typically a timestamp
Returns: path – Path to the located file(s).
Return type: str or list of strings

swirlspy.qpe.utils.
multiple_acc
(rainfalls, start_time, end_time, times=Timedelta('0 days 00:30:00'), acc_period=Timedelta('0 days 01:00:00'))¶ Obtain accumulated rainfall over a time period from a start_time to an end_time at certain times. For example, to generate past hourly rainfall every 30 minutes from start time 14:00 to end time 17:00:
 Create past 6min rainfall amount at 14:06, 14:12 … 17:00 by rfn().
 Concatenate all xarray’s returned by rfn().
 Call acc(rf, timestamp(‘14:00:00’), timestamp(‘17:00:00’), times=timedelta(30, ‘m’), acc_period=timedelta(1, ‘h’)).
Parameters:  rainfalls (xarray.DataArray) – Contains observed and/or forecasted rainfall every n minutes, n being the interval (in minutes) between two timestamps.
 start_time (pandas.Timestamp) – The start time of the forecast.
 end_time (pandas.Timestamp) – The last forecasted timestep.
 times (pandas.Timedelta) – Times at which accumulated rainfall are to be calculated. Defaults to every 30 minutes.
 acc_period (pandas.Timedelta) – Rainfall accumulation period. Defaults to 1 hour.
Returns: macc_rf – Contains accumulated rainfall over acc_period every times.
Return type: xarray,DataArray

swirlspy.qpe.utils.
rr2rf
(rainrate, scan_duration=6, time_shift=0, drift=0)¶ Convert from radar rainfall rate to accumulated rainfall.
Parameters:  rainrate (xarray.DataArray) – rainfall rate, likely outputs from dbz2rr()
 scan_duration (int) – number of minutes a radar scan represents, typically 5, 6 or 10
 time_shift (timedelta) – temporal shift to account for time required for rain droplets to fall to the ground, and also in case radar data are labelled at the start of the scan while rainfall are labelled at the end (e.g. past 60minute rainfall)
 drift (dict) – spatial displacement to account for rain droplets advected by wind, unit same as that of the xarray
Returns: rf – rainfall amount accumulated during the past n minutes
Return type: xarray.DataArray

swirlspy.qpe.utils.
temporal_interp
(da, start_time, end_time, intvl=Timedelta('0 days 00:06:00'), interp_type='linear')¶ Interpolate xarray data values such as rainrates along the time dimension.
Parameters:  da (xarray.DataArray) – Contains data values to be temporally interpolated.
 start_time (pandas.Timestamp) – User defined starttime.
 end_time (pandas.Timestamp) – The userdefined end time of the forecasted period.
 intvl (pandas.Timedelta) – The time interval between interpolated data. Defaults to 6 minutes.
 interp_type (str) – The interpolation type for interpolating data in the time axis. Options include: ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, ‘cubic’, ‘previous’, ‘next’. Interpolation based on scipy.interpolate.interp1d. Default is linear.
Returns: interp_da – Contains data interpolated along the time axis.
Return type: xarray.DataArray

swirlspy.qpe.utils.
timestamps_ending
(end_time, duration=Timedelta('0 days 01:00:00'), interval=Timedelta('0 days 00:06:00'), exclude_end=True, format='%y%m%d%H%M')¶ Generate a list of timestamp strings for the duration ending at time
Parameters:  end_time (datetime64[ns]) – time at the end of the period (excluding end).
 duration (timedelta64) – duration of the accumulation.
 interval (timedelta64) – intervals between each timestamp.
 exclude_end (Boolean) – If true, no timestamp for the end time.
 format (str) – format of the datetime string, referencing time.strftime().
Returns: timestamps – list of timestamps
Return type: a tuple of strings

swirlspy.qpe.utils.
timestamps_period
(start_time, end_time, interval, exclude_end=True, format='%y%m%d%H%M')¶ Generate a list of timestamp strings during the userdefined period.
Parameters:  start_time (pandas.Timestamp) – start time of the accumulated rainfall.
 end_time (pandas.Timestamp) – end time of the accumulated rainfall.
 interval (pandas.Timedelta) – time intervals between each xarray object.
 format (str) – format of the datetime string, referencing time.strftime().
Returns: timestamps – list of filenames
Return type: a tuple of strings