towerpy.utils.radutilities#

Towerpy: an open-source toolbox for processing polarimetric radar data.

Functions#

`find_nearest`(iarray, val2search[, mode])	Return the index of the closest value to a given number.
`normalisenan`(a)	Scale input vectors to unit norm, ignoring any NaNs.
`normalisenanvalues`(a, vmin, vmax)	Scale input vectors to unit norm, by scaling the vector to given values.
`fillnan1d`(x)	Fill nan value with last non nan value.
`interp_nan`(x, y[, kind, nan_type])	Interpolate 1-D arrays to fill nan-masked values.
`maf_radial`(rad_vars[, maf_len, maf_ignorenan, ...])	Apply a Moving-Average Filter to variables along the radial direction.
`get_datashp`(fname[, key2read])	Read in data from *.shp files using cartopy.
`get_windows_data`(wdw_size, wdw_coords, array2extract)	Retrieve data from a PPI scan using size-defined windows.
`rolling_window`(a, window[, mode, constant_values])	Compute a rolling window using np.lib.stride_tricks for fast computation.
`compute_texture`(tpy_coordlist, rad_vars[, wdw_size, ...])	Compute the texture of given arrays.
`idx_consecutive`(array1d[, step_size, group_size])	Find the index of consecutive non-nan values within a 1D array.
`linspace_step`(start, stop, step)	Like np.linspace but uses step instead of num.
`_to_kilometers`(var)	Convert units of DataArray in metres to kilometres.
`xr_hist2d`(x, y, x_edges, y_edges, dim)	Compute a vectorised 2D histogram of two DataArrays.
`record_provenance`(ds, function, outputs, parameters[, ...])	Update a Dataset’s provenance chain by recording function steps, inputs, outputs, and parameters.
`apply_correction_chain`(ds, varname, step, params[, ...])	Apply a correction mask to a variable and add it back into the Dataset,

Module Contents#

towerpy.utils.radutilities.find_nearest(iarray, val2search, mode='any')[source]#

Return the index of the closest value to a given number.

Parameters#

iarrayarray

Input array.

val2searchfloat or int

Value to search into the array.

mode{“any”, “major”, “minor”}, optional

“any”: closest value in the array (default)
“major”: closest local maximum
“minor”: closest local minimum

Returns#

idxfloat or int: Index into the array, or None if no candidate found.

towerpy.utils.radutilities.normalisenan(a)[source]#

Scale input vectors to unit norm, ignoring any NaNs.

Parameters#

aarray: The data to normalise, element by element.

Returns#

normarrayarray: Normalised input a.

towerpy.utils.radutilities.normalisenanvalues(a, vmin, vmax)[source]#

Scale input vectors to unit norm, by scaling the vector to given values.

Parameters#

aarray: The data to normalize.
vminfloat or int: Minimum value used to scale the data.
vmaxfloat or int: Maximum value used to scale the data.

Returns#

normarrayarray: Normalised data.

towerpy.utils.radutilities.fillnan1d(x)[source]#

Fill nan value with last non nan value.

Parameters#

xarray: The data to be filled.

Returns#

xf: Array with nan values filtered.

towerpy.utils.radutilities.interp_nan(x, y, kind='linear', nan_type='mask')[source]#

Interpolate 1-D arrays to fill nan-masked values.

Parameters#

xarray_like: 1-D array.
yarray_like: 1-D array.
kindstr, optional: Specifies the kind of interpolation used in the scipy.interpolate.interp1d function. The default is ‘linear’.
nan_typestr, optional: Type of non-valid values, either ‘nan’ or ‘mask’. The default is ‘mask’.

towerpy.utils.radutilities.maf_radial(rad_vars, maf_len=3, maf_ignorenan=True, maf_extendvalid=False, maf_params=None)[source]#

Apply a Moving-Average Filter to variables along the radial direction.

Parameters#

rad_varsdict

Radar variables to be smoothed.

maf_lenint, optional

Odd number used to apply a moving average filter to each beam and smooth the signal. The default is 3.

maf_ignorenanbool, optional

Set to False if nan values shall not be filtered. The default is True.

maf_paramsdict, optional

Filters the radar variable using min and max constraints. The default are:

\(ZH\) [dBZ]: [-np.inf, np.inf]

\(Z_{DR}\) [dB]: [-np.inf, np.inf]

\(\Phi_{DP}\) [deg]: [-np.inf, np.inf]

\(\rho_{HV}\) [-]: [-np.inf, np.inf]

\(V\) [m/s]: [-np.inf, np.inf]

\(LDR\) [dB]: [-np.inf, np.inf]35, 35, 3]

Returns#

mafvarsdict: Transformed data.

towerpy.utils.radutilities.get_datashp(fname, key2read=None)[source]#

Read in data from *.shp files using cartopy.

Parameters#

fnamestr: Name of the *.shp file.
key2readstr, optional: Name of the feature to retrieve from the *.shp file. The default is None.

Returns#

shpdatalistlist: Features extrated from the file.

towerpy.utils.radutilities.get_windows_data(wdw_size, wdw_coords, array2extract)[source]#

Retrieve data from a PPI scan using size-defined windows.

Parameters#

wdw_size2-element tuple or list of int: Size of the window [row, cols]. Must be odd numbers.
wdw_coords2-element tuple or list of int/floats: Coordinates within the PPI scan of the centre of the window to extract.
array2extractarray: Data array from which the data will bve retrieved.

Returns#

wdwlist: Retrieved data.

towerpy.utils.radutilities.rolling_window(a, window, mode='constant', constant_values=np.nan)[source]#

Compute a rolling window using np.lib.stride_tricks for fast computation.

Parameters#

aarray: Array to be smoothed.
window2-element tuple or list, optional: Window size (m, n) used to apply a moving average filter. m and n must be odd numbers for the m-rays and n-gates. The default is (1, 3).
modestr, optional: Mode used to pad the array. See numpy.pad for more information. The default is ‘constant’.
constant_valuesint or float, optional: Used in ‘constant’. The values to set the padded values for each axis. The default is np.nan.

Notes#

It is expected to pad arrays that represent radar data in polar format. Thus, the rays are wrapped, and the gates are extended for consistency.

towerpy.utils.radutilities.compute_texture(tpy_coordlist, rad_vars, wdw_size=[3, 3], classid=None)[source]#

Compute the texture of given arrays.

Parameters#

tpy_coordlist3-element tuple or list of int

Coordinates and classID of a given pixel.

rad_varsdict

Radar variables used to compute the texture.

wdw_size2-element tuple or list of int

Size of the window [row, cols]. Must be odd numbers. The default is [3, 3].

classiddict

Key/values of the echoes classification:

‘precipi’ = 0

‘clutter’ = 5

Returns#

rvarsdict: Texture values.

towerpy.utils.radutilities.idx_consecutive(array1d, step_size=1, group_size=1)[source]#

Find the index of consecutive non-nan values within a 1D array.

Parameters#

array1darray_like: Input 1-D array.
stepsizeint or float, optional: Difference between consecutive elements. The default is 1.
group_sizeint, optional: Minimum size of the grouped consecutive-valid values. The default is 3.

towerpy.utils.radutilities.linspace_step(start, stop, step)[source]#: Like np.linspace but uses step instead of num.

towerpy.utils.radutilities._to_kilometers(var: xarray.DataArray)[source]#: Convert units of DataArray in metres to kilometres.

towerpy.utils.radutilities.xr_hist2d(x, y, x_edges, y_edges, dim)[source]#

Compute a vectorised 2D histogram of two DataArrays.

Parameters#

x, yxr.DataArray: Input variables to histogram over, sharing the same core dimensions.
x_edges, y_edgesarray-like: Bin edges for the x and y axes, defining the histogram grid.
dimlist[str]: Dimensions over which the histogram is computed and reduced.

Returns#

xr.DataArray: A 2D histogram with labelled x_bin and y_bin dimensions, vectorised over all non-core dimensions.

towerpy.utils.radutilities.record_provenance(ds, function, outputs, parameters, step=None, inputs=None, extra_attrs=None)[source]#

Update a Dataset’s provenance chain by recording function steps, inputs, outputs, and parameters.

Parameters#

dsxr.Dataset: Dataset whose provenance metadata is to be updated.
functionstr: Name of the function contributing to the correction chain.
outputslist[str]: Variables produced or modified by the function.
parametersdict: Parameter values used during the function call.
stepstr, optional: Logical step name for grouping related function calls; defaults to function.
inputslist[str], optional: Variables read or required by the function.
extra_attrsdict, optional: Additional attributes to attach directly to the Dataset.

Returns#

xr.Dataset: The Dataset with an updated correction_chain attribute reflecting the new provenance entry.

towerpy.utils.radutilities.apply_correction_chain(ds, varname, step, params, mask=None, suffix='_corr')[source]#

Apply a correction mask to a variable and add it back into the Dataset, appending provenance-aware metadata to track the full correction chain.

Parameters#

dsxarray.Dataset: Dataset containing the variable to correct.
varnamestr: Name of the variable to correct.
maskxarray.DataArray: Boolean or categorical mask aligned with ds[varname].
stepstr: Short tag describing the correction step (e.g. “SNR_correction”).
paramsdict: Parameters used in the correction (e.g. {“min_snr”: 5}).
suffixstr, optional: Suffix for the corrected variable name. Default “_corr”.

Returns#

dsxarray.Dataset: Dataset with new corrected variable added.