pytspl.filters

Filter module for filter designs.

Submodules

• pytspl.filters.base_filter
• pytspl.filters.chebyshev_filter_design
• pytspl.filters.edge_flow_denoising
• pytspl.filters.grid_based_filter_design
• pytspl.filters.ls_filter_design
• pytspl.filters.simplicial_trend_filter

Classes

ChebyshevFilterDesign	Chebyshev polynomial filter design inheriting from the
EdgeFlowDenoising	Edge flow denoising with a low-pass filter H_P.
GridBasedFilterDesign	Module for grid-based filter design inheriting from the
LSFilterDesign	Module for LS filter design inheriting from the BaseFilter class.
SimplicialTrendFilter	Simplicial trend filter class for denoising and interpolation.

Package Contents

class pytspl.filters.ChebyshevFilterDesign(simplicial_complex: pytspl.simplicial_complex.SimplicialComplex)

Bases: pytspl.filters.base_filter.BaseFilter

Chebyshev polynomial filter design inheriting from the BaseFilter class.

_get_chebyshev_series(n: int, domain_min: float, domain_max: float, cut_off_frequency: float = 0.01, steep: int = 100) → numpy.ndarray

Approximate the Chebyshev series for the given points.

Args:

n (int): The number of points. domain_min (float): The minimum domain value. domain_max (float): The maximum domain value. cut_off_frequency (float, optional): The cut-off frequency. Defaults to 0.01. steep (int, optional): The steepness of the logistic function. Defaults to 100.

Returns:

np.ndarray: The Chebyshev series.

_chebyshev_filter_approximate(P: numpy.ndarray, coefficients: numpy.ndarray, alpha: float, order: int) → numpy.ndarray

Approximate the Chebyshev filter.

Args:

P (np.ndarray): The Laplacian matrix. coefficients (np.ndarray): The coefficients of the Chebyshev filter. alpha (float): The alpha value. order (int): The order of the Chebyshev polynomial.

Returns:

np.ndarray: The Chebyshev filter approximation.

get_alpha(p_choice: str) → tuple

Calculate the alpha value for the given choice of P matrix using the power iteration method.

Args:

p_choice (str): The choice of P matrix.

Returns:

tuple: The alpha and lambda_max value calculated.

get_ideal_frequency(component_coeffs: numpy.ndarray) → numpy.ndarray

Calculate the ideal frequency of the component.

Args:

component_coeffs: The masked coefficients of the component.

Returns:

np.ndarray: The ideal frequency of the given component.

get_chebyshev_frequency_approx(p_choice: str, coeffs: numpy.ndarray, alpha: float, order: int) → numpy.ndarray

Calculate the Chebyshev frequency approximation.

Args:

p_choice (str): The choice of P matrix. coeffs (np.ndarray): The coefficients of the Chebyshev filter. alpha (float): The alpha value. order (int): The order of the Chebyshev polynomial.

Returns:

np.ndarray: The Chebyshev frequency approximation.

apply(f: numpy.ndarray, p_choice: str = 'L1L', component: str = 'gradient', L: int = 10, n: int = None, cut_off_frequency: float = 0.01, steep: int = 100) → None

Apply the Chebyshev filter to the given flow f.

Args:

f (np.ndarray): The input flow. p_choice (str, optional): The choice of P matrix. Defaults to “L1L”. component (str, optional): The component of the flow. Defaults to “gradient”. L (int, optional): The filter size. Defaults to 10. n (int, optional): The number of points. Defaults to None. cut_off_frequency (float, optional): The cut-off frequency. Defaults to 0.01. steep (int, optional): The steepness of the logistic function. Defaults to 100.

plot_chebyshev_series_approx(p_choice: str, n: int = None, cut_off_frequency: float = 0.01, steep: int = 100) → None

Plot the Chebyshev series approximation.

Args:

p_choice (str): The choice of P matrix. n (int, optional): The number of points. Defaults to None. cut_off_frequency (float, optional): The cut-off frequency. Defaults to 0.01. steep (int, optional): The steepness of the logistic function. Defaults to 100.

plot_frequency_response_approx(flow: numpy.ndarray, component: str, fontdict: dict = None) → None

Plot the built filter’s frequency response.

Args:

flow (np.ndarray): The input flow. component (str): The component of the flow. fontdict (dict, optional): The font dictionary used for plotting. Defaults to None.

Raises:

ValueError: If the apply method is not run first.

class pytspl.filters.EdgeFlowDenoising(simplicial_complex: pytspl.simplicial_complex.SimplicialComplex)

Bases: pytspl.filters.base_filter.BaseFilter

Edge flow denoising with a low-pass filter H_P.

Solve the regularized optimization problem to estimate f_tilde from f = f0 + ε where, ε is a zero mean Gaussian noise.

denoise(f: numpy.ndarray, f_true: numpy.ndarray, p_choice: str, mu_vals: numpy.ndarray = [0.5])

Denoising with low-pass filter H_P.

Args:

f (np.ndarray): The noisy signal. f_true (np.ndarray): The true signal. p_choice (str): The choice of matrix P. component (str): The component of the signal. mu_vals (np.ndarray, optional): Regularization parameters. Defaults to [0.5].

plot_desired_frequency_response(p_choice: str)

Plot the desired frequency response of the filter.

Args:

p_choice (str): The choice of matrix P.

class pytspl.filters.GridBasedFilterDesign(simplicial_complex: pytspl.simplicial_complex.SimplicialComplex)

Bases: pytspl.filters.base_filter.BaseFilter

Module for grid-based filter design inheriting from the BaseFilter class.

_sample_grid_points(P: numpy.ndarray, num_of_samples: int) → numpy.ndarray

Sample M1 and M2 grid points uniformly in the interval for the smallest set value greater than 0 as the lower bound.

Args:

P (np.ndarray): The matrix P. num_of_samples (int): Number of samples to take.

Returns:

np.ndarray: Sampled grid points.

static _compute_frequency_response_hp(eigenvalue: float, mu: float = 0.5) → float

Compute the frequency response of the low-pass filter (Hp) for the given eigenvalue.

Args:

eigenvalue (float): The eigenvalue. mu (float): Damping factor.

Returns:

float: Frequency response.

_compute_sampled_continuous_freq_response(P: numpy.ndarray, num_of_samples: int, mu: float = 0.5) → tuple

Compute the continuous frequency response for sampled eigenvalues.

Args:

P (np.ndarray): The matrix P. num_of_samples (int): Number of samples to take. mu (float): Damping factor.

Returns:

np.ndarray: Sampled frequency responses. np.ndarray: Sampled eigenvalues.

_apply_filter(f: numpy.ndarray, f_true: numpy.ndarray, P: scipy.sparse.csr_matrix, alpha: numpy.ndarray, U: numpy.ndarray, eigenvals: numpy.ndarray, L: int) → tuple

Apply the filter to the input signal.

Args:

f (np.ndarray): The input signal. f_true (np.ndarray): The true signal. P (csr_matrix): The matrix P. alpha (np.ndarray): The filter coefficients. U (np.ndarray): The eigenvectors. eigenvals (np.ndarray): The eigenvalues. L (int): The filter size.

Returns:

np.ndarray: The filter. np.ndarray: The estimated signal. np.ndarray: The frequency responses. np.ndarray: The errors in the extracted component.

denoise(f: numpy.ndarray, f_true: numpy.ndarray, p_choice: str, L: int, mu: float = 0.5) → None

Build a low-pass filter H_P to denoise the input signal.

Args:

f (np.ndarray): The noisy signal. f_true (np.ndarray): The true signal. p_choice (str): The choice of matrix P. L (int): The filter size. mu (float): The damping factor.

subcomponent_extraction(f: numpy.ndarray, component: str, p_choice: str, L: int, num_of_samples: int = 10, mu: float = 0.5, cut_off_frequency: float = 0.01, steep: int = 100) → None

Subcomponent extraction using the grid-based simplicial filter H_1.

Args:

f (np.ndarray): The noisy signal. component (str): The component to extract. p_choice (str): The choice of matrix P. L (int): The filter size. num_of_samples (int, Optional): Number of eigenvalues to sample. Default is 10. mu (float, Optional): The damping factor. Default is 0.5. cut_off_frequency (float, Optional): The cut-off frequency. Default is 0.01. steep (int, Optional): The steepness of the logistic function. Default is 100.

general_filter(f: numpy.ndarray, L1: int, L2: int) → tuple

Apply a general filter H1 with L1 != L2 = L and α != β.

Args:

f (np.ndarray): The signal to be filtered. L1 (int): The size of the filter for the gradient extraction. L2 (int): The size of the filter for the curl extraction.

Returns:

np.ndarray: The estimated harmonic component. np.ndarray: The estimated curl component. np.ndarray: The estimated gradient component.

class pytspl.filters.LSFilterDesign(simplicial_complex: pytspl.simplicial_complex.SimplicialComplex)

Bases: pytspl.filters.base_filter.BaseFilter

Module for LS filter design inheriting from the BaseFilter class.

_apply_filter(f: numpy.ndarray, f_true: numpy.ndarray, lap_matrix: scipy.sparse.csr_matrix, U: numpy.ndarray, eigenvals: numpy.ndarray, alpha: numpy.ndarray, L: int) → tuple

Apply the filter to the signal using a type of the laplacian matrix.

Args:

f (np.ndarray): The noisy signal to be filtered. f_true (np.ndarray): The true signal. lap_matrix (csr_matrix): The laplacian matrix. It can be the Hodge Laplacian matrix, the upper or lower laplacian matrix. U (np.ndarray): The eigenvectors of the laplacian matrix. eigenvals (np.ndarray): The eigenvalues of the laplacian matrix. alpha (np.ndarray): The coefficients of the filter. L (int): The size of the filter.

Returns:

np.ndarray: The estimated filter. np.ndarray: The estimated signal. np.ndarray: The frequency response of the filter. np.ndarray: The error per filter size.

subcomponent_extraction_type_one(f: numpy.ndarray, component: str, L: int) → None

LS based filter design for subcomponent extraction using the Hodge Laplacian matrix (L1) - type one.

In this case, we will use the Hodge Laplacian matrix L1 = L2 = L and α = β.

Hk = sum(l=0, L) h_l * L^l

Args:

f (np.ndarray): The signal to be filtered. component (str): The component to be extracted. L (int): The size of the filter.

subcomponent_extraction_type_two(f: numpy.ndarray, component: str, L: int, tolerance: float = 1e-06) → None

LS based filter design for subcomponent extraction using the upper or lower Laplacian matrix (L1 or L2) - type two.

In this case: - The solution will have zero coefficients on the α for curl extraction (L1 = 0) - The solution will have zero coefficients on the β for gradient extraction (L2 = 0)

Therefore, we will only consider the upper or lower part of the filter to do so.

Args:

f (np.ndarray): The signal to be filtered. L (int): The size of the filter. component (str): The component to be extracted. tolerance (float, optional): The tolerance to consider the eigenvalues as unique. Defaults to 1e-6.

general_filter(f: numpy.ndarray, L1: int, L2: int, tolerance: float = 0.001) → numpy.ndarray

Denoising by a general filter H1 with L1 != L2 = L and α != β.

Args:

f (np.ndarray): The signal to be filtered. L1 (int): The size of the filter for the gradient extraction. L2 (int): The size of the filter for the curl extraction. tolerance (float, optional): The tolerance to consider the eigenvalues as unique. Defaults to 1e-3.

Returns:

np.ndarray: The estimated harmonic component. np.ndarray: The estimated curl component. np.ndarray: The estimated gradient component.

class pytspl.filters.SimplicialTrendFilter(simplicial_complex: pytspl.simplicial_complex.simplicial_complex.SimplicialComplex)

Bases: pytspl.filters.base_filter.BaseFilter

Simplicial trend filter class for denoising and interpolation. Inherits from the filter base class.

history

components

set_history(filter: numpy.ndarray, frequency_responses: numpy.ndarray, component_flow: numpy.ndarray, errors: numpy.ndarray, correlations: numpy.ndarray) → None

Set the history of the filter.

Args:

filter (np.ndarray, None): The filter. frequency_responses (np.ndarray): The frequency responses. component_flow (np.ndarray): The component flow. errors (np.ndarray): The errors. correlations (np.ndarray): The correlations.

static _solver(num_edges: int, f_noisy: numpy.ndarray, shift_operator: numpy.ndarray, mu: float = 0.5)

Solve the SFT equation.

static _calculate_correlation(A: numpy.ndarray, B: numpy.ndarray) → numpy.ndarray

Compute the correlation between two arrays.

static _calculate_snr(snr_db: numpy.ndarray) → numpy.ndarray

Calculate the signal to noise ratio (SNR).

get_power_noise(flow: numpy.ndarray, snr_db: numpy.ndarray) → tuple

Get the power noise and the signal to noise ratio.

Args:

flow (np.ndarray): The flow of the simplicial complex. snr_db (np.ndarray): The signal to noise ratio in dB.

Returns:

tuple: The power noise and the signal to noise ratio.

get_shift_operator(component: str, order: int) → numpy.ndarray

Return the shift operator for the divergence or the curl using the specified order of STF.

Args:

component (str): The component to regularize. Choose between ‘divergence’ and ‘curl’. order (int): The order of the STF filter.

Returns:

np.ndarray: The shift operator.

denoising_l2_regularizer(flow: numpy.ndarray, component: str, num_realizations: int, snr_db: numpy.ndarray, mu: float = 0.5) → None

Simplicial trend filter developed by regularizing the the total divergence and curl via their l2 norm for denoising.

Args:

flow (np.ndarray): The flow of the simplicial complex. component (str): The component to regularize. Choose between ‘divergence’ and ‘curl’. num_realizations (int): The number of realizations. snr_db (np.ndarray): The signal to noise ratio in dB. mu (float, optional): The regularization parameter. Defaults to 0.5.

Raises:

ValueError: If the component is not ‘divergence’ or ‘curl’.

denoising_l1_regularizer(flow: numpy.ndarray, component: str, num_realizations: int, snr_db: numpy.ndarray, order: int = 0, regularization: float = 0.5) → None

Simplicial trend filter developed by regularizing the the total divergence and curl via their l1 norm for denoising.

Args:

flow (np.ndarray): The flow of the simplicial complex. noisy_flow (np.ndarray): The noisy flow of the simplicial complex. shift_operator (np.ndarray): The shift operator used in the optimization problem. component (str): The component to regularize. Choose between ‘divergence’ and ‘curl’. num_realizations (int): The number of realizations. snr_db (np.ndarray): The signal to noise ratio in dB. order (int, optional): The order of the STF filter. Defaults to 0. regularization (float, optional): The regularization parameter alpha/beta. Defaults to 0.5.

Raises:

ValueError: If the component is not ‘divergence’ or ‘curl’.

interpolation_l1_regularizer(flow: numpy.ndarray, component: str, ratio: int, num_realizations: int, order: int = 0, regularization: float = 0.5) → None

Simplicial trend filter developed by regularizing the the total divergence and curl via their l1 norm for interpolation.

Args:

flow (np.ndarray): The flow of the simplicial complex. component (str): The component to regularize. Choose between ‘divergence’ and ‘curl’. ratio (int): The ratio of the number of nonzero nodes. num_realizations (int): The number of realizations. order (int, optional): The order of the STF filter. Defaults to 0. regularization (float, optional): The regularization parameter alpha/beta. Defaults to 0.5.

Raises:

ValueError: If the component is not ‘divergence’ or ‘curl’.