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 Z=aR^b

  • correlation (float) – correlation of 2 time series of reflectivity and rainfall

swirlspy.qpe.rfmap module

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.

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.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.

Return type

Raingauge_object

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.