Reference on kuibit.frequencyseries

The frequencyseries module provides a representation of frequency series.

FrequencySeries can be evenly or unevenly sampled, real or complex. They support all the mathematical operations and operators you may expect, and have additional methods, which include ones for taking derivatives, integrals, apply windows, smooth the signal, take inverse Fourier transform, and more. Most of these methods are available in two flavors: those that return a new FrequencySeries, and those which modify the object in place. The latter have names with imperative verbs.

As in TimeSeries, FrequencySeries are derived from the BaseSeries, which in turn is derived from the abstract class BaseNumerical. Some of the capabilities of FrequencySeries (e.g., overloading the mathematical operators) are implemented in the parent classes.

Additionally, two functions are defined in this module load_FrequencySeries() and load_noise_curve(). Both loads FrequencySeries from a text file, but load_noise_curve() is a simpler interface for real-valued signals.

class kuibit.frequencyseries.FrequencySeries(f, fft, guarantee_f_is_monotonic=False)[source]

Class representing a Fourier spectrum.

Variables:

  • f (1D NumPy array or float) – Frequency

  • fft (1D NumPy array or float) – Fourier transform

Create a FrequencySeries providing frequencies and the value at those frequencies.

It is your duty to make sure everything makes sense!

When guarantee_f_is_monotonic is True, no checks will be perform to make sure that f is monotonically increasing (increasing performance). This should is used internally whenever a new series is returned from self (since we have already checked that f is good.) or in performance critical routines.

Parameters:

  • f (1D NumPy array or float) – Frequencies.

  • fft (1D NumPy array or float) – Fourier transform.

  • guarantee_f_is_monotonic (bool) – If true, it will be assumes that f is monotonically increasing.

abs_max()

Return the maximum of the absolute value

abs_min()

Return the minimum of the absolute value

abs_nanmax()

Return the maximum of the absolute value ignoring NaNs

abs_nanmin()

Return the minimum of the absolute value ignoring NaNs

property amp

Return the amplitude of frequencies.

Returns:

Amplitude of the series.

Return type:

1d NumPy array

property amplitude

Return the amplitude of frequencies.

Returns:

Amplitude of the series.

Return type:

1d NumPy array

band_pass(fmin, fmax)[source]

Remove all the frequencies below fmin and above fmax.

Parameters:

  • fmin (float) – Minimum frequency.

  • fmax (float) – Maximum frequency.

band_passed(fmin, fmax)[source]

Remove frequencies outside the given range fmin, fmax.

Parameters:

  • fmin (float) – Minimum frequency.

  • fmax (float) – Maximum frequency.

clip(init=None, end=None)

Remove data outside the the interval [init, end]. If init or end are not specified or None, it does not remove anything from this side.

Parameters:

  • init (float or None) – Data with x <= init will be removed.

  • end (float or None) – Data with x >= end will be removed.

clipped(init=None, end=None)

Return a series with data removed outside the interval [init, end]. If init or end are not specified or None, it does not remove anything from this side.

Parameters:

  • init (float or None) – Data with x <= init will be removed.

  • end (float or None) – Data with x >= end will be removed.

Returns:

Series with enforced minimum and maximum

Return type:

BaseSeries or derived class

copy()

Return a deep copy.

Returns:

Deep copy of the series.

Return type:

BaseSeries or derived class

crop(init=None, end=None)

Remove data outside the the interval [init, end]. If init or end are not specified or None, it does not remove anything from this side.

Parameters:

  • init (float or None) – Data with x <= init will be removed.

  • end (float or None) – Data with x >= end will be removed.

cropped(init=None, end=None)

Return a series with data removed outside the interval [init, end]. If init or end are not specified or None, it does not remove anything from this side.

Parameters:

  • init (float or None) – Data with x <= init will be removed.

  • end (float or None) – Data with x >= end will be removed.

Returns:

Series with enforced minimum and maximum

Return type:

BaseSeries or derived class

property df

Return the spacing (delta_f) if the series is regularly sampled, otherwise raise error.

Returns:

Frequency spacing (delta_f).

Return type:

float

differentiate(order=1)

Differentiate with the numerical order-differentiation.

The optional parameter order specifies the order of the derivative.

The derivative is calulated as centered differencing in the interior and one-sided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.

Parameters:

order (int) – Order of derivative (e.g. 2 = second derivative).

differentiated(order=1)

Return a series that is the numerical order-differentiation of the present series.

The optional parameter order specifies the order of the derivative.

The derivative is calulated as centered differencing in the interior and one-sided derivatives at the boundaries. Higher orders are computed applying the same rule recursively.

Parameters:

order (int) – Order of derivative (e.g. 2 = second derivative).

Returns:

New series with derivative.

Return type:

BaseSeries or derived class

evaluate_with_spline(x, ext=2)

Evaluate the spline on the points x.

Values outside the interval are extrapolated if ext=0, set to 0 if ext=1, raise a ValueError if ext=2, or if ext=3, return the boundary value.

This method is meant to be used only if you want to use a different ext for a specific call, otherwise, just use __call__.

Parameters:

  • x (1D NumPy array of float) – Array of x where to evaluate the series or single x.

  • ext (int) – How to deal values outside the bounaries. Values outside the interval are extrapolated if ext=0, set to 0 if ext=1, raise a ValueError if ext=2, or if ext=3, return the boundary value.

Returns:

Values of the series evaluated on the input x.

Return type:

1D NumPy array or float

property f

Frequencies.

Returns:

Frequencies.

Return type:

1d NumPy array

property fft

Fourier components.

Returns:

Fourier components.

Return type:

1d NumPy array

property fmax

Return the maximum frequency.

Returns:

Maximum frequency of the series.

Return type:

float

property fmin

Return the minimum frequency.

Returns:

Minimum frequency of the series.

Return type:

float

property frange

Return the range of frequencies. The range is defined as the maximum frequency minus the minimum.

Returns:

Range of the series (f_max - f_min).

Return type:

float

high_pass(f)[source]

Remove all the frequencies smaller than f

Parameters:

f (float) – Frequency below which series will be zeroed.

high_passed(f)[source]

Remove frequencies lower or equal than the given.

Parameters:

f (float) – Frequency below which series will be zeroed.

Returns:

High-passed FrequencySeries.

Return type:

FrequencySeries

property index

Fake pandas properties, to make Series objects plottable by matplotlib.

inner_product(other, fmin=0, fmax=inf, noises=None, same_domain=False)[source]

Compute the (network) inner product with another FrequencySeries.

This is defined as:

\((h_1, h_2) = 4 \Re \int_{f_min}^{f_max} \frac{h_1 h_2^*}{S_n}\)

where S_n is the noise curve, and h_1, h_2 the series.

In case multiple noise curves are supplied, compute

\((h_1, h_2) = \sum_{detectors} 4 \Re \int_{f_min}^{f_max} \frac{h_1 h_2^*}{S_n}\)

This is the network inner product. To compute this quantity, you have to provide a list of noises.

We assume that the FrequencySeries are zero outside of the interval of definition, so if fmax (fmin) is larger (smaller) than the one available, it is effectively set to the one available.

Since Fourier typically transforms explode at fmin = 0, the result of the integration is highly sensitive to regions near that frequency.

If same_domain is True, it is assumed that all the FrequencySeries involved are defined over the same frequencies. Turning this on speeds up computations, but it will result in incorrect results if the assumption is violated. If it is False, the domain of definition of the series is checked, if it is not the same for all the series, then they will be resampled.

Parameters:

  • other (FrequencySeries) – Second frequency series in the inner product.

  • fmin (float) – Remove frequencies below this value.

  • fmax (float) – Remove frequencies above this value.

  • noise (FrequencySeries, list of FrequencySeries or None) – If None, no weight is applied.

  • same_domain (bool) – Whether to assume that the FrequencySeries are defined over the same frequencies. If you can guarantee this, the computation will be faster.

Returns:

Inner product between self and other.

Return type:

float

integrate(dx=None)

Integrate series with method of the rectangles.

The spacing dx can be optionally provided. If provided, it will be used (increasing performance), otherwise it will be computed internally.

integrated(dx=None)

Return a series that is the integral computed with method of the rectangles.

The spacing dx can be optionally provided. If provided, it will be used (increasing performance), otherwise it will be computed internally.

Parameters:

dx (float or None) – Delta x in the independent variable. If None it will be computed internally.

Returns:

New series with the cumulative integral.

Return type:

BaseSeries or derived class

is_complex()

Return whether the data is complex.

Returns:

True if the data is complex, false if it is not.

Return type:

bool

is_masked()

Return whether the x or y are masked.

Returns:

True if the x or y are masked, false if it is not.

Return type:

bool

is_regularly_sampled()

Return whether the series is regularly sampled.

If the series is only one point, an error is raised.

Returns:

Is the series regularly sampled?

Return type:

bool

local_maxima(*args, include_edges=True, **kwargs)

Use SciPy’s find_peaks to find the local maxima.

Unkown arguments are passed to find_peaks.

If the signal is complex, the absolute value is taken.

If include_edges is True, the edges are considered among the possible maxima.

Returns:

Coordinate and value of the peaks.

Return type:

Tuple of NumPy arrays

local_minima(*args, include_edges=True, **kwargs)

Use SciPy’s find_peaks to find the local minima.

Unkown arguments are passed to find_peaks.

If the signal is complex, the absolute value is taken.

If include_edges is True, the edges are considered among the possible minima.

Returns:

Coordinate and value of the minima.

Return type:

Tuple of NumPy arrays

low_pass(f)[source]

Remove frequencies higher or equal than f (absolute value).

Parameters:

f (float) – Frequency above which series will be zeroed.

low_passed(f)[source]

Remove frequencies higher or equal than the given.

Parameters:

f (float) – Frequency above which the series will be zeroed.

Returns:

Low-passed FrequencySeries.

Return type:

FrequencySeries

property mask

Return where the data is valid (according to the mask).

Returns:

Array of True/False of the same length of the data. False where the data is valid, true where is not.

Return type:

1D array of bool

mask_applied(mask, ignore_existing=False)

Return a new series with given mask applied to the data.

If a previous mask already exists, the new mask will be added on top, unless ignore_existing is True.

Parameters:

  • mask (1D NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method mask().

  • ignore_existing (bool) – If True, overwrite any previously existing mask.

Returns:

New series with mask applied.

Return type:

BaseSeries

mask_apply(mask, ignore_existing=False)

Apply given mask.

If a previous mask already exists, the new mask will be added on top, unless ignore_existing is True.

Parameters:

  • mask (1D NumPy array) – Array of booleans that identify where the data is invalid. This can be obtained with the method mask().

  • ignore_existing (bool) – If True, overwrite any previously existing mask.

mask_equal(value)

Mask where data is equal to given value.

mask_greater(value)

Mask where data is greater to given value.

mask_greater_equal(value)

Mask where data is greater or equal to given value.

mask_inside(value1, value2)

Mask where data is inside the given values.

mask_invalid()

Mask where data is invalid (NaNs of infs).

mask_less(value)

Mask where data is less to given value.

mask_less_equal(value)

Mask where data is less or equal to given value.

mask_not_equal(value)

Mask where data is not equal to given value.

mask_outside(value1, value2)

Mask where data is outside the given values.

mask_remove()

Remove masked values.

mask_removed()

Remove masked value.

Return a new series with valid values only.

Returns:

A new series with only valid values.

Return type:

BaseSeries or derived class

masked_equal(value)

Return a new objected masked where data is equal to given value.

masked_greater(value)

Return a new objected masked where data is greater to given value.

masked_greater_equal(value)

Return a new objected masked where data is greater or equal to given value.

masked_inside(value1, value2)

Return a new objected masked where data is inside the given values.

masked_invalid()

Return a new objected masked where data is invalid (NaNs or infs).

masked_less(value)

Return a new objected masked where data is less to given value.

masked_less_equal(value)

Return a new objected masked where data is less or equal to given value.

masked_not_equal(value)

Return a new objected masked where data is not equal to given value.

masked_outside(value1, value2)

Return a new objected masked where data is outside the given values.

nans_remove()

Filter out nans/infinite values.

nans_removed()

Filter out nans/infinite values. Return a new series with finite values only.

Returns:

A new series with only finite values.

Return type:

BaseSeries or derived class

negative_frequencies_remove()[source]

Remove all the frequencies smaller than 0.

negative_frequencies_removed()[source]

Remove frequencies lower than 0.

Returns:

Frequencyeseries with only positive frequencies.

Return type:

FrequencySeries

normalize()[source]

Scale values so that the maximum of the amplitude is 1.

normalized()[source]

Return a new FrequencySeries with maximum amplitude of 1.

Returns:

Normalized FrequencySeries series.

Return type:

FrequencySeries

overlap(other, fmin=0, fmax=inf, noises=None, same_domain=False)[source]

Compute the (network) overlap.

This is defined as:

\(\textrm{overlap} = (h_1, h_2) / \sqrt{(h_1, h_1)(h_2, h_2)}\)

where h_1, h_2 are the series.

To compute is the network overlap, you have to provide a list of noises.

We assume that the FrequencySeries are zero outside of the interval of definition, so if fmax (fmin) is larger (smaller) than the one available, it is effectively set to the one available.

Since Fourier typically transforms explode at fmin = 0, the result of the integration is highly sensitive to regions near that frequency.

If same_domain is True, it is assumed that all the FrequencySeries involved are defined over the same frequencies. Turning this on speeds up computations, but it will result in incorrect results if the assumption is violated. If it is False, the domain of definition of the series is checked, if it is not the same for all the series, then they will be resampled.

Parameters:

  • other (FrequencySeries) – Second frequency series in the overlap.

  • fmin (float) – Remove frequencies below this value.

  • fmax (float) – Remove frequencies above this value.

  • noise ((list of) FrequencySeries or None) – If None, no weight is applied. If it is a list, the netowrk overlap is computed.

  • same_domain (bool) – Whether to assume that the FrequencySeries are defined over the same frequencies. If you can guarantee this, the computation will be faster.

Returns:

Overlap between self and other.

Return type:

float

peaks(amp_threshold=0.0)[source]

Return the location and amplitude of the peaks of the amplitude.

Peaks at the boundaries are not considered.

Parameters:

amp_threshold (float) – Ignore peaks smaller than this value.

Returns:

Peaks of the amplitude as list of tuples of three elements: frequency of the bin in which the peak is, fitted frequency of the maximum with parabolic approximation, amplitude of the peak.

Return type:

List of tuples of three elements.

peaks_frequencies(amp_threshold=0.0)[source]

Return the frequencies of the peaks of the amplitude larger than amp_threshold.

The frequency is computed with a quadratic fit using the left and right neighbors.

Peaks at the boundaries are not considered.

Parameters:

amp_threshold (float) – Ignore peaks smaller than this value.

Returns:

Fitted frequencies of the peaks of the amplitude.

Return type:

1d NumPy array

resample(new_x, ext=2, piecewise_constant=False)

Resample the series to new independent variable new_x.

If you want to resample without using the spline, and you want a nearest neighbor resampling, pass the keyword piecewise_constant=True. This may be a good choice for data with large discontinuities, where the splines are ineffective.

Parameters:

  • new_x (1D NumPy array or list of float) – New independent variable.

  • ext (0 for extrapolation, 1 for returning zero, 2 for ValueError, 3 for extending the boundary) – How to handle points outside the interval.

  • piecewise_constant (bool) – Do not use splines, use the nearest neighbors.

resampled(new_x, ext=2, piecewise_constant=False)

Return a new series resampled from this to new_x.

You can specify the details of the spline with the method make_spline.

If you want to resample without using the spline, and you want a nearest neighbor resampling, pass the keyword piecewise_constant=True. This may be a good choice for data with large discontinuities, where the splines are ineffective.

Parameters:

  • new_x (1D NumPy array or list of float) – New independent variable.

  • ext (0 for extrapolation, 1 for returning zero, 2 for ValueError, 3 for extending the boundary) – How to handle points outside the data interval.

  • piecewise_constant (bool) – Do not use splines, use the nearest neighbors.

Returns:

Resampled series.

Return type:

BaseSeries or derived class

save(file_name, *args, **kwargs)

Saves into simple ASCII format with 2 columns (x, y) for real valued data and 3 columns (x, Re(y), Im(y)) for complex valued data.

Unknown arguments are passed to NumPy.savetxt.

Parameters:

file_name (str) – Path (with extension) of the output file.

savgol_smooth(window_size, order=3)

Smooth the series with a Savitzky-Golay filter with window of size window_size and order order.

This is just like a regular “Moving average” filter, but instead of just calculating the average, a polynomial (usually 2nd or 4th order) fit is made for every point, and only the “middle” point is chosen. Since 2nd (or 4th) order information is concerned at every point, the bias introduced in “moving average” approach at local maxima or minima, is circumvented.

Parameters:

  • window_size (int) – Number of points of the smoothing window (needs to be odd).

  • order (int) – Order of the filter.

savgol_smoothed(window_size, order=3)

Return a smoothed series with a Savitzky-Golay filter with window of size window_size and order order.

This is just like a regular “Moving average” filter, but instead of just calculating the average, a polynomial (usually 2nd or 4th order) fit is made for every point, and only the “middle” point is chosen. Since 2nd (or 4th) order information is concerned at every point, the bias introduced in “moving average” approach at local maxima or minima, is circumvented.

Parameters:

  • window_size (int) – Number of points of the smoothing window (needs to be odd).

  • order (int) – Order of the filter.

Returns:

New smoothed series.

Return type:

BaseSeries or derived class

spline_differentiate(order=1)

Differentiate the series using the spline representation.

The optional parameter order specifies the order of the derivative.

Warning

The values at the boundary are typically not accurate.

Parameters:

order (int) – Order of derivative (e.g. 2 = second derivative).

spline_differentiated(order=1)

Return a series that is the derivative of the current one using the spline representation.

The optional parameter order specifies the order of the derivative.

Warning

The values at the boundary are typically not accurate.

Parameters:

order (int) – Order of derivative (e.g. 2 = second derivative).

Returns:

New series with derivative

Return type:

BaseSeries or derived class

to_TimeSeries()[source]

Perform a inverse Fourier transform.

If only positive frequencies are found, we will assume that the original signal was real.

Returns:

Inverse Fourier transform.

Return type:

TimeSeries

to_numpy()

Return the data as NumPy array. Equivalent to self.y.

This function is here to enable compatibility matplotlib.

property values

Fake pandas properties, to make Series objects plottable by matplotlib.

x_at_abs_maximum_y()

Return the value of x when abs(y) is maximum.

Returns:

Value of x when abs(y) is maximum.

Return type:

float

x_at_abs_minimum_y()

Return the value of x when abs(y) is minimum.

Returns:

Value of x when abs(y) is minimum.

Return type:

float

x_at_maximum_y()

Return the value of x when y is maximum.

Returns:

Value of x when y is maximum.

Return type:

float

x_at_minimum_y()

Return the value of x when y is minimum.

Returns:

Value of x when y is minimum.

Return type:

float

property xmax

Return the maximum of the independent variable x.

Rvalue:

Maximum of x

Return type:

float

property xmin

Return the minimum of the independent variable x.

Rvalue:

Minimum of x.

Return type:

float

kuibit.frequencyseries.load_FrequencySeries(path, *args, complex_on_two_columns=False, **kwargs)[source]

Load a text file as a FrequencySeries.

The backend is np.loadtxt, and the unknown arguments passed to this function are given to np.loadtxt. This can be used, for example, to specify the columns of the file that have to be read.

Parameters:

  • path (str) – Path of the file to be loaded.

  • complex_on_two_columns (bool) – When true, it is assumed that the real and the imaginary parts of the frequency series are on two columns. Otherwise, on one. This has to be False to load real data (e.g., noise curves).

Returns:

Loaded data as FrequencySeries.

Return type:

FrequencySeries

kuibit.frequencyseries.load_noise_curve(path, *args, **kwargs)[source]

Load a noise curve as a FrequencySeries.

Unknown arguments are passed to np.loadtxt.

This is syntactic sugar for the function ()

Parameters:

path (str) – Path of the file to be loaded.

Returns:

Noise curve.

Return type:

FrequencySeries