proadv 2.0.2__py3-none-any.whl

proadv/filtration/detection/acceleration.py

@@ -0,0 +1,65 @@
+import numpy as np
+from proadv.statistics.spread import std
+
+
+def acceleration_thresholding(velocities, frequency, tag, gravity=980, k_gravity=1.5, k_sigma=1):
+    """
+    Detects acceleration events based on velocity data.
+
+    This function calculates acceleration events based on velocity data, considering thresholds
+        for acceleration magnitude and velocity deviation from mean.
+
+    Parameters
+    ------
+        velocities (array_like): Array of velocity data.
+            An array-like object containing velocity values.
+        frequency (float): Sampling frequency.
+            The frequency at which the velocity data is sampled,
+            used to calculate acceleration from velocity differences.
+        tag (int): Tag for acceleration direction.
+            An integer indicating the direction of acceleration to detect:
+                - 1 for positive acceleration (increasing velocity)
+                - 2 for negative acceleration (decreasing velocity).
+        gravity (float): Value of gravity.
+            The acceleration due to gravity, used as a reference for acceleration thresholds.
+            Default is 980 (m/s^2).
+        k_gravity (float): Threshold multiplier for gravity.
+            A multiplier applied to the gravity value to determine the acceleration threshold.
+            Default is 1.5.
+        k_sigma (float, optional): Threshold multiplier for standard deviation.
+            A multiplier applied to the standard deviation of velocities to determine velocity deviation threshold.
+            Default is 1.
+
+    Returns
+    ------
+        accel_indices (array_like): Indices of acceleration events.
+            An array containing the indices of the detected acceleration events.
+
+    Raises
+    ------
+        ValueError: If invalid tag value is provided.
+            Raised when the tag value is not 1 or 2.
+
+    References
+    ------
+        Goring, Derek G., and Vladimir I. Nikora.
+            "Despiking acoustic Doppler velocimeter data."
+            Journal of hydraulic engineering 128.1 (2002): 117-126.
+    """
+    velocities = np.asarray(velocities)
+
+    # Calculate velocity differences and multiply by frequency to obtain acceleration
+    differences = np.concatenate((np.array([0]), np.diff(velocities) * frequency))
+
+    if tag == 1:
+        # Detect positive acceleration events
+        accel_indices = np.intersect1d(np.where(differences > k_gravity * gravity)[0],
+                                       np.where(velocities > np.mean(velocities) + k_sigma * std(velocities))[0])
+    elif tag == 2:
+        # Detect negative acceleration events
+        accel_indices = np.intersect1d(np.where(differences < -k_gravity * gravity)[0],
+                                       np.where(velocities < np.mean(velocities) - k_sigma * std(velocities))[0])
+    else:
+        raise ValueError("Invalid tag value. Expected 1 or 2.")
+
+    return accel_indices

proadv/filtration/detection/bivariatekernel.py

@@ -0,0 +1,53 @@
+import numpy as np
+
+
+def _cutoff(density_profile, velocity_profile, c1_threshold, c2_threshold, force_profile, peak_index, grid):
+    """
+    Find the lower and upper cutoff velocities based on specified criteria.
+
+    Parameters
+    ------
+    density_profile (array_like): Density profile of the system.
+    velocity_profile (array_like): Velocity profile of the system.
+    c1_threshold (float): Threshold ratio for force compared to peak force.
+    c2_threshold (float): Threshold for absolute change in force.
+    force_profile (array_like): Force profile of the system.
+    peak_index (int): Index of the peak force in the force profile.
+    grid (int): Grid spacing or resolution.
+
+    Returns
+    ------
+    lower_cutoff_velocity, upper_cutoff_velocity: A tuple containing the lower and upper cutoff velocities.
+
+    Note
+    ------
+    This function assumes that the input arrays (density_profile, velocity_profile, and force_profile) 
+        are of the same length.
+        length.
+    The density profile, velocity profile, and force profile should be consistent and correspond to 
+        each other at each index.
+    """
+
+    profile_length = force_profile.size
+    delta_force = np.append([0], np.diff(force_profile)) * grid / density_profile
+
+    # Find lower cutoff index
+    for i in range(peak_index - 1, 0, -1):
+        if force_profile[i] / force_profile[peak_index] <= c1_threshold and abs(delta_force[i]) <= c2_threshold:
+            lower_cutoff_index = i
+            break
+    else:
+        lower_cutoff_index = 1
+
+    # Find upper cutoff index
+    for i in range(peak_index + 1, profile_length - 1):
+        if force_profile[i] / force_profile[peak_index] <= c1_threshold and abs(delta_force[i]) <= c2_threshold:
+            upper_cutoff_index = i
+            break
+    else:
+        upper_cutoff_index = profile_length - 1
+
+    lower_cutoff_velocity = velocity_profile[lower_cutoff_index]
+    upper_cutoff_velocity = velocity_profile[upper_cutoff_index]
+
+    return lower_cutoff_velocity, upper_cutoff_velocity

proadv/filtration/detection/correlation.py

@@ -0,0 +1,78 @@
+import numpy as np
+from proadv.filtration.detection.poincare import calculate_ab, calculate_rho
+from proadv.statistics.spread import std
+
+
+def calculate_parameters(up, vp, wp):
+    """
+    Calculate parameters required for velocity correlation.
+
+    Parameters
+    ------
+        up (array_like): Array of the first velocity component.
+        vp (array_like): Array of the second velocity component.
+        wp (array_like): Array of the third velocity component.
+
+    Returns
+    ------
+        lambda_ (float): Lambda value used in velocity correlation detection.
+        std_u (float): Standard deviation of the longitudinal velocity component.
+        std_v (float): Standard deviation of the transverse velocity component.
+        std_w (float): Standard deviation of the vertical velocity component.
+    """
+    data_size = up.size
+    std_u = std(up)
+    std_v = std(vp)
+    std_w = std(wp)
+    lambda_ = np.sqrt(2 * np.log(data_size))
+    return lambda_, std_u, std_v, std_w
+
+
+def velocity_correlation(ui, vi, wi):
+    """
+    Detect spikes using velocity correlation filter, based on three velocity components.
+
+    Parameters
+    ------
+        ui (array_like): Array of the longitudinal velocity component.
+        vi (array_like): Array of the transverse velocity component.
+        wi (array_like): Array of the vertical velocity component.
+
+    Returns
+    ------
+        correl_indices (array_like): Indices of spikes detected by velocity correlation.
+
+    References
+    ------
+        Cea, L., J. Puertas, and L. Pena.
+            "Velocity measurements on highly turbulent free surface flow using ADV."
+            Experiments in fluids 42 (2007): 333-348.
+    """
+    from proadv.statistics.descriptive import mean
+    ui, vi, wi = ui - mean(ui), vi - mean(vi), wi - mean(wi)
+    lambda_, std_u, std_v, std_w = calculate_parameters(ui, vi, wi)
+
+    # Calculate angles between velocity components
+    theta1 = np.arctan(np.sum(ui * vi) / np.sum(ui ** 2))
+    theta2 = np.arctan(np.sum(ui * wi) / np.sum(ui ** 2))
+    theta3 = np.arctan(np.sum(vi * wi) / np.sum(vi ** 2))
+
+    # Calculate 'a' and 'b' coefficients for each angle
+    a1, b1 = calculate_ab(std_u, std_v, theta1, lambda_)
+    a2, b2 = calculate_ab(std_u, std_w, theta2, lambda_)
+    a3, b3 = calculate_ab(std_v, std_w, theta3, lambda_)
+
+    # Calculate rho values for each component pair
+    rho1 = calculate_rho(ui, vi, theta1, a1, b1)
+    rho2 = calculate_rho(ui, wi, theta2, a2, b2)
+    rho3 = calculate_rho(vi, wi, theta3, a3, b3)
+
+    # Find indices where rho values exceed 1 (indicating correlation)
+    x1 = np.nonzero(rho1 > 1)[0]
+    x2 = np.nonzero(rho2 > 1)[0]
+    x3 = np.nonzero(rho3 > 1)[0]
+
+    # Combine all detected indices and remove duplicates
+    correl_indices = np.sort(np.unique(np.concatenate((x1, x2, x3))))
+
+    return correl_indices

proadv/filtration/detection/phasespace.py

@@ -0,0 +1,173 @@
+import numpy as np
+from proadv.filtration.detection.poincare import calculate_rho
+from proadv.statistics.spread import std
+
+
+def calculate_derivatives(c):
+    """
+    Calculate time-independent first and second order derivatives of the input data.
+
+    Parameters
+    ------
+        c (array_like): Input data.
+
+    Returns
+    ------
+        dc (array_like): First derivative of the input data.
+        dc2 (array_like): Second derivative of the input data.
+    """
+    # Initialize arrays for first and second derivatives
+    dc = np.zeros_like(c)
+    dc2 = np.zeros_like(c)
+
+    # Calculate first derivative
+    for i in range(1, len(c) - 1):
+        dc[i] = np.around((c[i + 1] - c[i - 1]) / 2, 4)
+
+    # Calculate second derivative
+    for i in range(1, len(c) - 1):
+        dc2[i] = np.around((dc[i + 1] - dc[i - 1]) / 2, 4)
+
+    return dc, dc2
+
+
+def calculate_parameters(c, dc, dc2):
+    """
+    Calculate parameters for phase-space thresholding.
+
+    Parameters
+    ------
+        c (array_like): Array of the velocity component.
+        dc (array_like): First derivative of the input data.
+        dc2 (array_like): Second derivative of the input data.
+
+    Returns
+    ------
+        std_c (float): Standard deviation of the input data.
+        std_dc (float): Standard deviation of the first derivative.
+        std_dc2 (float): Standard deviation of the second derivative.
+        lambda_ (float): Lambda value.
+        theta (float | rad): Angle between components.
+        a1 (float): Coefficient 'a1'.
+        b1 (float): Coefficient 'b1'.
+        a2 (float): Coefficient 'a2'.
+        b2 (float): Coefficient 'b2'.
+        a3 (float): Coefficient 'a3'.
+        b3 (float): Coefficient 'b3'.
+    """
+    # Calculate standard deviations
+    std_c = std(c)
+    std_dc = std(dc)
+    std_dc2 = std(dc2)
+
+    # Calculate lambda value
+    lambda_ = np.sqrt(2 * np.log(len(c)))
+
+    # Calculate theta value
+    theta = np.arctan(np.sum(c * dc2) / np.sum(c ** 2))
+
+    # Calculate coefficients
+    a1 = lambda_ * std_c
+    b1 = lambda_ * std_dc
+    a2 = lambda_ * std_dc
+    b2 = lambda_ * std_dc2
+    fact = np.cos(theta) ** 4 - np.sin(theta) ** 4
+    a3 = np.sqrt(a1 ** 2 * np.cos(theta) ** 2 - b2 ** 2 * np.sin(theta) ** 2) / fact
+    b3 = np.sqrt(b2 ** 2 * np.cos(theta) ** 2 - a1 ** 2 * np.sin(theta) ** 2) / fact
+    return std_c, std_dc, std_dc2, lambda_, theta, a1, b1, a2, b2, a3, b3
+
+
+def phasespace_thresholding(c):
+    """
+    Detect spikes using phase-space thresholding, based on each velocity component and
+        their first-order and second-order derivatives.
+
+    Phase-space thresholding is a method for detecting spikes or abrupt changes in time series data
+        by analyzing the behavior of the data in a multidimensional space defined by the data and its derivatives.
+
+
+    Parameters
+    ------
+        c (array_like): Velocity component
+
+    Returns
+    ------
+        phase_indices (array_like): Array containing the indices of detected spikes.
+
+    References
+    ------
+        Goring, Derek G., and Vladimir I. Nikora.
+            "Despiking acoustic Doppler velocimeter data."
+            Journal of hydraulic engineering 128.1 (2002): 117-126.
+    """
+
+    # Calculate first and second order derivatives of the input data
+    dc, dc2 = calculate_derivatives(c)
+
+    # Calculate parameters used in phase-space thresholding
+    std_c, std_dc, std_dc2, lambda_, theta, a1, b1, a2, b2, a3, b3 = calculate_parameters(c, dc, dc2)
+
+    # Calculate poincare map rho values for each dimension
+    rho1 = calculate_rho(c, dc, 0, a1, b1)
+    rho2 = calculate_rho(dc, dc2, 0, a2, b2)
+    rho3 = calculate_rho(c, dc2, theta, a3, b3)
+
+    # Find indices where rho values exceed the threshold
+    x1 = np.nonzero(rho1 > 1)[0]
+    x2 = np.nonzero(rho2 > 1)[0]
+    x3 = np.nonzero(rho3 > 1)[0]
+
+    # Concatenate and sort indices to get unique spike indices
+    phase_indices = np.sort(np.unique(np.concatenate((x1, x2, x3))))
+
+    return phase_indices
+
+
+def phasespace_thresholding_premodification(data, c1=1.5, c2=1.35):
+    """
+    Perform phase space thresholding premodification on a given data array.
+
+    Parameters
+    ------
+        data (array_like): Array of data to be processed.
+        c1 (float, optional): Threshold parameter for unremovable data. Default is 1.5.
+        c2 (float, optional): Threshold parameter for removable data. Default is 1.35.
+
+    Returns
+    ------
+        data (array_like): Processed data array with potential modifications.
+        unremovable_indices (array_like): Indices of unremovable data points.
+
+    Notes
+    ------
+        This function applies phase space thresholding premodification to the input data array.
+        Threshold parameters c1 and c2 determine which data points are considered unremovable and removable, respectively.
+        Unremovable data points are those within the range of -c1*theta to c1*theta, where theta is the median absolute deviation.
+        Removable data points are those exceeding c2*theta*sqrt(2*log(ndata)), where theta is the median absolute deviation
+            and ndata is the length of the data array.
+        Removable data points are replaced with the value of the preceding data point.
+
+    Example
+    ------
+        >>> data = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+        >>> phasespace_thresholding_premodification(data)
+    """
+
+    data_size = data.size
+    theta = np.median(np.absolute(data - np.median(data)))
+
+    # Calculate indices of unremovable data
+    unremovable_indices = np.intersect1d(np.nonzero(data >= -c1 * theta)[0], np.nonzero(data <= c1 * theta)[0])
+
+    # Calculate threshold for removable data
+    removable_threshold = c2 * theta * np.sqrt(2 * np.log(data_size))
+
+    # Calculate indices of removable data
+    removable_indices = np.intersect1d(np.nonzero(data > removable_threshold)[0],
+                                       np.nonzero(data < -removable_threshold)[0])
+
+    # Replace removable data points with the preceding data point
+    for i in removable_indices:
+        data[i] = data[i - 1]
+
+    return data, unremovable_indices

proadv/filtration/detection/poincare.py

@@ -0,0 +1,46 @@
+import numpy as np
+
+
+def calculate_ab(std1, std2, theta, lambda_):
+    """
+    Calculate 'a' and 'b' coefficients for poincare mapping base detection algorithms.
+
+    Parameters
+    ------
+        std1 (float): Standard deviation of the first component.
+        std2 (float): Standard deviation of the second component.
+        theta (float | rad): Angle between components.
+        lambda_ (float): Lambda value used in algorithm.
+
+    Returns
+    ------
+        float: Coefficient 'a' used in poincare map.
+        float: Coefficient 'b' used in poincare map.
+    """
+    r1 = lambda_ * std1
+    r2 = lambda_ * std2
+    fact = np.cos(theta) ** 4 - np.sin(theta) ** 4
+    fa = (r1 ** 2 * np.cos(theta) ** 2 - r2 ** 2 * np.sin(theta) ** 2) / fact
+    fb = (r2 ** 2 * np.cos(theta) ** 2 - r1 ** 2 * np.sin(theta) ** 2) / fact
+    return np.sqrt(fa), np.sqrt(fb) if fa > 0 and fb > 0 else (1e10, 1e10)
+
+
+def calculate_rho(x, y, theta, a, b):
+    """
+    Calculate rho value for poincare mapping base detection algorithms.
+
+    Parameters
+    ------
+        x (array_like): First component.
+        y (array_like): Second component.
+        theta (float | rad): Angle between components.
+        a (float): Coefficient 'a' used in poincare map.
+        b (float): Coefficient 'b' used in poincare map.
+
+    Returns
+    ------
+        rho (array_like): Rho value calculated for poincare map.
+    """
+    xp = x * np.cos(theta) + y * np.sin(theta)
+    yp = y * np.cos(theta) - x * np.sin(theta)
+    return (xp / a) ** 2 + (yp / b) ** 2

proadv/filtration/detection/pollution.py

@@ -0,0 +1,32 @@
+import numpy as np
+from proadv.statistics.spread import std
+
+
+def pollution_rate(x, xfil, k):
+    """
+    Compute the pollution rate based on the given data and threshold.
+
+    Parameters
+    ------
+    x (array_like): Input data array.
+    xfil (array_like): SSA analyzed data of x.
+    k (float): Threshold factor.
+
+    Returns
+    ------
+    pollution (float): Pollution rate as a percentage.
+    """
+    
+    # Find positions where x exceeds the threshold
+    pos = np.nonzero(x > xfil + k * std(x))
+    
+    # Find positions where x is below the negative threshold
+    neg = np.nonzero(x < -xfil - k * std(x))
+    
+    # Concatenate positive and negative noises
+    noises = np.concatenate((pos, neg), axis=None)
+    
+    # Compute pollution rate
+    pollution = len(noises) / len(x) * 100
+    
+    return pollution

proadv/filtration/detection/spherical.py

@@ -0,0 +1,181 @@
+import numpy as np
+
+
+def _descript(c, iteration, c_mean):
+    """
+    Calculate the mean value and center the input data.
+
+    Parameters
+    ------
+    c (array_like): Input data.
+    iteration (int): Loop counter.
+    c_mean (float): Mean value of input data.
+
+    Returns
+    ------
+    f (array_like): Centered input data.
+    f_mean (float): Updated mean value.
+    """
+    if iteration == 1:
+        f_mean = np.around(np.nanmean(c), 4)
+    else:
+        f_mean = np.around(c_mean + np.nanmean(c), 4)
+    f = np.around(c - np.nanmean(c), 4)
+    return f, f_mean
+
+
+def _gradients(c):
+    """
+    Calculate the first and second order derivatives of the input data.
+
+    Parameters
+    ------
+    c (array_like): Input data.
+
+    Returns
+    ------
+    dc (array_like): First order derivative of the input data.
+    dc2 (array_like): Second order derivative of the input data.
+    """
+    dc = np.gradient(c)
+    dc2 = np.gradient(dc)
+    return dc, dc2
+
+
+def _rotation(c, dc, dc2, theta):
+    """
+    Rotate the input data based on the specified angle theta.
+
+    Parameters
+    ------
+    c (array_like): Input data.
+    dc (array_like): First order derivative of the input data.
+    dc2 (array_like): Second order derivative of the input data.
+
+    Returns
+    ------
+    x (array_like): Rotated X-axis data.
+    y (array_like): Rotated Y-axis data.
+    z (array_like): Rotated Z-axis data.
+    """
+    if theta == 0:
+        x = c.copy()
+        y = dc.copy()
+        z = dc2.copy()
+    else:
+        rotation_matrix = np.around(np.array([
+            [np.cos(theta), 0, np.sin(theta)],
+            [0, 1, 0],
+            [-np.sin(theta), 0, np.cos(theta)]
+        ]), 4)
+        x = np.around(c * rotation_matrix[0, 0] + dc * rotation_matrix[0, 1] + dc2 * rotation_matrix[0, 2], 4)
+        y = np.around(c * rotation_matrix[1, 0] + dc * rotation_matrix[1, 1] + dc2 * rotation_matrix[1, 2], 4)
+        z = np.around(c * rotation_matrix[2, 0] + dc * rotation_matrix[2, 1] + dc2 * rotation_matrix[2, 2], 4)
+    return x, y, z
+
+
+def _parameters(x, y, z):
+    """
+    Calculate parameters for phase-space thresholding in spherical coordinates.
+
+    Parameters
+    ------
+    x (array_like): Rotated X-axis data.
+    y (array_like): Rotated Y-axis data.
+    z (array_like): Rotated Z-axis data.
+
+    Returns
+    ------
+    a (float): Coefficient 'a'.
+    b (float): Coefficient 'b'.
+    c (float): Coefficient 'c'.
+    """
+    lambda_ = np.around(np.sqrt(2 * np.log(x.size)), 4)
+    a = np.around(lambda_ * np.nanstd(x), 4)
+    b = np.around(lambda_ * np.nanstd(y), 4)
+    c = np.around(lambda_ * np.nanstd(z), 4)
+    return a, b, c
+
+
+def _spike_indices(x, y, z, a, b, c):
+    """
+    Calculate spike indices based on the input data and coefficients.
+
+    Parameters
+    ------
+    x (array_like): Rotated X-axis data.
+    y (array_like): Rotated Y-axis data.
+    z (array_like): Rotated Z-axis data.
+    a (float): Coefficient 'a'.
+    b (float): Coefficient 'a'.
+    c (float): Coefficient 'a'.
+
+    Returns
+    ------
+    spike_indices (array_like): Indices of detected spikes.
+    """
+    xp, yp, zp, ip = [], [], [], []
+    for i in range(x.size):
+        x1 = x[i]
+        y1 = y[i]
+        z1 = z[i]
+        x2 = np.around(a * b * c * x1 / np.sqrt((a * c * y1) ** 2 + b ** 2 * (c ** 2 * x1 ** 2 + a ** 2 * z1 ** 2)), 4)
+        y2 = np.around(a * b * c * y1 / np.sqrt((a * c * y1) ** 2 + b ** 2 * (c ** 2 * x1 ** 2 + a ** 2 * z1 ** 2)), 4)
+        zt = np.around(c ** 2 * (1 - (x2 / a) ** 2 - (y2 / b) ** 2), 4)
+        if z1 < 0:
+            z2 = -np.around(np.sqrt(zt), 4)
+        elif z1 > 0:
+            z2 = np.around(np.sqrt(zt), 4)
+        else:
+            z2 = 0
+        dis = (x2 ** 2 + y2 ** 2 + z2 ** 2) - (x1 ** 2 + y1 ** 2 + z1 ** 2)
+        if dis < 0:
+            ip.append(i)
+            xp.append(x[i])
+            yp.append(y[i])
+            zp.append(z[i])
+    spike_indices = np.array(ip, dtype=np.int64)
+    return spike_indices
+
+
+def spherical_phasespace_thresholding(c, iteration, c_mean):
+    """
+    Detect spikes using three-dimensional phase-space thresholding, based on each velocity component and
+        their first-order and second-order derivatives.
+
+    Parameters
+    ------
+    c (array_like): Velocity component
+    iteration (int): Loop counter.
+    c_mean (float): Mean of the velocity component
+
+    Returns
+    ------
+    spherical_indices (array_like): Array containing the indices of detected spikes.
+
+    References
+    ------
+        Wahl, Tony L.
+        "Discussion of “Despiking acoustic doppler velocimeter data” by Derek G. Goring and Vladimir I. Nikora."
+        Journal of Hydraulic Engineering 129, no. 6 (2003): 484-487.
+    """
+
+    # Calculate mean and center the data
+    c, c_mean = _descript(c, iteration, c_mean)
+
+    # Calculate gradients
+    dc, dc2 = _gradients(c)
+
+    # Calculaterotation angle
+    theta = np.around(np.arctan2(np.sum(c * dc), np.sum(dc2 ** 2)), 4)
+
+    # Rotate data
+    x, y, z = _rotation(c, dc, dc2, theta)
+
+    # Calculate parameters
+    a, b, c = _parameters(x, y, z)
+
+    # Calculate spike indices
+    spherical_indices = _spike_indices(x, y, z, a, b, c)
+
+    return spherical_indices