Filter Class Documentation

Introduction

The Filter class is designed to apply specific filtering algorithms to lidar data. It supports a range of filters including Savitzky-Golay, Hamming, and Blackman windows, among others. The class allows for the management of data inputs, altitude vector adjustments, and the application of calculated filters to the input data.

API

class SignalCreation.Treatment.Filter.Filter(filter_name, use_ndacc_resol_file=True, filenames_ndacc_resol=None, use_multiprocessing=True)

This class implements a filtering process for lidar signal data. It handles the application of various filter types to the data, such as Savitzky-Golay, Hamming, and Blackman windows among others.

Parameters:

filter_name (str)
use_ndacc_resol_file (bool)
filenames_ndacc_resol (dict | None)
use_multiprocessing (bool)

\* _filter_name

Name of the filter to be applied.

Type:: str

\* _coefficients

Dictionary to store coefficients for different number of coefficients.

Type:: dict

\* _altitude_vector

Vector of altitude measurements.

Type:: pint.Quantity or None

\* _nb_coefficients_over_altitude

DataArray storing number of coefficients per altitude.

Type:: xr.DataArray or None

\* _data_in

Input dataset before filtering.

Type:: xr.Dataset or None

\* _data_out

Output dataset after filtering.

Type:: xr.Dataset or None

\* _nf_ir

Number of impulse responses.

Type:: int

\* _nf_df

Number of transfer functions.

Type:: int

\* _ndacc_resolution_df

Dictionary storing resolutions for different transfer functions.

Type:: dict

\* _ndacc_transfer_function

Dictionary of transfer functions.

Type:: dict

\* _ndacc_resolution_ir

Dictionary storing resolutions for impulse responses.

Type:: dict

\* _ndacc_impulse_response

Dictionary of impulse responses.

Type:: dict

_nb_coeff_from_dial_poly(parameters)

Calculates the number of coefficients over altitude using a polynomial function derived from the DIAL method.

Parameters:: parameters (dict) – Parameters including polynomial function coefficients and altitude indexes.
Returns:: the parameters used
Return type:: dict

_nb_coeff_from_fixed_number_points(parameters)

Calculates the number of coefficients from fixed number of points specified in parameters.

Parameters:: parameters (dict) – Dictionary specifying the fixed number of points.

_nb_coeff_from_linear(parameters)

Calculates the number of coefficients over altitude using a linear regression.

Parameters:: parameters (dict) – Parameters from linear regression

_search_nf_max(method)

Searches for the maximum coefficient based on the specified method.

Parameters:: method (str) – Methodology to use, either ‘df’ (transfer function) or ‘ir’ (impulse response).
Returns:: The maximum coefficient based on the method.
Return type:: xr.DataArray

add_altitude_vector(alt, force_if_data_in_different=True, default_altitude_unit='m')

Adds or updates the altitude vector in the Filter class.

Parameters:

alt (np.ndarray, xr.DataArray, or pint.Quantity) – Altitude vector data.
force_if_data_in_different (bool) – Force update if incoming data differs from existing, default True.
default_altitude_unit (str) – Unit for altitude, defaults to ‘meters’.

add_data_in(data_in)

Adds input data to the Filter class. Initializes internal structures if data is present.

Parameters:: data_in (xr.DataArray or None) – Data to be added.

altitude_vector()

Returns the altitude vector if set; otherwise, returns None.

Returns:: Altitude vector or None if not set.
Return type:: pint.Quantity or None

apply(da=None, uncertainty_flag=False, resolution_unit='m')

Applies the filter to a xarray data array. Calculates uncertainty if specified.

Parameters:

da (xr.DataArray or None) – DataArray to filter (by default, uses internal data_in).
uncertainty_flag (bool) – True if uncertainty calculation is needed.
resolution_unit (str) – Unit of the resolution, default is meters.

Returns:

Filtered data as a new DataArray.

Return type:

xr.DataArray

static blackman(nb_coeff, fcut, *args, **kwargs)

Generates coefficients for a Blackman filter with a specified cutoff frequency.

Parameters:

nb_coeff (int) – Number of coefficients.
fcut (float) – Cutoff frequency.

Returns:

List of Blackman filter coefficients.

Return type:

list

static blackman_windows(nb_coeff, *args, **kwargs)

Generates coefficients for a Blackman window filter.

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of Blackman filter coefficients.
Return type:: list

calculate_coefficients(): Calculates the filter coefficients for each altitude based on the number of coefficients specified.

calculate_nb_coef_over_altitude(method, parameters=None)

Calculates the number of coefficients over altitude based on the given method and parameters.

Parameters:

method (str) – Method for calculating the number of coefficients.
parameters (dict or None) – Parameters for the calculation method.

Return type:

dict | None

data_in()

Return data_in

Returns:: data_in
Return type:: xr.Dataset or None

filter_name()

Returns the name of the filter

Returns:: The name of the filter
Return type:: str

get_filter_coefficients(nb_coef, parameters=None)

Returns a set of filter coefficients for use in a convolution process based on the number of coefficients and optionally specified parameters.

Parameters:

nb_coef (int) – Number of coefficients for the filter.
parameters (dict or None) – Additional parameters for coefficient calculation (optional).

Returns:

List of filter coefficients.

Return type:

list

get_ndacc_resolution(method=None, output=None)

Gets the resolution based on the NDACC methodology, optionally returning the transfer function or impulse response.

Parameters:

method (str or None) – Methodology to use, e.g., ‘ir’ (impulse response) or ‘df’ (transfer function).
output (str or None) – Output type, e.g., ‘resolution’, ‘matrix’, or ‘all’.

Returns:

Resolution data array or a tuple of data arrays based on the output choice.

Return type:

xr.DataArray or tuple[xr.DataArray, xr.DataArray]

get_resol_init_matlab_software()

Calculates the resolution of the filter based on the initial function in Matlab software.

Returns:: Final resolution after the filter application.
Return type:: xr.DataArray

get_resolution_over_altitude(method, output=None)

Retrieves resolution over altitude for the specified method and output type.

Parameters:

method (str) – Methodology to use, e.g., ‘ir’ (impulse response) or ‘df’ (transfer function).
output (str or None) – Output type, e.g., ‘resolution’, ‘matrix’, or ‘all’.

Returns:

Resolution data array or a tuple of data arrays based on the output choice.

Return type:

xr.DataArray or tuple[xr.DataArray, xr.DataArray]

static hamming(nb_coeff, fcut, *args, **kwargs)

Generates coefficients for a Hamming filter with a specified cutoff frequency.

Parameters:

nb_coeff (int) – Number of coefficients.
fcut (float) – Cutoff frequency.

Returns:

List of Hamming filter coefficients.

Return type:

list

static hamming_windows(nb_coeff, *args, **kwargs)

Generates coefficients for a Hamming window filter.

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of Hamming filter coefficients.
Return type:: list

static hann(nb_coeff, fcut, *args, **kwargs)

Generates coefficients for a Hann filter with a specified cutoff frequency.

Parameters:

nb_coeff (int) – Number of coefficients.
fcut (float) – Cutoff frequency.

Returns:

List of Hann filter coefficients.

Return type:

list

static hann_windows(nb_coeff, *args, **kwargs)

Generates coefficients for a Hann window filter.

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of Hann filter coefficients.
Return type:: list

static ideal_trunc(nb_coeff, fcut, *args, **kwargs)

Generates coefficients for an ideal truncation filter with a specified cutoff frequency.

Parameters:

nb_coeff (int) – Number of coefficients.
fcut (float) – Cutoff frequency.

Returns:

List of ideal truncation filter coefficients.

Return type:

list

static lsq1(nb_coeff, *args, **kwargs)

Generates coefficients for a least squares filter with a flat window (simple averaging).

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of filter coefficients, all equal, representing an average.
Return type:: list

nb_coefficients_over_altitude()

Returns the number of coefficients over altitude.

Returns:: DataArray of coefficients or None if not set.
Return type:: xr.DataArray or None

ndacc_resol_data_read(filename=None)

Read ndacc resol data previously calculated and insert data into filter class.

Returns:
Parameters:: filename (dict | None)

ndacc_resol_data_save()

Write data from NDACC resolution in NetCDF file

Returns:: the file created
Return type:: list

resolution_ndacc(method=None)

Calculates the resolution of the filtered data based on NDACC-approved methods.

Parameters:: method (str or None) – Methodology to use, either ‘df’ (transfer function) or ‘ir’ (impulse response).

static savitzky_golay(nb_coeff, *args, **kwargs)

Generates Savitzky-Golay filter coefficients.

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of filter coefficients.
Return type:: list

static savitzky_golay_derivative(nb_coeff, *args, **kwargs)

Generates Savitzky-Golay filter coefficients.

Parameters:: nb_coeff (int) – Number of coefficients.
Returns:: List of filter coefficients.
Return type:: list

SignalCreation.Treatment.Filter._calcul_impulse_response(coef, nf=None, type_tf=None)

Calculates the impulse response for a given set of coefficients and a specified type of filter.

Parameters:

coef (np.ndarray) – Coefficients of the filter.
nf (int or None) – Number of data points for the calculation (optional).
type_tf (str or None) – Type of filter, either ‘low_pass’ or ‘derivative’.

Returns:

Array representing the impulse response.

Return type:

np.ndarray

SignalCreation.Treatment.Filter._calcul_transfer_function(frequency, coef, nb_values_max=None, type_tf=None)

Calculates the transfer function for a given set of coefficients and frequencies.

Parameters:

frequency (np.ndarray) – Array of frequencies.
coef (np.ndarray) – Coefficients of the filter.
nb_values_max (int or None) – Maximum number of values to calculate (optional).
type_tf (str or None) – Type of filter, either ‘low_pass’ or ‘derivative’.

Returns:

Array representing the transfer function values.

Return type:

np.ndarray

SignalCreation.Treatment.Filter._dirac(nf)

Creates a Dirac delta function with an amplitude of 1 at the center.

Parameters:: nf (int or float) – Number of data points.
Returns:: Array representing the Dirac delta function.
Return type:: np.ndarray

SignalCreation.Treatment.Filter._eq_transfer_function_derivative_filter(coef, frequency, m, j)

Equation for calculating derivative filter transfer function component.

Parameters:

coef (np.ndarray) – Coefficients of the filter.
frequency (np.ndarray) – Array of frequencies.
m (int) – Midpoint index for the coefficients.
j (int) – Current index in the frequency array.

Returns:

Calculated value of the derivative filter at the current frequency.

Return type:

float