swirlspy.qpe package

Submodules

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

class swirlspy.qpe.rfmap.RainGauge(start_time, end_time, gauge_lat, gauge_lon, rainfall)

Bases: object

A class for raingauge object. “Raingauge object” can be just 1 raingauge, or a network of raingauges, depending on how many raingauge data is inputted. Each raingauge object has the following attributes.

start_time

Starting time when raingauge(s) start accumulating rainfall.

Type:str
end_time

Ending time when raingauge(s) stop accumulating rainfall.

Type:str
gauge_lat

Latitude of raingauge(s).

Type:numpy.1darray
gauge_lon

Longitude of raingauge(s).

Type:numpy.1darray
rainfall

Accumulated rainfall value of each raingauge(s), within the period between start_time and end_time.

Type:numpy.1darray
rg_number

Number of raingauge(s).

Type:int
data

An array of tuple(s), where each tuple contains (gauge_lat, gauge_lon, rainfall).

Type:numpy.1darray
swirlspy.qpe.rfmap.barnes_interpolation(m_lllon, m_lllat, m_urlon, m_urlat, m_rg_lon, m_rg_lat, rg_value, resolution, interp_type='barnes', gamma_value=2, minimum_neighbors=3, kappa_star=0.01)

Interpolate rainfall of an area from raingauge values, by Metpy Barnes interpolation.

Parameters:
  • m_lllon (float (Basemap coordinate)) – x-coordinate of the lower left corner in the interpolated area.
  • m_lllat (float (Basemap coordinate)) – y-coordinate of the lower left corner in the interpolated area.
  • m_urlon (float (Basemap coordinate)) – x-coordinate of the upper right corner in the interpolated area.
  • m_urlat (float (Basemap coordinate)) – y-coordinate of the upper right corner in the interpolated area.
  • m_rg_lon (numpy.1darray (Basemap coordinates)) – x-coordinate of raingauges in the interpolated area.
  • m_rg_lat (numpy.1darray (Basemap coordinates)) – y-coordinate of raingauges in the interpolated area.
  • rg_value (numpy.1darray) – Raingauge values.
  • resolution (int) – Resolution of the interpolated contour/grid. Default 1000. Adjustable.
  • interp_type (str (optional)) – What type of interpolation to use. Available options include: 1) “linear”, “nearest”, “cubic”, or “rbf” from scipy.interpolate. 2) “natural_neighbor”, “barnes”, or “cressman” from metpy.interpolate Default “barnes”.
  • gamma_value (float (optional)) – Adjustable smoothing parameter for the barnes interpolation. Default 2.0. Adjustable.
  • minimum_neighbors (int (optional)) – Minimum number of neighbors needed to perform barnes or cressman interpolation for a point. Default is 3. Adjustable.
  • kappa_star (float (optional)) – Response parameter for barnes interpolation, specified nondimensionally in terms of the Nyquist. Default 0.01. Adjustable.
Returns:

  • barnes_gx (2D array (Basemap coordinates)) – Meshgrid for the Barnes interpolation in the x dimension.

  • barnes_gy (2D array (Basemap coordinates)) – Meshgrid for the Barnes interpolation in the y dimension. interpolated_rf: 2D array (Default dimension: 1000*1000)

    Interpolated rainfall of the area.

Notes

Default values set in ‘minimum_neighbors’, ‘gamma_value’ and ‘kappa_star’, 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.create_colormesh(coastline, show_value, lllon, urlon, lllat, urlat, m_rg_lon, m_rg_lat, rg_value, gx, gy, interpolated_rf, levels=[0, 0.5, 2, 5, 10, 20, 30, 40, 50, 70, 100, 150, 200, 300, 400, 500, 600, 700], cmap=<matplotlib.colors.ListedColormap object>)

Create a color plot, of the interpolated rainfall contour.

Parameters:
  • coastline (bool) – ‘True’ to show coastline from cartopy basemap. ‘False’ to hide coastline.
  • show_value (bool) – ‘True’ to show raingauge values.
  • lllon (float) – Longitude of lower left corner of interested area (Rainfall interpolation).
  • urlon (float) – Longitude of upper right corner of interested area (Rainfall interpolation).
  • lllat (float) – Latitude of lower left corner of interested area (Rainfall interpolation).
  • urlat (float) – Latitude of upper right corner of interested area (Rainfall interpolation).
  • m_rg_lon (numpy.1darray (Basemap coordinates)) – x-coordinate of raingauges in the interpolated area.
  • m_rg_lat (numpy.1darray (Basemap coordinates)) – y-coordinate of raingauges in the interpolated area.
  • rg_value (numpy.1darray) – Raingauge values.
  • gx (2D array) – “rbf_gx” returned from rfmap.rbf_interpolation or “barnes_gx” returned from rfmap.barnes_interpolation.
  • gy (2D array) – “rbf_gx” returned from rfmap.rbf_interpolation or “barnes_gx” returned from rfmap.barnes_interpolation.
  • interpolated_rf (2D array) – “interpolated_rf” returned from rfmap.rbf_interpolation or rfmap.barnes_interpolation.
  • (Optional) (cmap) – Rainfall intervals/scale. Adjustable.
  • (Optional) – Color between 2 intervals. Adjustable.
swirlspy.qpe.rfmap.epsilon(urlon, lllon, resolution, rg_number)

Calculate epsilon value for RBF interpolation.

Parameters:
  • urlon (float) – Longitude of upper right hand corner.
  • lllon (float) – Longitude of lower right hand corner.
  • RESOULTION (int) – Resolution of the interpolated contour.
  • rg_number (int) – Number of raingauges.
Returns:

epsilon – Adjustable constant for gaussian or multiquadrics functions.

Epsilon = (prod(max(x’)-min(x’))/nXCount)^(1/nXDim);

ie, take the volume of the bounding cube, divide by the number of points and take the n-th root (n = number of dimensions).
Return type:

float
swirlspy.qpe.rfmap.overlay_pil(filename_rfcontour, filename_overlay, dimension, position)

Overlay rainfall contour with a frame/ basemap on it, then save it as a figure.

File name saved as [filename_rfcontour]_OVERLAYED.png.

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.rbf_interpolation(m_rg_lon, m_rg_lat, rbf_gx, rbf_gy, rg_value, epsilon_value)

Interpolate rainfall of an area from raingauge values (putting interpolated rainfall on meshgrid created from rfmap.rbf_create_basemap), by Scipy radial basis function (RBF) interpolation.

Parameters:
  • m_rg_lon (numpy.1darray) – x coordinates of raingauge location in basemap, converted from its longitude.
  • m_rg_lat (numpy.1darray) – y coordinates of raingauge location in basemap, converted from its longitude.
  • rbf_gx (2D array (Basemap coordinates)) – Meshgrid for the RBF interpolation in the x dimension.
  • rbf_gy (2D array (Basemap coordinates)) – Meshgrid for the RBF interpolation in the y dimension.
  • rg_value (numpy.1darray) – Raingauge values.
  • epsilon (float (Default=22.0)) –

    Adjustable constant for gaussian or multiquadrics functions.

    Epsilon = (prod(max(x’)-min(x’))/nXCount)^(1/nXDim);
    ie, take the volume of the bounding cube, divide by the number of points and take the n-th root (n = number of dimensions).
Returns:

interpolated_rf – Interpolated rainfall of the area.
Return type:

2D array (Default dimension: 1000*1000)
swirlspy.qpe.rfmap.read_file(file, NAN=3276.7)

Create a raingauge object from a text file. ‘Raingauge object’ is like a network of raingauges. How many raingauges there are in this object depends on how many there are in your input text file.

Format of the text file is as follows:
  • First line: “start_time end_time” (in YYYYMMDDhhmm).
  • Starting from second line, each line has 3 columns.
  • First column: Latitude of raingauges.
  • Second column: Longitude of raingauges.
  • Third column: Accumulated rainfall value.
Parameters:
  • file (str) – Filename of text file to be read.
  • NAN (list of floats (Default 3276.7)) – Rainfall values to be ignored while reading text file, usually the number to indicate raingauges under maintenance.
Returns:

Raingauge_object
Return type:

RainGauge
swirlspy.qpe.rfmap.save_fig(mode, start_time, end_time, lllon, urlon, lllat, urlat, m_rg_lon, m_rg_lat, rg_value, gx, gy, interpolated_rf, coastline, show_value)

Save it as a figure. File name saved as [start_time+”_”+end_time+”.png”].

Parameters:
  • mode (str) – Mode of interpolation (‘rbf’ or “barnes”). Used as filename of output figure.
  • start_time (string) – Starting time of rainfall period.
  • end_time (string) – Ending time of rainfall period.
  • lllon (float) – Longitude of lower left corner of interested area (Rainfall interpolation).
  • urlon (float) – Longitude of upper right corner of interested area (Rainfall interpolation).
  • lllat (float) – Latitude of lower left corner of interested area (Rainfall interpolation).
  • urlat (float) – Latitude of upper right corner of interested area (Rainfall interpolation).
  • m_rg_lon (numpy.1darray (Basemap coordinates)) – x-coordinate of raingauges in the interpolated area.
  • m_rg_lat (numpy.1darray (Basemap coordinates)) – y-coordinate of raingauges in the interpolated area.
  • rg_value (numpy.1darray) – Raingauge values.
  • gx (2D array) – “rbf_gx” returned from rfmap.rbf_interpolation or “barnes_gx” returned from rfmap.barnes_interpolation.
  • gy (2D array) – “rbf_gx” returned from rfmap.rbf_interpolation or “barnes_gx” returned from rfmap.barnes_interpolation.
  • interpolated_rf (2D array) – “interpolated_rf” returned from rfmap.rbf_interpolation or rfmap.barnes_interpolation.
  • coastline (bool) – ‘True’ to show coastline from cartopy basemap. ‘False’ to hide coastline.
  • show_value (bool) – ‘True’ to show raingauge values.
swirlspy.qpe.rfmap.show_rg_values_on_plot(m_rg_lon, m_rg_lat, rg_value, lllon, urlon, lllat, urlat)

Show all raingauge values on figure.

Parameters:
  • m_rg_lon (numpy.1darray (Basemap coordinates)) – x-coordinate of raingauges in the interpolated area.
  • m_rg_lat (numpy.1darray (Basemap coordinates)) – y-coordinate of raingauges in the interpolated area.
  • rg_value (numpy.1darray) – Raingauge values.
  • lllon (float) – Longitude of lower left corner of interested area (Rainfall interpolation).
  • urlon (float) – Longitude of upper right corner of interested area (Rainfall interpolation).
  • lllat (float) – Latitude of lower left corner of interested area (Rainfall interpolation).
  • urlat (float) – Latitude of upper right corner of interested area (Rainfall interpolation).
swirlspy.qpe.rfmap.to_map_coordinates(lllon, urlon, lllat, urlat, rg_lon, rg_lat, resolution)

Create a basemap with boundary defined by input latitude/ longitude, then convert raingauges’ lat/lon and boundaries lat/lon to map coordinates of this created basemap.

Parameters:
  • lllon (float) – Longitude of lower left corner of interested area for rainfall interpolation.
  • lllat (float) – Latitude of lower left corner of interested area for rainfall interpolation.
  • urlon (float) – Longitude of upper right corner of interested area for rainfall interpolation.
  • urlat (float) – Latitude of upper right corner of interested area for rainfall interpolation.
  • rg_lon (numpy.1darray) – Longitude of raingauges.
  • rg_lat (numpy.1darray) – Latitude of raingauges.
  • resolution (int) – Resolution of the interpolated contour/grid. Suggest 1000. Adjustable.
Returns:

  • m_lllon (float (Basemap coordinate)) – x-coordinate of the lower left corner in the interpolated area.
  • m_lllat (float (Basemap coordinate)) – y-coordinate of the lower left corner in the interpolated area.
  • m_urlon (float (Basemap coordinate)) – x-coordinate of the upper right corner in the interpolated area.
  • m_urlat (float (Basemap coordinate)) – y-coordinate of the upper right corner in the interpolated area.
  • m_rg_lon (numpy.1darray (Basemap coordinates)) – x coordinates of raingauge location in basemap, converted from its longitude.
  • m_rg_lat (numpy.1darray (Basemap coordinates)) – y coordinates of raingauge location in basemap, converted from its longitude.
  • rbf_gx (2D array (Basemap coordinates)(Default dimension: 1000*1000)) – Meshgrid for the RBF interpolation in the x dimension.
  • rbf_gy (2D array (Basemap coordinates)(Default dimension: 1000*1000)) – Meshgrid for the RBF interpolation in the y dimension.

Notes

rbf_gx and rbf_gy returned by this function should only be used for RBF interpolation.

For barnes interpolation, do not use rbf_gx and rbf_gy from here.

Use its own meshgrid from rfmap.barnes_interpolation.

swirlspy.qpe.utils module

swirlspy.qpe.utils.acc(rf, ts, te, i)

Calculate the past rainfall by accumulating rainfall amount For example: to calculate the past 60 minute rainfall amount at 15:00 1. Create past 6-min rainfall amount at 14:06, 14:12 … by rfn() 2. Concatenate all xarray’s returned by rfn() 3. Call acc(rf, datetime64(‘15:00:00’), timedelta(6, ‘m’), 10 )

Parameters:
  • rf (xarray.DataArray) – rainfall amount at various time
  • ts (datetime64[ns]) – start time of the accumulated rainfall
  • te (datetime64[ns]) – end time of the accumulated rainfall
  • i (timedelta) – time intervals between each xarray object
Returns:

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 Z-R relationship. Default a & b are Marshall-Plalmer. You may wish to refer to the Z-R 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, only the first one 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
Return type:

str
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 60-minute 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.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 user-defined 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