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 thatf
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 abovefmax
.- 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]
. Ifinit
orend
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]
. Ifinit
orend
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]
. Ifinit
orend
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]
. Ifinit
orend
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 ifext=1
, raise aValueError
ifext=2
, or ifext=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 ifext=1
, raise a ValueError ifext=2
, or ifext=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
- 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, andh_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 iffmax
(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 theFrequencySeries
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 ofFrequencySeries
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
andother
.- 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(include_edges=True, *args, **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(include_edges=True, *args, **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
- 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
- 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_removed()[source]¶
Remove frequencies lower than 0.
- Returns
Frequencyeseries with only positive frequencies.
- Return type
- normalized()[source]¶
Return a new
FrequencySeries
with maximum amplitude of 1.- Returns
Normalized
FrequencySeries
series.- Return type
- 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 iffmax
(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 theFrequencySeries
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
andother
.- 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 orderorder
.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 orderorder
.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
- 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 tonp.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
- 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