kkpy.util¶

Utility functions for my research

Winds¶

`kkpy.util.wind2uv`([wd, ws, radians, knots])	Convert wind direction and speed to u and v wind components.
`kkpy.util.uv2wind`(u, v)	Convert u and v wind components to wind direction and speed.
`kkpy.util.ms2knot`(ws_ms)	Convert unit of wind speed from meter per seconds to knots.
`kkpy.util.knot2ms`(ws_knot)	Convert unit of wind speed from knots to meter per seconds.

Radars¶

kkpy.util.dbzmean(dbz_arr[, outside_radar, …])

Get linear-scale average of reflectivity (dBZ).

Microphysics¶

`kkpy.util.vel_atlas`(D)	Get Atlas et al. (1973) fall velocity.
`kkpy.util.calc_dsdmoments`(ND, D, dD[, VD, …])	Get DSD moments from drop size distribution.

Maps¶

`kkpy.util.proj_dfs`()	Return a lambert conformal conic projection of DFS (Digital Forecasting System) used in KMA.
`kkpy.util.proj_icepop`()	Return a lambert conformal conic projection for ICE-POP 2018 domain.
`kkpy.util.dist_bearing`(lonlat0, lonlat1[, …])	Get distance [km] and bearing [deg] between two lon/lat points.

Spatial calculations¶

`kkpy.util.nn_idx_2d`(xtarget, ytarget, x2d, y2d)	Get nearest indices of the x and y values of target if 2D array is given.
`kkpy.util.cross_section_2d`(xy0, xy1, x2d, …)	Get values along the transect of two points (lon/lat) for 2D array.
`kkpy.util.to_lower_resolution`(arr_in, …[, dBZ])	Get 2D array with lower resolution.

ICE-POP 2018¶

`kkpy.util.icepop_events`([KST])	Get datetimes for nine major evnets in ICE-POP 2018.
`kkpy.util.icepop_sites`()	Get metadata of ICE-POP 2018 sites.
`kkpy.util.icepop_extent`()	Get extent of ICE-POP 2018 domain.

Miscellaneous¶

`kkpy.util.std2d`(X, window_size)	Get 2D standard deviation of 2D array efficiently.
`kkpy.util.nanstd2d`(X, window_size)	Get 2D standard deviation of 2D array efficiently with missings ignored.
`kkpy.util.nanconvolve2d`(slab, kernel[, …])	Get 2D convolution with missings ignored.
`kkpy.util.derivative`(var, cnt_x[, …])	Get derivative of 1D or 2D array.
`kkpy.util.stats`(x, y[, fmtbias, fmtrmse, …])	Get performance matrix BIAS, RMSE, STD, and CORR values and its f-string.
`kkpy.util.summary`(arr[, cnt_print])	Get summary of the array.
`kkpy.util.get_intersect`(list_array)	Get intersection of multiple 1D arrays.

kkpy.util.wind2uv(wd=None, ws=None, radians=False, knots=False)[source]¶

Convert wind direction and speed to u and v wind components.

Examples

>>> u, v = kkpy.util.wind2uv(wd, ws)

Parameters

wd (array_like) – Array containing wind direction in degree. It should be meteorological direction, not mathematical.
ws (array_like) – Array containing wind speed in m/s.
radians (boolean, optional) – If this is set to True, the unit of wd is radian. The default is False (i.e. degree).
knots (boolean, optional) – If this is set to True, the unit of ws is knots. The default is False (i.e. m/s).

Returns

u (ndarray) – Return u component of wind in m/s.
v (ndarray) – Return v component of wind in m/s.

kkpy.util.uv2wind(u, v)[source]¶

Convert u and v wind components to wind direction and speed.

Examples

>>> wd, ws = kkpy.util.uv2wind(u, v)

Parameters

u (array_like) – Array containing u component of wind in m/s.
v (array_like) – Array containing v component of wind in m/s.

Returns

wd (ndarray) – Return wind direction in degree.
ws (ndarray) – Return wind speed in m/s.

kkpy.util.ms2knot(ws_ms)[source]¶

Convert unit of wind speed from meter per seconds to knots.

Examples

>>> ws_knot = kkpy.util.ms2knot(ws_ms)

Parameters: ws_ms (array_like) – Array containing wind speed in m/s.
Returns: ws_knot – Return wind speed in knots.
Return type: ndarray

kkpy.util.knot2ms(ws_knot)[source]¶

Convert unit of wind speed from knots to meter per seconds.

Examples

>>> ws_ms = kkpy.util.knot2ms(ws_knot)

Parameters: ws_knot (array_like) – Array containing wind speed in knots.
Returns: ws_ms – Return wind speed in m/s.
Return type: ndarray

kkpy.util.nn_idx_2d(xtarget, ytarget, x2d, y2d)[source]¶

Get nearest indices of the x and y values of target if 2D array is given.

Examples

>>> x2d, y2d = np.meshgrid(np.arange(128,130,0.1), np.arange(36,38,0.1))
>>> idx2d = kkpy.util.nn_idx_2d(128.35, 37.65, x2d, y2d)
>>> print(x2d[idx2d], y2d[idx2d])

Parameters

xtarget (float) – Target value of x.
ytarget (float) – Target value of y.
x2d (2D array) – Numpy 2D array containing x value of each grid point. The shape of x2d and y2d should be same.
y2d (2D array) – Numpy 2D array containing y value of each grid point. The shape of x2d and y2d should be same.

Returns

idx2d – Return an array of nearest x and y indicies.

Return type

1D array

kkpy.util.cross_section_2d(xy0, xy1, x2d, y2d, value2d, linewidth=1, along='x', reduce_func=<function mean>)[source]¶

Get values along the transect of two points (lon/lat) for 2D array.

Examples

>>> dem, lon, lat, proj = kkpy.io.read_dem(area='pyeongchang')
>>> start = [127.52, 37.3]
>>> end = [129, 36.52]
>>> xaxis, vcross = kkpy.util.cross_section_2d(start, end, lon, lat, dem)
>>> plt.plot(xaxis, vcross)
>>> plt.show()

Parameters

xy0 (array_like) – Array of x and y values of starting point.
xy1 (array_like) – Array of x and y values of ending point.
x2d (2D array) – Numpy 2D array containing x value of each grid point. The shape of x2d, y2d, and value2d should be same.
y2d (2D array) – Numpy 2D array containing y value of each grid point. The shape of x2d, y2d, and value2d should be same.
value2d (2D array) – Numpy 2D array containing data value of each grid point. The shape of x2d, y2d, and value2d should be same.
linewidth (int, optional) – The linewidth used in average over perpendicular direction along the transect. Default is 1 (i.e. no average).
along (str, optional) – Set ‘x’ to return xaxis in x axis, otherwise return it in y axis. Default is ‘x’.
reduce_func (callable, optional) – Function used to calculate the aggregation of pixel values perpendicular to the profile_line direction when linewidth > 1. See skimage.measure.profile_line for detail.

Returns

xaxis (1D array) – Return xaxis of cross-section in longitude or latitude unit. The unit is determined by along keyword.
vcross (1D array) – Return averaged value along the cross-section.

kkpy.util.proj_dfs()[source]¶

Return a lambert conformal conic projection of DFS (Digital Forecasting System) used in KMA.

Examples

>>> import cartopy.crs as ccrs
>>> ax = plt.subplot(proj=kkpy.util.proj_dfs())
>>> ax.scatter([126], [38], transform=ccrs.PlateCarree())
>>> plt.show()

Returns: proj – Return a map projection of DFS.
Return type: cartopy projection

kkpy.util.proj_icepop()[source]¶

Return a lambert conformal conic projection for ICE-POP 2018 domain.

Examples

>>> import cartopy.crs as ccrs
>>> ax = plt.subplot(proj=kkpy.util.proj_icepop())
>>> ax.scatter([129], [37.7], transform=ccrs.PlateCarree())
>>> ax.set_extent(kkpy.util.icepop_extent(), crs=ccrs.PlateCarree())
>>> plt.show()

Returns: proj – Return a map projection of DFS.
Return type: cartopy projection

kkpy.util.dist_bearing(lonlat0, lonlat1, radians=False)[source]¶

Get distance [km] and bearing [deg] between two lon/lat points.

Examples

>>> dist_km, bearing_deg = kkpy.util.dist_bearing([127.5,36], [130,37])

Parameters

lonlat0 (1D Array) – Array containing longitude and latitude of the first point. Longitude (latitude) should be at the first (second) element.
lonlat1 (1D Array) – Array containing longitude and latitude of the second point. Longitude (latitude) should be at the first (second) element.
radians (boolean, optional) – If this is set to True, the unit of bearing is radian. The default is False (i.e. degree).

Returns

distance (float) – Return distance between two points in km.
bearing (ndarray) – Return bearing of two points in degree. If radians is True, the unit is radians.

kkpy.util.nanconvolve2d(slab, kernel, max_missing=0.99)[source]¶

Get 2D convolution with missings ignored.

Examples

Moving 2D standard deviation

>>> import astropy.convolution
>>> kernel = np.array(astropy.convolution.Box2DKernel(5))
>>> c1 = kkpy.util.nanconvolve2d(arr2d, kernel)
>>> c2 = kkpy.util.nanconvolve2d(arr2d*arr2d, kernel)
>>> stddev2d = np.sqrt(c2 - c1*c1)

Moving 2D average

>>> import astropy.convolution
>>> kernel = np.array(astropy.convolution.Box2DKernel(5))
>>> avg2d = kkpy.util.nanconvolve2d(arr2d, kernel)

Parameters

slab (2D Array) – Input array to convolve. Can have numpy.nan or masked values.
kernel (1D Array) – Convolution kernel, must have sizes as odd numbers.
max_missing (float, optional) – Float in (0,1), max percentage of missing in each convolution window is tolerated before a missing is placed in the result.

Returns

result – Return convolution result. Missings are represented as numpy.nans if they are in slab, or masked if they are masked in slab.

Return type

2D Array

Notes

This code is from Stack Overflow answer (https://stackoverflow.com/a/40416633/12272819), written by Jason (https://stackoverflow.com/users/2005415/jason). This is licensed under the Creative Commons Attribution-ShareAlike 3.0 license (CC BY-SA 3.0). Modified by Kwonil Kim in November 2020: modify docstring format, remove verbose argument, modify default value of max_missing, change numpy to np

kkpy.util.nanstd2d(X, window_size)[source]¶

Get 2D standard deviation of 2D array efficiently with missings ignored.

Examples

>>> std2d = kkpy.util.nanstd2d(arr2d, 3)

Parameters

X (2D Array) – Array containing the data.
window_size (float) – Window size of x and y. Window sizes of x and y should be same.

Returns

std2d – Return 2D standard deviation.

Return type

2D Array

kkpy.util.std2d(X, window_size)[source]¶

Get 2D standard deviation of 2D array efficiently.

Examples

>>> std2d = kkpy.util.std2d(arr2d, 3)

Parameters

X (2D Array) – Array containing the data.
window_size (float or 1D array) – Window size. If array of two elements, window sizes of x and y will be window_size[0] and window_size[1], respectively.

Returns

std2d – Return 2D standard deviation.

Return type

2D Array

Notes

This code is from https://nickc1.github.io/python,/matlab/2016/05/17/Standard-Deviation-(Filters)-in-Matlab-and-Python.html, written by Nick Cortale. Modified by Kwonil Kim in November 2020: add docstring, modify function name

kkpy.util.dbzmean(dbz_arr, outside_radar=- 9999.0, noprecip=- 9998.0, qced=- 9997.0, axis=None)[source]¶

Get linear-scale average of reflectivity (dBZ).

Examples

>>> dbz_avg = kkpy.util.dbzmean(dbz_arr)

Parameters

X (array_like) – Array containing the reflectivity in dBZ.
outside_radar (float, optional) – Value indicating the grid point is located outside radar observable range. This will not be included in the count during the average.
noprecip (float, optional) – Value indicating the grid point is clear echo. This will be considered as 0.0 mm6 m-3.
qced (float, optional) – Value indicating the grid point is masked by QC process. This will not be included in the count during the average.
axis (None or int or tuple of ints, optional) –
Axis or axes along which the means are computed.

New in version 0.2.0.

Returns

dbz_avg – Return averaged reflectivity in dBZ.

Return type

array_like

kkpy.util.icepop_events(KST=False)[source]¶

Get datetimes for nine major evnets in ICE-POP 2018.

Examples

>>> dts = kkpy.util.icepop_events()
>>> for eventno in np.arange(9)+1:
>>>     dt = dts[eventno]
>>>     print(f'eventno = {eventno}, start = {dt[0]}, end = {dt[1]}')

Parameters: KST (boolean, optional) – True if return the datetime in KST, rather than UTC.
Returns: dict_datetimes – Return a dictionary of array containing start and finish datetime for each event.
Return type: dictionary

kkpy.util.icepop_sites()[source]¶

Get metadata of ICE-POP 2018 sites.

Examples

>>> # Plotting in Lon/Lat coordinates
>>> for lon, lat, hgt, site in kkpy.util.icepop_sites():
>>>     plt.plot(lon, lat, marker='o', color='red', markersize=3, alpha=0.5, transform=ccrs.PlateCarree())
>>>     plt.text(lon+0.01, lat, site, verticalalignment='center', fontsize=10, transform=ccrs.PlateCarree())

>>> # Plotting in Lon/Hgt coordinates
>>> for lon, lat, hgt, site in kkpy.util.icepop_sites():
>>>     plt.plot(lon, hgt/1e3, marker='o', color='red', markersize=3, alpha=0.5)
>>>     plt.text(lon+0.01, hgt/1e3, site, verticalalignment='center', fontsize=10)

Returns: tuple_sites – Return a tuple containing longitude, latitude, height, and sitename for each ICE-POP 2018 supersite.
Return type: tuple

kkpy.util.icepop_extent()[source]¶

Get extent of ICE-POP 2018 domain.

Examples

>>> ax.set_extent(kkpy.util.icepop_extent(), crs=ccrs.PlateCarree())

Returns: list_extent – Return a list containing lon0, lon1, lat0, and lat1 of default ICE-POP 2018 domain.
Return type: list

kkpy.util.vel_atlas(D)[source]¶

Get Atlas et al. (1973) fall velocity.

Examples

>>> V_arr = kkpy.util.vel_atlas(D_arr)

Parameters: D (array_like) – Array containing the diameter in mm.
Returns: V – Return a fall velocity of raindrop for a given diameter.
Return type: array_like

kkpy.util.calc_dsdmoments(ND, D, dD, VD=None, Vatlas=False)[source]¶

Get DSD moments from drop size distribution.

Examples

>>> tdvd = kkpy.util.calc_dsdmoments(ND_arr, D_arr, dD_arr, VD=VD_arr)

>>> poss = kkpy.util.calc_dsdmoments(ND_arr, D_arr, dD_arr, Vatlas=True)

Parameters

ND (array_like) – Array containing the number concentration in mm-1 m-3. If 2D array, the diameter should be at the first axis (i.e. axis = 0).
D (array_like) – Array containing the median of each diameter channel in mm.
dD (array_like) – Array containing the spread of each diameter channel in mm.
VD (array_like, optional) – Array containing the mean velocity of each diameter channel in m s-1. Vatlas should be False if VD contains data.
Vatlas (boolean, optional) – True if VD is replaced by the velocity-diameter relationship of Atlas et al. (1973).

Returns

dict_moments – Return a dictionary containing the DSD moments: z[mm6 m-3], Z[dBZ], and R[mm hr-1].

Return type

dictionary

kkpy.util.stats(x, y, fmtbias='.3f', fmtrmse='.3f', fmtstd='.3f', fmtcorr='.3f')[source]¶

Get performance matrix BIAS, RMSE, STD, and CORR values and its f-string.

Examples

>>> stats, str_stat = kkpy.util.stats(xarr, yarr)
>>> print(stats)
>>> plt.text(3, 5, str_stat)

>>> stats, str_stat = kkpy.util.stats(xarr, yarr, fmtbias='.1f', fmtcorr='.2f')

Parameters

x (array_like) – Array containing multiple variables and observations.
y (array_like) – Array containing multiple variables and observations. The shape should be same as x.
fmtbias (str, optional) – String format for BIAS. Default is ‘.3f’.
fmtrmse (str, optional) – String format for RMSE. Default is ‘.3f’.
fmtstd (str, optional) – String format for STD. Default is ‘.3f’.
fmtcorr (str, optional) – String format for CORR. Default is ‘.3f’.

Returns

dict_moments – Return a dictionary containing the DSD moments: z[mm6 m-3], Z[dBZ], and R[mm hr-1].

Return type

dictionary

kkpy.util.summary(arr, cnt_print=10)[source]¶

Get summary of the array.

Parameters

arr (array_like) – Array containing multiple variables and observations.
cnt_print (int, optional) – The number of elements to print.

kkpy.util.derivative(var, cnt_x, pixelsize=1, axis=0)[source]¶

Get derivative of 1D or 2D array.

Examples

>>> # Derivative of 1D array with a window size of 5.
>>> # Note that the horizontal resolution of xarr is 0.1.
>>> xarr = np.arange(100)*0.1
>>> yarr = np.exp(xarr)
>>> dydx = kkpy.util.derivative(yarr, 5, pixelsize=0.1)

>>> # This example gives the derivative of arr2d along x axis with a window size of 20.
>>> # Assume that you have an arr2d[iy,ix] with horizontal resolution of 3 km.
>>> dzdx = kkpy.util.derivative(arr2d, 11, pixelsize=3000, axis=1)

Parameters

var (array_like) – Array containing multiple variables and observations.
cnt_x (int) – The number of the pixel for derivative. This should be odd number. The derivative will be (Y[i+N/2]-Y[i-N/2]) / (N-1).
pixelsize (float, optional) – The size of one pixel of x axis. If default (1), the derivative means the rate of change on an interval of one pixel with resolution of 1.
axis (int, optional) – Axis along which the derivatives are computed. Default is 0.

Returns

derivative – Return a derivative for a given array.

Return type

array_like

kkpy.util.to_lower_resolution(arr_in, ratio_x, ratio_y, dBZ=False)[source]¶

Get 2D array with lower resolution.

Examples

>>> arr1 = np.random.rand(250,150) # shape: (250,150)
>>> arr2 = to_lower_resolution(arr1,10,10) # shape: (25,15)
>>> arr3 = to_lower_resolution(arr1,5,10) # shape: (50,15)

Parameters

arr_in (2D array) – Array you want to lower the resolution.
ratio_x (int) – The reduction ratio over x axis. The size of arr_in xaxis should be able to be divided by ratio_x.
ratio_y (int) – The reduction ratio over y axis. The size of arr_in yaxis should be able to be divided by ratio_y.
dBZ (boolean, optional) – True if return a linear-scale average of reflectivity (dBZ).

Returns

arr_out – Return an array with lower resolution.

Return type

2D array

Notes

This code is from Stack Overflow answer (https://stackoverflow.com/a/14916963/12272819), written by Jaime (https://stackoverflow.com/users/110026/jaime). This is licensed under the Creative Commons Attribution-ShareAlike 3.0 license (CC BY-SA 3.0).

kkpy.util.get_intersect(list_array)[source]¶

Get intersection of multiple 1D arrays.

Examples

>>> arr1 = np.array([0,1,2,4,5,6])
>>> arr2 = np.array([0,1,3,4,6])
>>> arr_inter = kkpy.util.get_intersect([arr1, arr2]) # [0,1,4,6]

Parameters: list_array (array_like) – List of 1D numpy arrays.
Returns: intersection – Return an array with lower resolution.
Return type: array_like

Notes

This code is based on Stack Exchange answer (https://codereview.stackexchange.com/a/145210), written by Peilonrayz (https://codereview.stackexchange.com/users/42401/peilonrayz). This is licensed under the Creative Commons Attribution-ShareAlike 3.0 license (CC BY-SA 3.0).