endaq.calc

endaq.calc is a module comprising a collection of common calculations for vibration analysis. It leverages the standard Python scientific stack (NumPy, SciPy, Pandas) in order to enable engineers to perform domain-specific calculations in a few lines of code, without having to first master Python and its scientific stack in their entireties.

endaq.calc.filters

endaq.calc.filters.band_limited_noise(min_freq=0.0, max_freq=None, duration=1.0, sample_rate=1000.0, norm='peak')

Generate a time series with noise in a defined frequency range.

Parameters

  • min_freq (float) – minimum frequency (Hz) where noise starts, default to 0

  • max_freq (float) – maximum frequency (Hz) where noise ends, default to 1/2 the sample rate

  • duration (float) – the duration of the time series returned, in seconds

  • sample_rate (float) – sample rate (Hz) of the time series

  • norm (typing.Literal[('rms', 'peak')]) – how to normalize the amplitude so that one of the following is equal to 1: * “rms” - root mean square * “peak” - peak value, default

Returns

a dataframe of the generated time series

Return type

pd.DataFrame

See also

endaq.calc.filters.bessel(df, low_cutoff=1.0, high_cutoff=None, half_order=3, tukey_percent=0.0, norm='mag')

Apply a lowpass and/or a highpass Bessel filter to an array.

This function uses Bessel filter designs, and implements the filter(s) as bi-directional digital biquad filters, split into second-order sections.

Parameters

  • df (pd.DataFrame) – the input data; cutoff frequencies are relative to the timestamps in df.index

  • low_cutoff (Optional[float]) – the low-frequency cutoff, if any; frequencies below this value are rejected, and frequencies above this value are preserved

  • high_cutoff (Optional[float]) – the high-frequency cutoff, if any; frequencies above this value are rejected, and frequencies below this value are preserved

  • half_order (int) – half of the order of the filter; higher orders provide more aggressive stopband reduction

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

  • norm (typing.Literal[('phase', 'delay', 'mag')]) – how to normalize relative to the critical frequency: * “phase” - “phase-matched” case which is the default in SciPy & MATLAB * “delay” - the “natural” type obtained by solving Bessel polynomials * “mag” - gain magnitude is -3 dB at the cutoff frequency, default for this implementation to match Butterworth

Returns

the filtered data

Return type

pd.DataFrame

See also

endaq.calc.filters.butterworth(df, low_cutoff=1.0, high_cutoff=None, half_order=3, tukey_percent=0.0)

Apply a lowpass and/or a highpass Butterworth filter to an array.

This function uses Butterworth filter designs, and implements the filter(s) as bi-directional digital biquad filters, split into second-order sections.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data; cutoff frequencies are relative to the timestamps in df.index

  • low_cutoff (Optional[float]) – the low-frequency cutoff, if any; frequencies below this value are rejected, and frequencies above this value are preserved

  • high_cutoff (Optional[float]) – the high-frequency cutoff, if any; frequencies above this value are rejected, and frequencies below this value are preserved

  • half_order (int) – half of the order of the filter; higher orders provide more aggressive stopband reduction

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

Returns

the filtered data

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.filters.cheby1(df, low_cutoff=1.0, high_cutoff=None, half_order=3, tukey_percent=0.0, rp=3.0)

Apply a lowpass and/or a highpass Chebyshev type I filter to an array.

This function uses Chebyshev type I filter designs, and implements the filter(s) as bi-directional digital biquad filters, split into second-order sections.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data; cutoff frequencies are relative to the timestamps in df.index

  • low_cutoff (Optional[float]) – the low-frequency cutoff, if any; frequencies below this value are rejected, and frequencies above this value are preserved

  • high_cutoff (Optional[float]) – the high-frequency cutoff, if any; frequencies above this value are rejected, and frequencies below this value are preserved

  • half_order (int) – half of the order of the filter; higher orders provide more aggressive stopband reduction

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

  • rp (float) – the maximum ripple allowed in the passband, specified in decibels

Returns

the filtered data

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.filters.cheby2(df, low_cutoff=1.0, high_cutoff=None, half_order=3, tukey_percent=0.0, rs=30.0)

Apply a lowpass and/or a highpass Chebyshev type II filter to an array.

This function uses Chebyshev type II filter designs, and implements the filter(s) as bi-directional digital biquad filters, split into second-order sections.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data; cutoff frequencies are relative to the timestamps in df.index

  • low_cutoff (Optional[float]) – the low-frequency cutoff, if any; frequencies below this value are rejected, and frequencies above this value are preserved

  • high_cutoff (Optional[float]) – the high-frequency cutoff, if any; frequencies above this value are rejected, and frequencies below this value are preserved

  • half_order (int) – half of the order of the filter; higher orders provide more aggressive stopband reduction

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

  • rs (float) – the minimum attenuation allowed in the stopband, specified in decibels

Returns

the filtered data

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.filters.ellip(df, low_cutoff=1.0, high_cutoff=None, half_order=3, tukey_percent=0.0, rp=3.0, rs=30.0)

Apply a lowpass and/or a highpass Elliptic filter to an array.

This function uses Elliptic filter designs, and implements the filter(s) as bi-directional digital biquad filters, split into second-order sections.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data; cutoff frequencies are relative to the timestamps in df.index

  • low_cutoff (Optional[float]) – the low-frequency cutoff, if any; frequencies below this value are rejected, and frequencies above this value are preserved

  • high_cutoff (Optional[float]) – the high-frequency cutoff, if any; frequencies above this value are rejected, and frequencies below this value are preserved

  • half_order (int) – half of the order of the filter; higher orders provide more aggressive stopband reduction

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

  • rp (float) – the maximum ripple allowed in the passband, specified in decibels

  • rs (float) – the minimum attenuation allowed in the stopband, specified in decibels

Returns

the filtered data

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.filters.rolling_mean(df, duration=5.0)

Remove the rolling mean of an input time series dataframe

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • duration (float) – the rolling window size in seconds to use - if None is given, the entire mean is removed

Returns

a dataframe of the filtered data

Return type

pandas.core.frame.DataFrame

endaq.calc.integrate

endaq.calc.integrate.integrals(df, n=1, zero='start', highpass_cutoff=None, tukey_percent=0.0)

Calculate n integrations of the given data.

Parameters

  • df (pandas.core.frame.DataFrame) – the data to integrate, indexed with timestamps

  • n (int) – the number of integrals to calculate; defaults to 1

  • zero (Union[Literal['start', 'mean', 'median'], Callable]) – the output quantity driven to zero by the integration constant; “start” (default) chooses an integration constant of -output[0], “mean” chooses -np.mean(output) & “median” chooses -np.median(output)

  • highpass_cutoff (Optional[float]) – the cutoff frequency for the initial highpass filter; this is used to remove artifacts caused by DC trends

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

Returns

a length n+1 list of the kth-order integrals from 0 to n (inclusive)

Return type

List[pandas.core.frame.DataFrame]

See also

endaq.calc.integrate.iter_integrals(df, zero='start', highpass_cutoff=None, tukey_percent=0.0)

Iterate over conditioned integrals of the given original data.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • zero (Union[Literal['start', 'mean', 'median'], Callable]) – the output quantity driven to zero by the integration constant; “start” (default) chooses an integration constant of -output[0], “mean” chooses -np.mean(output) & “median” chooses -np.median(output)

  • highpass_cutoff (Optional[float]) – the cutoff frequency of a preconditioning highpass filter; if None, no filter is applied

  • tukey_percent (float) – the alpha parameter of a preconditioning Tukey filter; if 0 (default), no filter is applied

Returns

an iterable over the data’s successive integrals; the first item is the preconditioned input data

Return type

Iterable[pandas.core.frame.DataFrame]

See also

endaq.calc.psd

endaq.calc.psd.differentiate(df, n=1.0)

Perform time-domain differentiation on periodogram data.

Parameters

  • df (pandas.core.frame.DataFrame) – a periodogram

  • n (float) – the time derivative order; negative orders represent integration

Returns

a periodogram of the time-differentiated data

Return type

pandas.core.frame.DataFrame

endaq.calc.psd.to_jagged(df, freq_splits, agg='mean')

Calculate a periodogram over non-uniformly spaced frequency bins.

Parameters

  • df (pandas.core.frame.DataFrame) – the returned values from endaq.calc.psd.welch()

  • freq_splits (numpy.array) – the boundaries of the frequency bins; must be strictly increasing

  • agg (Union[Literal['mean', 'sum'], Callable[[numpy.ndarray, int], float]]) – the method for aggregating values into bins; ‘mean’ preserves the PSD’s area-under-the-curve, ‘sum’ preserves the PSD’s “energy”

Returns

a periodogram with the given frequency spacing

Return type

pandas.core.frame.DataFrame

endaq.calc.psd.to_octave(df, fstart=1.0, octave_bins=12.0, **kwargs)

Calculate a periodogram over log-spaced frequency bins.

Parameters

  • df (pandas.core.frame.DataFrame) – the returned values from endaq.calc.psd.welch()

  • fstart (float) – the first frequency bin, in Hz; defaults to 1 Hz

  • octave_bins (float) – the number of frequency bins in each octave; defaults to 12

  • kwargs – other parameters to pass directly to to_jagged()

Returns

a periodogram with the given logarithmic frequency spacing

Return type

pandas.core.frame.DataFrame

endaq.calc.psd.vc_curves(accel_psd, fstart=1.0, octave_bins=12.0)

Calculate Vibration Criterion (VC) curves from an acceleration periodogram.

Parameters

  • accel_psd (pandas.core.frame.DataFrame) – a periodogram of the input acceleration

  • fstart (float) – the first frequency bin

  • octave_bins (float) – the number of frequency bins in each octave; defaults to 12

Returns

the Vibration Criterion (VC) curve of the input acceleration

Return type

pandas.core.frame.DataFrame

endaq.calc.psd.welch(df, bin_width=1.0, scaling=None, **kwargs)

Perform scipy.signal.welch with a specified frequency spacing.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • bin_width (float) – the desired width of the resulting frequency bins, in Hz; defaults to 1 Hz

  • scaling (Optional[Literal[None, 'density', 'spectrum', 'parseval']]) – the scaling of the output; “density” & “spectrum” correspond to the same options in scipy.signal.welch; “parseval” will maintain the “energy” between the input & output, s.t. welch(df, scaling="parseval").sum(axis="rows") is roughly equal to df.abs().pow(2).sum(axis="rows"); “unit” will maintain the units and scale of the input data.

  • kwargs – other parameters to pass directly to scipy.signal.welch

Returns

a periodogram

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.fft

endaq.calc.fft.aggregate_fft(df, **kwargs)

Calculate the FFT using scipy.signal.welch() with a specified frequency spacing. The data returned is in the same units as the data input.

Parameters

  • df – The input data

  • bin_width – The desired width of the resulting frequency bins, in Hz; defaults to 1 Hz

  • kwargs – Other parameters to pass directly to scipy.signal.welch()

Returns

A periodogram of the input data in the same units as the input.

See also

endaq.calc.fft.dct(df, nfft=None, norm=None, **kwargs)

Calculate the DCT of the data in df, using SciPy’s DCT method from scipy.fft.dct().

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • nfft (Optional[int]) – Length of the transformed axis of the output. If nfft is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

  • norm (Optional[Literal[None, 'unit', 'forward', 'ortho', 'backward']]) – Normalization mode. Default is “unit”, meaning a normalization of 2/n is applied on the forward transform, and a normalization of 1/2 is applied on the idct. The “unit” normalization means that the units of the FFT are the same as the units of the data put into it and that a sinusoid of amplitude A will peak with amplitude A in the frequency domain. “forward” instead applies a normalization of 1/n on the forward transforms and no normalization is applied on the idct. “backward” applies no normalization on the forward transform and 1/n on the backward. For norm="ortho", both directions are scaled by 1/sqrt(n).

  • kwargs – Further keywords passed to scipy.fft.dct(). Note that the nfft parameter of this function is passed to scipy.fft.dct() as n.

Returns

The DCT of each channel in df.

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.fft.dst(df, nfft=None, norm=None, **kwargs)

Calculate the DST of the data in df, using SciPy’s DST method from scipy.fft.dst().

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • nfft (Optional[int]) – Length of the transformed axis of the output. If nfft is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

  • norm (Optional[Literal[None, 'unit', 'forward', 'ortho', 'backward']]) – Normalization mode. Default is “unit”, meaning a normalization of 2/n is applied on the forward transform, and a normalization of 1/2 is applied on the idst. The “unit” normalization means that the units of the FFT are the same as the units of the data put into it and that a sinusoid of amplitude A will peak with amplitude A in the frequency domain. “forward” instead applies a normalization of 1/n on the forward transforms and no normalization is applied on the idst. “backward” applies no normalization on the forward transform and 1/n on the backward. For norm="ortho", both directions are scaled by 1/sqrt(n).

  • kwargs – Further keywords passed to scipy.fft.dst(). Note that the nfft parameter of this function is passed to scipy.fft.dst() as n.

Returns

The DST of each channel in df.

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.fft.fft(df, output=None, nfft=None, norm=None, optimize=True)

Perform the FFT of the data in df, using SciPy’s FFT method from scipy.fft.fft(). If the in df is all real, then the output will be symmetrical between positive and negative frequencies, and it is instead recommended that you use the endaq.calc.fft.fft() method.

Parameters

  • df (pandas.core.frame.DataFrame) – The input data

  • output (Optional[Literal[None, 'magnitude', 'angle', 'complex']]) – The type of the output of the FFT. Default is “magnitude”. “magnitude” will return the absolute value of the FFT, “angle” will return the phase angle in radians, “complex” will return the complex values of the FFT.

  • nfft (Optional[int]) – Length of the transformed axis of the output. If nfft is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

  • norm (Optional[Literal[None, 'unit', 'forward', 'ortho', 'backward']]) – Normalization mode. Default is “unit”, meaning a normalization of 2/n is applied on the forward transform, and a normalization of 1/2 is applied on the ifft. The “unit” normalization means that the units of the FFT are the same as the units of the data put into it and that a sinusoid of amplitude A will peak with amplitude A in the frequency domain. “forward” instead applies a normalization of 1/n on the forward transforms and no normalization is applied on the ifft. “backward” applies no normalization on the forward transform and 1/n on the backward. For norm="ortho", both directions are scaled by 1/sqrt(n).

  • optimize (bool) – If optimize is set to True, the length of the FFT will automatically be padded to a length which can be calculated more quickly. Default is True.

  • kwargs – Further keywords passed to scipy.fft.fft(). Note that the nfft parameter of this function is passed to scipy.fft.fft() as n.

Returns

The FFT of each channel in df.

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.fft.rfft(df, output=None, nfft=None, norm=None, optimize=True)

Perform the real valued FFT of the data in df, using SciPy’s RFFT method from scipy.fft.rfft().

Parameters

  • df (pandas.core.frame.DataFrame) – The input data

  • output (Optional[Literal[None, 'magnitude', 'angle', 'complex']]) – The type of the output of the FFT. Default is “magnitude”. “magnitude” will return the absolute value of the FFT, “angle” will return the phase angle in radians, “complex” will return the complex values of the FFT.

  • nfft (Optional[int]) – Length of the transformed axis of the output. If nfft is smaller than the length of the input, the input is cropped. If it is larger, the input is padded with zeros. If n is not given, the length of the input along the axis specified by axis is used.

  • norm (Optional[Literal[None, 'unit', 'forward', 'ortho', 'backward']]) – Normalization mode. Default is “unit”, meaning a normalization of 2/n is applied on the forward transform, and a normalization of 1/2 is applied on the ifft. The “unit” normalization means that the units of the FFT are the same as the units of the data put into it and that a sinusoid of amplitude A will peak with amplitude A in the frequency domain. “forward” instead applies a normalization of 1/n on the forward transforms and no normalization is applied on the ifft. “backward” applies no normalization on the forward transform and 1/n on the backward. For norm="ortho", both directions are scaled by 1/sqrt(n).

  • optimize (bool) – If optimize is set to True, the length of the FFT will automatically be padded to a length which can be calculated more quickly. Default is True.

  • kwargs – Further keywords passed to scipy.fft.rfft(). Note that the nfft parameter of this function is passed to scipy.fft.rfft() as n.

Returns

The RFFT of each channel in df.

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock

class endaq.calc.shock.HalfSineWavePulse(amplitude, duration)

The output data type for enveloping_half_sine().

The significant data members are amplitude and duration, which can simply be unpacked as if from a plain tuple:

ampl, T = enveloping_half_sine(df_pvss)

However, users can also elect to use the other methods of this class to generate other kinds of outputs.

Note

This class is not intended to be instantiated manually.

to_time_series(tstart=None, tstop=None, dt=None, tpulse=None)

Generate a time-series of the half-sine pulse.

Parameters

  • tstart (Optional[float]) – the starting time of the resulting waveform; if None (default), the range starts at tpulse

  • tstop (Optional[float]) – the ending time of the resulting waveform; if None (default), the range ends at tpulse + duration

  • dt (Optional[float]) – the sampling period of the resulting waveform; defaults to 1/20th of the pulse duration

  • tpulse (Optional[float]) –

    the starting time of the pulse within the resulting waveform; if None (default), the pulse starts at either:

    • tstart, if provided

    • tstop - self.duration.max()), if tstop is provided

    • 0.0 otherwise

Returns

a time-series of the half-sine pulse

Return type

pandas.core.frame.DataFrame

endaq.calc.shock.absolute_acceleration(accel, omega, damp=0.0)

Calculate the absolute acceleration for a SDOF system.

The absolute acceleration follows the transfer function:

H(s) = L{x”(t)}(s) / L{y”(t)}(s) = X(s)/Y(s)

for the PDE:

x” + (2ζω)x’ + (ω²)x = (2ζω)y’ + (ω²)y

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • omega (float) – the natural frequency ω of the SDOF system

  • damp (float) – the damping coefficient ζ of the SDOF system

Returns

the absolute acceleration x” of the SDOF system

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock.enveloping_half_sine(pvss, damp=0.0)

Characterize a half-sine pulse whose PVSS envelopes the input.

Parameters

  • pvss (pandas.core.frame.DataFrame) – the PVSS to envelope

  • damp (float) – the damping factor used to generate the input PVSS

Returns

a tuple of amplitudes and periods, each pair of which describes a half-sine pulse

Return type

endaq.calc.shock.HalfSineWavePulse

See also

Pseudo Velocity Shock Spectrum Rules For Analysis Of Mechanical Shock, Howard A. Gaberson

endaq.calc.shock.pseudo_velocity(accel, omega, damp=0.0)

Calculate the pseudo-velocity for a SDOF system.

The pseudo-velocity follows the transfer function:

H(s) = L{ωz(t)}(s) / L{y”(t)}(s) = (ω/s²)(Z(s)/Y(s))

for the PDE:

z” + (2ζω)z’ + (ω²)z = -y”

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • omega (float) – the natural frequency ω of the SDOF system

  • damp (float) – the damping coefficient ζ of the SDOF system

Returns

the pseudo-velocity of the SDOF system

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock.relative_displacement(accel, omega, damp=0.0)

Calculate the relative displacement for a SDOF system.

The relative displacement follows the transfer function:

H(s) = L{z(t)}(s) / L{y”(t)}(s) = (1/s²)(Z(s)/Y(s))

for the PDE:

z” + (2ζω)z’ + (ω²)z = -y”

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • omega (float) – the natural frequency ω of the SDOF system

  • damp (float) – the damping coefficient ζ of the SDOF system

Returns

the relative displacement z of the SDOF system

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock.relative_displacement_static(accel, omega, damp=0.0)

Calculate the relative displacement expressed as equivalent static acceleration for a SDOF system.

The relative displacement as static acceleration follows the transfer function:

H(s) = L{ω²z(t)}(s) / L{y”(t)}(s) = (ω²/s²)(Z(s)/Y(s))

for the PDE:

z” + (2ζω)z’ + (ω²)z = -y”

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • omega (float) – the natural frequency ω of the SDOF system

  • damp (float) – the damping coefficient ζ of the SDOF system

Returns

the relative displacement of the SDOF system expressed as equivalent static acceleration

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock.relative_velocity(accel, omega, damp=0.0)

Calculate the relative velocity for a SDOF system.

The relative velocity follows the transfer function:

H(s) = L{z’(t)}(s) / L{y”(t)}(s) = (1/s)(Z(s)/Y(s))

for the PDE:

z” + (2ζω)z’ + (ω²)z = -y”

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • omega (float) – the natural frequency ω of the SDOF system

  • damp (float) – the damping coefficient ζ of the SDOF system

Returns

the relative velocity z’ of the SDOF system

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.shock.shock_spectrum(accel, freqs, damp=0.0, mode='srs', two_sided=False, aggregate_axes=False)

Calculate the shock spectrum of an acceleration signal.

Parameters

  • accel (pandas.core.frame.DataFrame) – the absolute acceleration y”

  • freqs (numpy.ndarray) – the natural frequencies across which to calculate the spectrum

  • damp (float) – the damping coefficient ζ, related to the Q-factor by ζ = 1/(2Q); defaults to 0

  • mode (Literal['srs', 'pvss']) –

    the type of spectrum to calculate:

    • ’srs’ (default) specifies the Shock Response Spectrum (SRS)

    • ’pvss’ specifies the Pseudo-Velocity Shock Spectrum (PVSS)

  • two_sided (bool) – whether to return for each frequency: both the maximum negative and positive shocks (True), or simply the maximum absolute shock (False; default)

  • aggregate_axes (bool) – whether to calculate the column-wise resultant (True) or calculate spectra along each column independently (False; default)

Returns

the shock spectrum

Return type

pandas.core.frame.DataFrame

See also

endaq.calc.stats

endaq.calc.stats.L2_norm(array, axis=None, keepdims=False)

Compute the L2 norm (a.k.a. the Euclidean Norm).

Parameters

  • array (np.ndarray) – the input array

  • axis (Union[None, typing.SupportsIndex, Sequence[typing.SupportsIndex]]) – the axis/axes along which to aggregate; if None (default), the L2 norm is computed along the flattened array

  • keepdims (bool) – if True, the axes which are reduced are left in the result as dimensions of size one; if False (default), the reduced axes are removed

Returns

an array containing the computed values

Return type

np.ndarray

endaq.calc.stats.max_abs(array, axis=None, keepdims=False)

Compute the maximum of the absolute value of an array.

This function should be equivalent to, but generally use less memory than np.amax(np.abs(array)).

Specifically, it generates the absolute-value maximum from np.amax(array) and -np.amin(array). Thus instead of allocating space for the intermediate array np.abs(array), it allocates for the axis-collapsed smaller arrays np.amax(array) & np.amin(array).

Note

This method does not work on complex-valued arrays.

Parameters

  • array (np.ndarray) – the input data

  • axis (Union[None, typing.SupportsIndex, Sequence[typing.SupportsIndex]]) – the axis/axes along which to aggregate; if None (default), the absolute maximum is computed along the flattened array

  • keepdims (bool) – if True, the axes which are reduced are left in the result as dimensions with size one; if False (default), the reduced axes are removed

Returns

an array containing the computed values

Return type

np.ndarray

endaq.calc.stats.rms(array, axis=None, keepdims=False)

Calculate the root-mean-square (RMS) along a given axis.

Parameters

  • array (np.ndarray) – the input array

  • axis (Union[None, typing.SupportsIndex, Sequence[typing.SupportsIndex]]) – the axis/axes along which to aggregate; if None (default), the RMS is computed along the flattened array

  • keepdims (bool) – if True, the axes which are reduced are left in the result as dimensions with size one; if False (default), the reduced axes are removed

Returns

an array containing the computed values

Return type

np.ndarray

endaq.calc.stats.rolling_rms(df, window_len, *args, **kwargs)

Calculate a rolling root-mean-square (RMS) over a pandas DataFrame.

This function is equivalent to, but computationally faster than the following:

df.rolling(window_len).apply(endaq.calc.stats.rms)
Parameters

  • df (Union[pandas.core.frame.DataFrame, pandas.core.series.Series]) – the input data

  • window_len (int) – the length of the rolling window

  • args – the positional arguments to pass into df.rolling().mean

  • kwargs – the keyword arguments to pass into df.rolling().mean

Returns

the rolling-windowed RMS

Return type

Union[pandas.core.frame.DataFrame, pandas.core.series.Series]

See also

endaq.calc.utils

endaq.calc.utils.logfreqs(df, init_freq=None, bins_per_octave=12.0)

Calculate a sequence of log-spaced frequencies for a given dataframe.

Parameters

  • df (pandas.core.frame.DataFrame) – the input data

  • init_freq (Optional[float]) – the initial frequency in the sequence; if None (default), use the frequency corresponding to the data’s duration

  • bins_per_octave (float) – the number of frequencies per octave

Returns

an array of log-spaced frequencies

Return type

numpy.ndarray

endaq.calc.utils.resample(df, sample_rate=None)

Resample a dataframe to a desired sample rate (in Hz)

Parameters

  • df (pandas.core.frame.DataFrame) – The DataFrame to resample, indexed by time

  • sample_rate (Optional[float]) – The desired sample rate to resample the given data to. If one is not supplied, then it will use the same as it currently does, but make the time stamps uniformly spaced

Returns

The resampled data in a DataFrame

Return type

pandas.core.frame.DataFrame

endaq.calc.utils.sample_spacing(data, convert='to_seconds')

Calculate the average spacing between individual samples.

For time indices, this calculates the sampling period dt.

Parameters

  • data (Union[numpy.ndarray, pandas.core.frame.DataFrame]) – the input data; either a pandas DataFrame with the samples spaced along its index, or a 1D-array-like of sample times

  • convert (Literal[None, 'to_seconds']) – if “to_seconds” (default), convert any time objects into floating-point seconds

endaq.calc.utils.to_dB(data, reference, squared=False)

Scale data into units of decibels.

Decibels are a log-scaled ratio of some value against a reference; typically this is expressed as follows:

\[dB = 10 \log_{10}\left( \frac{x}{x_{\text{ref}}} \right)\]

By convention, “decibel” units tend to operate on units of power. For units that are proportional to power when squared (e.g., volts, amps, pressure, etc.), their “decibel” representation is typically doubled (i.e., \(dB = 20 \log_{10}(...)\)). Users can specify which scaling to use with the squared parameter.

Note

Decibels can NOT be calculated from negative values.

For example, to calculate dB on arbitrary time-series data, typically data is first aggregated via a total or a rolling RMS or PSD, and the non-negative result is then scaled into decibels.

Parameters

  • data (numpy.ndarray) – the input data

  • reference (float) – the reference value corresponding to 0dB

  • squared (bool) – whether the input data & reference value are pre-squared; defaults to False

See also

  • endaq.calc.stats.rms

  • endaq.calc.stats.rolling_rms

  • endaq.calc.psd.welch

previous

endaq.ide Usage Examples

next

endaq.calc Usage Examples