Utilities (pyart.util) — pyart-mch 0.4.1 documentation

# Utilities (`pyart.util`)

Miscellaneous utility functions.

The location and names of these functions within Py-ART may change between versions without depreciation, use with caution.

## Direction statistics

`angular_mean`(angles) | Compute the mean of a distribution of angles in radians.
`angular_std`(angles) | Compute the standard deviation of a distribution of angles in radians.
`angular_mean_deg`(angles) | Compute the mean of a distribution of angles in degrees.
`angular_std_deg`(angles) | Compute the standard deviation of a distribution of angles in degrees.
`interval_mean`(dist, interval_min, interval_max) | Compute the mean of a distribution within an interval.
`interval_std`(dist, interval_min, interval_max) | Compute the standard deviation of a distribution within an interval.
`mean_of_two_angles`(angles1, angles2) | Compute the element by element mean of two sets of angles.
`mean_of_two_angles_deg`(angle1, angle2) | Compute the element by element mean of two sets of angles in degrees.

## Miscellaneous functions

`cross_section_ppi`(radar, target_azimuths[, …]) | Extract cross sections from a PPI volume along one or more azimuth angles.
`cross_section_rhi`(radar, target_elevations) | Extract cross sections from an RHI volume along one or more elevation angles.
`colocated_gates`(radar1, radar2[, h_tol, …]) | Flags radar gates of radar1 colocated with radar2
`intersection`(radar1, radar2[, h_tol, …]) | Flags region of radar1 that is intersecting with radar2 and complies with criteria regarding visibility, altitude, range, elevation angle and azimuth angle
`datetime_from_radar`(radar[, epoch]) | Return a datetime for the first ray in a Radar.
`datetimes_from_radar`(radar[, epoch]) | Return an array of datetimes for the rays in a Radar.
`datetime_from_dataset`(dataset[, epoch]) | Return a datetime for the first time in a netCDF Dataset.
`datetimes_from_dataset`(dataset[, epoch]) | Return an array of datetimes for the times in a netCDF Dataset.
`datetime_from_grid`(grid[, epoch]) | Return a datetime for the volume start in a Grid.
`estimate_noise_hs74`(spectrum[, navg, nnoise_min]) | Estimate noise parameters of a Doppler spectrum.
`estimate_noise_ivic13`(pwr_w_ray[, pct, …]) | Estimate noise parameters of a ray
`get_ivic_pct`(npulses, pct, z[, prob_thr]) | Get the point clutter threshold (PCT)
`get_ivic_flat_reg_var_max`(npulses, y, x, …) | Get the threshold for maximum local variance of noise [dB]
`get_ivic_snr_thr`(npulses, snr_thr[, pfa_thr]) | Get the threshold for steps 3 and 6 of ivic
`ivic_pct_table`(npulses) | Get the point clutter threshold (PCT) of Ivic from a look up table.
`ivic_snr_thr_table`(npulses) | Get the threshold for steps 3 and 6 of ivic from a look up table The thresholds are computed for between 3 and 200 pulses.
`ivic_flat_reg_var_max_table`(npulses, …) | Get maximum variance of noise of Ivic from a look up table.
`is_vpt`(radar[, offset]) | Determine if a Radar appears to be a vertical pointing scan.
`to_vpt`(radar[, single_scan]) | Convert an existing Radar object to represent a vertical pointing scan.
`join_radar`(radar1, radar2) | Combine two radar instances into one.
`join_spectra`(spectra1, spectra2) | Combine two spectra instances into one.
`subset_radar`(radar, field_names[, rng_min, …]) | Cuts the radar object into new dimensions
`subset_radar_spectra`(radar, field_names[, …]) | Cuts the radar spectra object into new dimensions
`radar_from_spectra`(psr) | obtain a Radar object from a RadarSpectra object
`interpol_spectra`(psr[, kind, fill_value]) | Interpolates the spectra so that it has a uniform grid
`simulated_vel_from_profile`(radar, profile[, …]) | Create simulated radial velocities from a profile of horizontal winds.
`texture_along_ray`(radar, var[, wind_size]) | Compute field texture along ray using a user specified window size.
`texture`(radar, var) | Determine a texture field using an 11pt stdev texarray=texture(pyradarobj, field).
`rolling_window`(a, window) | create a rolling window object for application of functions eg: result=np.ma.std(array, 11), 1)
`angular_texture_2d`(image, N, interval) | Compute the angular texture of an image.

`pyart.util.` `angular_mean`(angles)

  Compute the mean of a distribution of angles in radians.

  Parameters: | angles : array like Distribution of angles in radians.
  Returns: | mean : float The mean angle of the distribution in radians.

`pyart.util.` `angular_mean_deg`(angles)

  Compute the mean of a distribution of angles in degrees.

  Parameters: | angles : array like Distribution of angles in degrees.
  Returns: | mean : float The mean angle of the distribution in degrees.

`pyart.util.` `angular_std`(angles)

  Compute the standard deviation of a distribution of angles in radians.

  Parameters: | angles : array like Distribution of angles in radians.
  Returns: | std : float Standard deviation of the distribution.

`pyart.util.` `angular_std_deg`(angles)

  Compute the standard deviation of a distribution of angles in degrees.

  Parameters: | angles : array like Distribution of angles in degrees.
  Returns: | std : float Standard deviation of the distribution.

`pyart.util.` `angular_texture_2d`(image, N, interval)

  Compute the angular texture of an image. Uses convolutions in order to speed up texture calculation by a factor of ~50 compared to using ndimage.generic_filter.

  Parameters: | image : 2D array of floats The array containing the velocities in which to calculate texture from. N : int This is the window size for calculating texture. The texture will be calculated from an N by N window centered around the gate. interval : float The absolute value of the maximum velocity. In conversion to radial coordinates, pi will be defined to be interval and -pi will be -interval. It is recommended that interval be set to the Nyquist velocity.
  Returns: | std_dev : float array Texture of the radial velocity field.

`pyart.util.` `colocated_gates`(radar1, radar2, h_tol=0.0, latlon_tol=0.0, coloc_gates_field=None)

  Flags radar gates of radar1 colocated with radar2

  Parameters: | radar1 : Radar radar object that is going to be flagged radar2 : Radar radar object h_tol : float tolerance in altitude [m] latlon_tol : float tolerance in latitude/longitude [deg] coloc_gates_field : string Name of the field to retrieve the data
  Returns: | coloc_dict : dict a dictionary containing the colocated positions of radar 1 (ele, azi, rng) and radar 2 coloc_rad1 : field with the colocated gates of radar1 flagged, i.e: 1: not colocated gates 2: colocated (0 is reserved)

`pyart.util.` `cross_section_ppi`(radar, target_azimuths, az_tol=None)

  Extract cross sections from a PPI volume along one or more azimuth angles.

  Parameters: | radar : Radar Radar volume containing PPI sweeps from which azimuthal cross sections will be extracted. target_azimuth : list Azimuthal angles in degrees where cross sections will be taken. az_tol : float, optional Azimuth angle tolerance in degrees. If none the nearest angle is used. If valid only angles within the tolerance distance are considered.
  Returns: | radar_rhi : Radar Radar volume containing RHI sweeps which contain azimuthal cross sections from the original PPI volume.

`pyart.util.` `cross_section_rhi`(radar, target_elevations, el_tol=None)

  Extract cross sections from an RHI volume along one or more elevation angles.

  Parameters: | radar : Radar Radar volume containing RHI sweeps from which azimuthal cross sections will be extracted. target_elevations : list Elevation angles in degrees where cross sections will be taken. el_tol : float, optional Elevation angle tolerance in degrees. If none the nearest angle is used. If valid only angles within the tolerance distance are considered.
  Returns: | radar_ppi : Radar Radar volume containing PPI sweeps which contain azimuthal cross sections from the original RHI volume.

`pyart.util.` `subset_radar`(radar, field_names, rng_min=None, rng_max=None, ele_min=None, ele_max=None, azi_min=None, azi_max=None)

  Cuts the radar object into new dimensions

  Parameters: | radar : radar object The radar object containing the data field_names : str or None The fields to keep in the new radar rng_min, rng_max : float The range limits [m]. If None the entire coverage of the radar is going to be used ele_min, ele_max, azi_min, azi_max : float or None The limits of the grid [deg]. If None the limits will be the limits of the radar volume
  Returns: | radar : radar object The radar object containing only the desired data

`pyart.util.` `subset_radar_spectra`(radar, field_names, rng_min=None, rng_max=None, ele_min=None, ele_max=None, azi_min=None, azi_max=None)

  Cuts the radar spectra object into new dimensions

  Parameters: | radar : radar object The radar object containing the data field_names : str or None The fields to keep in the new radar rng_min, rng_max : float The range limits [m]. If None the entire coverage of the radar is going to be used ele_min, ele_max, azi_min, azi_max : float or None The limits of the grid [deg]. If None the limits will be the limits of the radar volume
  Returns: | radar : radar object The radar object containing only the desired data

`pyart.util.` `datetime_from_dataset`(dataset, epoch=False, **kwargs)

  Return a datetime for the first time in a netCDF Dataset.

`pyart.util.` `datetime_from_grid`(grid, epoch=False, **kwargs)

  Return a datetime for the volume start in a Grid.

`pyart.util.` `datetime_from_radar`(radar, epoch=False, **kwargs)

  Return a datetime for the first ray in a Radar.

`pyart.util.` `datetimes_from_dataset`(dataset, epoch=False, **kwargs)

  Return an array of datetimes for the times in a netCDF Dataset.

`pyart.util.` `datetimes_from_radar`(radar, epoch=False, **kwargs)

  Return an array of datetimes for the rays in a Radar.

`pyart.util.` `estimate_noise_hs74`(spectrum, navg=1, nnoise_min=1)

  Estimate noise parameters of a Doppler spectrum.

  Use the method of estimating the noise level in Doppler spectra outlined by Hildebrand and Sehkon, 1974.

  Parameters: | spectrum : array like Doppler spectrum in linear units. navg : int, optional The number of spectral bins over which a moving average has been taken. Corresponds to the p variable from equation 9 of the article. The default value of 1 is appropiate when no moving average has been applied to the spectrum. nnoise_min : int Minimum number of noise samples to consider the estimation valid
  Returns: | mean : float-like Mean of points in the spectrum identified as noise. threshold : float-like Threshold separating noise from signal. The point in the spectrum with this value or below should be considered as noise, above this value signal. It is possible that all points in the spectrum are identified as noise. If a peak is required for moment calculation then the point with this value should be considered as signal. var : float-like Variance of the points in the spectrum identified as noise. nnoise : int Number of noise points in the spectrum.

  References

  P. H. Hildebrand and R. S. Sekhon, Objective Determination of the Noise Level in Doppler Spectra. Journal of Applied Meteorology, 1974, 13, 808-811.

`pyart.util.` `estimate_noise_ivic13`(pwr_w_ray, pct=2.0, delay=1, flat_reg_wlen=96, flat_reg_var_max=1.5, snr_thr=1.6, npulses=30, ngates_min=800, iterations=10, get_noise_pos=False)

  Estimate noise parameters of a ray

  Use the method of estimating the noise level in a ray outlined by Ivic, 2013.

  Parameters: | pwr_w_ray : array like Doppler spectrum in linear units. pct : float Point Clutter Threshold delay : int distance of the gate to which compare for point target threshold flat_reg_wlen : int Minimum number of gates that should contain a valid region. Default gives a size of 8 km with 83.3 m resolution flat_reg_var_max : float Maximum local variance of powers in decibels to consider the region as flat. snr_thr : float Threshold applied in steps 3 and 6 npulses : int Number of pulses used to compute the power of the array ngates_min: int minimum number of gates with noise to consider the retrieval valid iterations: int number of iterations in step 7 get_noise_pos : bool If True the indices of the gates identified as noise will be returned
  Returns: | mean : float-like Mean of the gates in the ray identified as noise. var : float-like Variance of the gates in the ray identified as noise. nnoise : int Number of noise gates in the ray. inds_ray : 1D-array The indices of the gates containing noise

  References

  I.R. Ivic, C. Curtis and S.M. Torres, Radial-Based Noise Power Estimation for Weather Radars. Journal of Atmospheric and Oceanic Technology, 2013, 30, 2737-2753.

`pyart.util.` `get_ivic_flat_reg_var_max`(npulses, y, x, flat_reg_wlen, ndBm=30.0, accuracy=0.001)

  Get the threshold for maximum local variance of noise [dB]

  Parameters: | npulses : 1D array array with the number of pulses in a ray y : 1D array array of y values x : 1D array array of x values. These are the possible values of the threshold flat_reg_wlen : int the lenght of the flat region window in bins ndBm : float the mean noise power in dBm accuracy : float The desired accuracy of the threshold (difference with target probability)
  Returns: | var_thr : 1D array The thresholds corresponding to each number of pulses

`pyart.util.` `get_ivic_pct`(npulses, pct, z, prob_thr=0.0001)

  Get the point clutter threshold (PCT)

  Parameters: | npulses : 1D array array with the number of pulses in a ray pct : 1D array array with possible values of the PCT z : 1D array array of z values prob_thr : float Desired probability
  Returns: | pct_out : 1D array The PCT threshold corresponding to each number of pulses

`pyart.util.` `get_ivic_snr_thr`(npulses, snr_thr, pfa_thr=0.001)

  Get the threshold for steps 3 and 6 of ivic

  Parameters: | npulses : 1D array array with the number of pulses in a ray snr_thr : 1D array array with possible values of the snr threshold pfa_thr : float the desired probability of false alarm
  Returns: | snr_thr_out : 1D array The snr threshold corresponding to each number of pulses according to the desired probability of false alarm

`pyart.util.` `interpol_spectra`(psr, kind='linear', fill_value=0.0)

  Interpolates the spectra so that it has a uniform grid

  Parameters: | psr : RadarSpectra object The original spectra
  Returns: | psr_interp : RadarSpectra object The interpolated spectra

`pyart.util.` `intersection`(radar1, radar2, h_tol=0.0, latlon_tol=0.0, vol_d_tol=None, vismin=None, hmin=None, hmax=None, rmin=None, rmax=None, elmin=None, elmax=None, azmin=None, azmax=None, visib_field=None, intersec_field=None)

  Flags region of radar1 that is intersecting with radar2 and complies with criteria regarding visibility, altitude, range, elevation angle and azimuth angle

  Parameters: | radar1 : Radar radar object that is going to be flagged radar2 : Radar radar object checked for intersecting region h_tol : float tolerance in altitude [m] latlon_tol : float latitude and longitude tolerance [decimal deg] vol_d_tol : float pulse volume diameter tolerance [m] vismin : float minimum visibility [percentage] hmin, hmax : floats min and max altitude [m MSL] rmin, rmax : floats min and max range from radar [m] elmin, elmax : floats min and max elevation angle [deg] azmin, azmax : floats min and max azimuth angle [deg]
  Returns: | intersec_rad1_dict : dict the field with the gates of radar1 in the same region as radar2 flagged, i.e.: 1 not intersecting, 2 intersecting, 0 is reserved

`pyart.util.` `interval_mean`(dist, interval_min, interval_max)

  Compute the mean of a distribution within an interval.

  Return the average of the array elements which are interpreted as being taken from a circular interval with endpoints given by interval_min and interval_max.

  Parameters: | dist : array like Distribution of values within an interval. interval_min, interval_max : float The endpoints of the interval.
  Returns: | mean : float The mean value of the distribution.

`pyart.util.` `interval_std`(dist, interval_min, interval_max)

  Compute the standard deviation of a distribution within an interval.

  Return the standard deviation of the array elements which are interpreted as being taken from a circular interval with endpoints given by interval_min and interval_max.

  Parameters: | dist : array_like Distribution of values within an interval. interval_min, interval_max : float The endpoints of the interval.
  Returns: | std : float The standard deviation of the distribution.

`pyart.util.` `is_vpt`(radar, offset=0.5)

  Determine if a Radar appears to be a vertical pointing scan.

  This function only verifies that the object is a vertical pointing scan, use the `to_vpt()` function to convert the radar to a vpt scan if this function returns True.

  Parameters: | radar : Radar Radar object to determine if. offset : float, optional Maximum offset of the elevation from 90 degrees to still consider to be vertically pointing.
  Returns: | flag : bool True if the radar appear to be verticle pointing, False if not.

`pyart.util.` `ivic_flat_reg_var_max_table`(npulses, flat_reg_wlen)

  Get maximum variance of noise of Ivic from a look up table.

  Parameters: | npulses : 1D array array with the number of pulses in a ray flat_reg_wlen : float The flat region window length in bins
  Returns: | flat_reg_var_max : 1D array The maximum variance threshold corresponding to each number of pulses

`pyart.util.` `ivic_pct_table`(npulses)

  Get the point clutter threshold (PCT) of Ivic from a look up table. The thresholds are computed for between 3 and 78 pulses. If there number of pulses is beyond this range it throws an error

  Parameters: | npulses : 1D array array with the number of pulses in a ray
  Returns: | pct_table : 1D array The PCT corresponding to each number of pulses

`pyart.util.` `ivic_snr_thr_table`(npulses)

  Get the threshold for steps 3 and 6 of ivic from a look up table The thresholds are computed for between 3 and 200 pulses. If there number of pulses is beyond this range it throws an error

  Parameters: | npulses : 1D array array with the number of pulses in a ray
  Returns: | snr_thr_out : 1D array The snr threshold corresponding to each number of pulses according to the desired probability of false alarm

`pyart.util.` `join_radar`(radar1, radar2)

  Combine two radar instances into one.

  Parameters: | radar1 : Radar Radar object. radar2 : Radar Radar object.

`pyart.util.` `join_spectra`(spectra1, spectra2)

  Combine two spectra instances into one.

  Parameters: | spectra1 : spectra spectra object. spectra2 : spectra spectra object.

`pyart.util.` `mean_of_two_angles`(angles1, angles2)

  Compute the element by element mean of two sets of angles.

  Parameters: | angles1 : array First set of angles in radians. angles2 : array Second set of angles in radians.
  Returns: | mean : array Elements by element angular mean of the two sets of angles in radians.

`pyart.util.` `mean_of_two_angles_deg`(angle1, angle2)

  Compute the element by element mean of two sets of angles in degrees.

  Parameters: | angle1 : array First set of angles in degrees. angle2 : array Second set of angles in degrees.
  Returns: | mean : array Elements by element angular mean of the two sets of angles in degrees.

`pyart.util.` `radar_from_spectra`(psr)

  obtain a Radar object from a RadarSpectra object

  Parameters: | psr : RadarSpectra object The reference object
  Returns: | radar : radar object The new radar object

`pyart.util.` `rolling_window`(a, window)

  create a rolling window object for application of functions eg: result=np.ma.std(array, 11), 1)

`pyart.util.` `simulated_vel_from_profile`(radar, profile, interp_kind='linear', sim_vel_field=None)

  Create simulated radial velocities from a profile of horizontal winds.

  Parameters: | radar : Radar Radar instance which provides the scanning parameters for the simulated radial velocities. profile : HorizontalWindProfile Profile of horizontal winds. interp_kind : str, optional Specifies the kind of interpolation used to determine the winds at a given height. Must be one of ‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic’, or ‘cubic’. The the documentation for the SciPy scipy.interpolate.interp1d function for descriptions. sim_vel_field : str, optional Name to use for the simulated velocity field metadata. None will use the default field name from the Py-ART configuration file.
  Returns: | sim_vel : dict Dictionary containing a radar field of simulated radial velocities.

`pyart.util.` `texture`(radar, var)

  Determine a texture field using an 11pt stdev texarray=texture(pyradarobj, field).

`pyart.util.` `texture_along_ray`(radar, var, wind_size=7)

  Compute field texture along ray using a user specified window size.

  Parameters: | radar : radar object The radar object where the field is. var : str Name of the field which texture has to be computed. wind_size : int, optional Optional. Size of the rolling window used.
  Returns: | tex : radar field The texture of the specified field.

`pyart.util.` `to_vpt`(radar, single_scan=True)

  Convert an existing Radar object to represent a vertical pointing scan.

  This function does not verify that the Radar object contains a vertical pointing scan. To perform such a check use `is_vpt()`.

  Parameters: | radar : Radar Mislabeled vertical pointing scan Radar object to convert to be properly labeled. This object is converted in place, no copy of the existing data is made. single_scan : bool, optional True to convert the volume to a single scan, any azimuth angle data is lost. False will convert the scan to contain the same number of scans as rays, azimuth angles are retained.