Reference on kuibit.series¶
The series
module provides a base class BaseSeries
for representing and handling series (from which TimeSeries
and
FrequencySeries
are derived).
BaseSeries
handles series that have a independent variable x
and a dependent variable y
. The derived classes have to implement setters
and getters if they need to rename these variables (e.g. x -> t
). The
independent variable has to be monotonically increasing.
BaseSeries
implements several methods for operations on series.
Most of these methods are available in two flavors: those that return a new
BaseSeries
, and those which modify the object in place. The latter
have names with imperative verbs.
This module also provides the useful function sample_common()
, which
takes a list of series and resamples them to their common points.
- class kuibit.series.BaseSeries(x, y, guarantee_x_is_monotonic=False)[source]¶
Base class (not intended for direct use) for generic series data in which the independendent variable x is sorted.
This class is already rich of features.
- Variables:
data_x (1D NumPy array or float) – Independent variable.
y (1D NumPy array or float) – Dependent variable.
spline_real (Tuple) – Coefficients for a spline represent of the real part of y.
spline_imag (Tuple) – Coefficients for a spline represent of the real part of y.
When guarantee_x_is_monotonic is True no checks will be perform to make sure that x is monotonically increasing (increasing performance). This should is used internally whenever a new series is returned from self, since we have already checked that data_x is good.
- Parameters:
x (1d NumPy array or list) – Independent variable.
y (1d NumPy array or list) – Dependent variable.
guarantee_x_is_monotonic – Whether we can skip the check on monotonicity.
guarantee_x_is_monotonic – bool
- 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()[source]¶
Return a deep copy.
- Returns:
Deep copy of the series.
- Return type:
BaseSeries
or derived class
- crop(init=None, end=None)[source]¶
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)[source]¶
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
- differentiate(order=1)[source]¶
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)[source]¶
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)[source]¶
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 index¶
Fake pandas properties, to make Series objects plottable by matplotlib.
- integrate(dx=None)[source]¶
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)[source]¶
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()[source]¶
Return whether the data is complex.
- Returns:
True if the data is complex, false if it is not.
- Return type:
bool
- is_masked()[source]¶
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()[source]¶
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)[source]¶
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)[source]¶
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
- 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)[source]¶
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)[source]¶
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_removed()[source]¶
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
- nans_removed()[source]¶
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
- resample(new_x, ext=2, piecewise_constant=False)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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_numpy()[source]¶
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()[source]¶
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()[source]¶
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()[source]¶
Return the value of x when y is maximum.
- Returns:
Value of x when y is maximum.
- Return type:
float
- x_at_minimum_y()[source]¶
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.series.sample_common(series, resample=False, piecewise_constant=False)[source]¶
Take a list of series and return new ones so that they are all defined on the same points.
If
resample
is False (default), take as input a list of series and return a new list with the same series but only defined on those points that are common to all the lists. Ifresample
is True, instead of removing points, find the common interval of definition, and resample all the series on that internal. The number of sample points is the minimum over all series. Additionally, ifpiecewise_constant=True
, the approximant used for resampling is a piecewise constant function, splines are not used, instead, the nearest neighbors are used. Use this when you have series with discontinuities.- Parameters:
series (list of
Series
) – The series to resample or redefine on the common pointsresample (bool) – Whether to resample the series, or just find the common points.
piecewise_constant (bool) – Whether to use the nearest neighbor resampling method instead of splines. If
piecewise_constant=True
, the approximant used for resampling is a piecewise constant function.
- Returns:
Resampled series so that they are all defined in the same interval.
- Return type:
list of
Series