Metrics

Methods to evaluate the quality of our signals, few metrics.

ultraspy.metrics.build_mask(position, dimension, x_axis, z_axis, shape='circle')

Build a mask given a numpy area, the shape of the mask and its dimension and location. The resulting array is of type bool, with False values within the requested shape and True elsewhere. Few shapes are supported:

  • circle: build a circle mask, centered at ‘position’ with the radius ‘dimension’

  • empty_circle: build an empty circle mask, centered at ‘position’. It expects ‘dimension’ to be a tuple with (radius, radius_offset), both in m, with radius_offset the width of the circle border

  • rectangle: build a rectangular mask, centered at ‘position’. It expects ‘dimension’ to be a tuple with (width, height), both in m

  • square: build a square mask, centered at ‘position’ with a width of ‘dimension’, in m

Parameters:

  • position (tuple) – The position of the mask to apply (in m). It is either the center of the shape (in case of circle / empty circle), or the top left position for square or rectangular masks

  • dimension (float, tuple) – The dimension of the shape (check the detail of each shape to know what is expected here)

  • x_axis (numpy.ndarray) – The lateral axis

  • z_axis (numpy.ndarray) – The axial axis

  • shape (str) – The requested shape for the mask (can be either ‘circle’, ‘empty_circle’, ‘rectangle’, ‘square’)

Returns:

The masked array with the requested mask, it can be used using np.ma.masked_where(this_mask, data)

Return type:

numpy.ndarray

ultraspy.metrics.find_signal_and_noise(data, signal_width=20, noise_offset=50, ignore_until=0, noise_size=None, show=False)

Returns an estimation of where the signal and noise could be in a signal based on its maximum value and some ad-hoc values.

Parameters:

  • data (numpy.ndarray) – The sample of data to evaluate (must be 1D)

  • signal_width (int, list) – The width of the signal in the data, it can be either an integer (total width, centered around maximum value), or a list with two integers [nb_time_samples before / after max value].

  • noise_offset (int) – The number of time sample to skip between signal and noise.

  • ignore_until (int) – The number of time sample to ignore at the beginning of the data (artificial 0 values at the beginning after truncation for example).

  • noise_size (int) – The maximum number of time samples for noise. If None, takes everything it can.

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

The indices of both the signal and the noise

Return type:

tuple

ultraspy.metrics.get_contrat_noise_ratio(b_mode, focus_mask, noise_mask, cr=False)

Returns the Contrast to Noise ratio of the data, using two masks, one for the position of the signal, the other one for the noise.

\[CNR = 20 . \log_{10} \left ( \frac{|\mu_{cyst} - \mu_{speckle}|} {{\sqrt{(\sigma_{cyst}^{2} + \sigma_{speckle}^{2}) / 2}}} \right )\]

Or, if you set cr to True:

\[CR = 20 . \log_{10} \left ( \frac{\mu_{speckle}}{\mu_{cyst}} \right )\]
Parameters:

  • b_mode (numpy.ndarray) – The b_mode to evaluate

  • focus_mask (numpy.ndarray) – The mask area where to find the signal

  • noise_mask (numpy.ndarray) – The mask area where to find the noise

  • cr (bool) – If set to True, will compute the CR instead

Returns:

The Contrast to Noise Ratio (in dB)

Return type:

float

ultraspy.metrics.get_full_width_at_half_maximum(signal, focus_idx, line_axis, half=-6, local=True, get_details=False, show=False)

Returns the Full-Width at Half Maximum of a signal, given a focus index. It is basically the width of the focused lobe at -6dB.

Parameters:

  • signal (numpy.ndarray) – The sample of data to evaluate

  • focus_idx (int) – The index to focus on, we’ll look for the lobe around this index

  • line_axis (numpy.ndarray) – The spatial axis to know the location of each pixel

  • half (int) – Where to cut the lobe (default to -6dB)

  • local (bool) – If set to True, consider local maximum (FWHM is bound to maximum of the lobe - half). Else case, arbitrary -6dB is used (or half if specified)

  • get_details (bool) – If set to True, the function will return the details of the computation, which is useful for visualization

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

Either the FWHM itself, or a dictionary with the details of the computation

Return type:

dict, float

ultraspy.metrics.get_lobe_metrics(b_mode, focus, x, z, show=False)

Calls both peak side lobe and FWHM methods to return the results in both axial and lateral axes.

Parameters:

  • b_mode (numpy.ndarray) – The B-Mode image to study (of shape (nb_x, nb_z))

  • focus (tuple) – The indices to focus on, we’ll look for the lobe around this position

  • x (numpy.ndarray) – The lateral axis

  • z (numpy.ndarray) – The axial axis

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

A dictionary with the results of both PSL and FWHM computation for both lateral and axial axes

Return type:

dict

ultraspy.metrics.get_most_salient_point(data, ignore_until=0, show=False)

Returns the position which received the highest amplitude.

Parameters:

  • data (numpy.ndarray) – The data to evaluate (multidimensional)

  • ignore_until (int) – Ignore the first x time samples (assumed to be the last axis)

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

The indices of the most salient pixel in the image

Return type:

tuple

ultraspy.metrics.get_peak_side_lobe(signal, focus_idx, line_axis, get_details=False, show=False)

Returns the Peak Side Lobe of a signal, given a focus index. It is basically the difference in dB between the focused lobe and its closest neighbor.

Parameters:

  • signal (numpy.ndarray) – The sample of data to evaluate

  • focus_idx (int) – The index to focus on, we’ll look for the lobe around this index

  • line_axis (numpy.ndarray) – The spatial axis to know the location of each pixel

  • get_details (bool) – If set to True, the function will return the details of the computation, which is useful for visualization

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

Either the PSL itself, or a dictionary with the details of the computation

Return type:

dict, float

ultraspy.metrics.signal_noise_ratio(data, signal_bounds, noise_bounds, center=True, max_power=False, show=False)

Returns the Signal to Noise ratio of the sample, based on the location of both the pulse and the noise.

\[SNR = 10 . \log_{10} \left ( \frac{\sum^{N_{s}} (s^{2} / N_{s})} {\sum^{N_{n}} (n^{2} / N_{n})} \right )\]
Parameters:

  • data (numpy.ndarray) – The sample of data to evaluate

  • signal_bounds (tuple) – The indices of the signal (pulse) to observe

  • noise_bounds (tuple) – The indices of the noise to compare

  • center (bool) – If set to True, will center the average of the pulse and the noise to 0

  • max_power (bool) – If set to True, will take the maximum value of the pulse sample only. Else case, it performs an average of the results

  • show (bool) – If set to True, shows the results with matplotlib

Returns:

The Signal to Noise Ratio (in dB)

Return type:

float