HTTPS SSH

Curve - A waveform manipulation and analysis library for Python

Juan Pablo Caram (c) 2018

Introduction

The Curve class represents Y values that evolve as a function of X.

Example:

import numpy as np
from matplotlib.pyplot import *
from curve import Curve

x = np.linspace(0, 10)
y = np.sin(x)
mycurve = Curve(x, y)

mycurve.plot()

png

The class provides several operations for the data within the class:

Example:

sq_curve = mycurve**2
int_curve = sq_curve.integrate().plot()

png

It is also possible to carry out operations between Curve's even is their
x-axis values don't match:

x1 = np.linspace(0, 10, num=30)
x2 = np.linspace(0, 10, num=100)
y1 = np.sin(x1)
y2 = np.cos(x2)
sum_curve = Curve(x1, y1) + Curve(x2, y2)
sum_curve.plot()

png

Curve API

Curve(data, y=None, dtype=float)

Initilizes the Curve object with data.

Usage:

    mycurve = Curve(x, y)

or

    mycurve = Curve([x, y])

:param data: A 2xn (or nx2) list or Numpy array, or a 1-d vector
             for the x-axis values (In this case, must also provide
             the y parameter).
:param y: 1-d vector of y-axis values correspondind to the x-axis
          values provided in the data parameter. If this is not
          provided it assumes that data contains both x and y-axis data
          in a 2-times-n data structure.
:param dtype: Type in which the data is stored.

Addition: curve + other

other may be a scalar or a Curve.

Multiplication: curve * other

other may be a scalar or a Curve.

x1 = np.linspace(0, 10, num=130)
x2 = np.linspace(0, 10, num=100)
y1 = np.sin(x1)
y2 = np.cos(x2 * 3)
c1 = Curve(x1, y1)
c2 = Curve(x2, y2)
c1.plot(label='c1')
c2.plot(label='c2')
(c1 * c2).plot(label='c1*c2')
legend();

png

Division: curve / other

other may be a scalar or a Curve. Reverse division, i.e., other / curve, when other is a scalar is also supported.

c1.plot(label='c1')
c2.plot(label='c2')
(c1 / c2).plot(label='c1/c2')
legend();

png

Power: curve ** other

Only scalar values of other are supported at this time.

Negative: -curve

Inverts the sign of the y-axis values.

curve.x

X-axis values

curve.y

Y-axis values

curve.duration

The difference between the first and last X-axis values.

curve.check(fix=0)

Check for proper data (Monotonicity of the x-axis values).
Fix it if necessary by sorting (x, y) pairs by x.

:param fix: Fix non-monotonicity in the x-axis by sorting (x, y) pairs by x.
            Default is False.

curve.at(value, interpolate=True)

Returns y(x=value), interpolating values (trapezoid), otherwise
returns y for the closest existing x < value. If values is
a list, returns a list of corresponding values of y.

:param value: X-axis value(s) for which the Y-axis value(s) is(are) returned.
              May be a list/Numpy array of values or a scalar (float/int).
:param interpolate: Wheather to interpolate between closest X values,
                    or to approximate to the nearest available.
                    Default is True.
:return: Corresponding Y-axis value(s).
curve = Curve([0, 3], [1, 9])
x = [1.5, 2.5]
y = curve.at(x)

plot(curve.x, curve.y, 'o-', label='curve')
plot(x, y, 'o', label='interpolation')
legend();

png

curve.resample(max_grow=10)

Resamples the curve at uniform intervals. It chooses the minumum existing
spacing between x-axis values as the sampling period unless the resulting
number of samples is greater than max_grow times the current number of samples.
In such case, the period is set to be such that the resulting number of
samples is exactly max_grow times the current number of samples.

:param max_grow: Maximum allowed increase in number of data points.
:return: Resulting resampled curve.

curve.envelope()

Calculates the envelope of the curve. Uses the hilbert function from
scipy.signal.

:return: Envelope curve.
x = np.linspace(0, 100, num=200)
y = np.sin(x/10) * np.sin(x)
curve = Curve(x, y)
env = curve.envelope()

curve.plot(label='curve')
env.plot(label='envelope')
legend();

png

curve.envelope2(tc=None, numpoints=101)

Calculates the envelope of the curve. Slices the curve into uniform intervals
and computes the maximum of the interval to determine the envelope.

:param tc: Interval width for computing the maximum as the envelope.
           If not provided, tc = duration / (numpoints - 1).
:param numpoints: Used if tc is not provided to calaculate tc.
:return: Envelope curve.
x = np.linspace(0, 100, num=200)
y = np.sin(x/10) * np.sin(x)
curve = Curve(x, y)
env = curve.envelope2(tc=5.0)

curve.plot(label='curve')
env.plot(label='envelope')
legend();

png

curve.diff()

Computes the difference (derivative) of this curve.

:return: A Curve containing the derivative of this curve.
x = np.linspace(0, 10)
y = np.sin(x)
curve = Curve(x, y)
curve_diff = curve.diff()

curve.plot(label='curve')
curve_diff.plot(label='d(curve)/dx')
legend();

png

curve.interval(xmin=None, xmax=None, include_edges=True, interpolate=True)

Extracts a segment of the curve for xmin < x < xmax. If xmin or xmax
are not specified, they are considered the min(x) or max(x)
respectively.

:param xmin: Minimum x-axis value of the interval.
:param xmax: Maximum x-axis value of the interval.
:param include_edges: If xmin or xmax exceed the limits of the curve,
                      whether to include these limits or truncate
                      at the actual limits of the curve.
                      Default is True.
:param interpolate: If include_edge is True, whether to interpolate to
                    compute the extremes. Default is True.
:return: Curve for the specified interval.

curve.integrate()

Generates a new Curve with the integral (trapezoidal)
of this Curve.

:return: A Curve containing the integral of this curve.
x = np.linspace(0, 10)
y = np.sin(x)
curve = Curve(x, y)
curve_integ = curve.integrate()

curve.plot(label='curve')
curve_integ.plot(label='integ(curve)')
legend();

png

curve.average()

Computes a curve whose value at any given x, are
the average of the y-axis values for all previous
values of x.

:return: Curve with the average of this Curve throughout x.
x = np.linspace(0, 30, num=200)
y = np.sin(x)
curve = Curve(x, y)
curve.plot(label='curve')
curve.average().plot(label='average')
legend();

png

curve.cross(edge=None)

Computes the times (or x-axis values) at which this curve
crosses 0 (in y-axis values).

To compute the crossing of a different threshold,
shift the curve first:

    mycurve = Curve(x, y)
    cross_times = (mycurve - threshold).cross()

:param edge: Whether to get just rising or falling edges.
             Possible values are 'rise', 'fall' or None (default).
             If None, it computes both rising and falling edges.
:param which: Not implemented.
:return: 1-d Numpy array of values corresponding to when/where
         along the x-axis, the y-axis values cross 0.
x = np.linspace(0, 30, num=200)
y = np.sin(x)
curve = Curve(x, y)
curve.plot(label='curve')

zero_cross = curve.cross(edge='fall')
plot(zero_cross, [0]*len(zero_cross), 'o', label='pos-neg 0 crossing')
legend(loc='lower left');

png

curve.period(threshold=None, verbose=False)

Computes a curve with the period of this curve. The period
is defined as the time between rising edges crossing the
specified threshold. If not provided, it is set to the
curve's average. Values are defined at the time of the
threshold crossing and are with respect to the previous
threshold crossing.

:param verbose: If true, prints debug information.
:param threshold: Value of the curve at which it is considered
    to have completed/started a period.
:return: Period Curve.
fig, ax = subplots(2, 1)

x = np.linspace(0, 30, num=500)
yp = 0.5 * np.sin(x/5)
y = np.sin((3+yp)*x)
curve = Curve(x, y)
curve.plot(ax=ax[0], label='curve')
ax[0].legend()

period = curve.period()
period.plot(ax=ax[1], color='orange', marker='o', label='period')
ax[1].legend();

png

curve.frequency(threshold=None, verbose=False)

Computes the frequency of the signal/curve. This is computed
as 1/period. See Curve.period().

:param threshold: Threshold used for computing the period of each cycle.
:param verbose: Print out additional information.
:return: Curve containing the frequency of this curve as a function of X.
fig, ax = subplots(2, 1)

x = np.linspace(0, 30, num=500)
yp = 0.5 * np.sin(x/5)
y = np.sin((3+yp)*x)
curve = Curve(x, y)
curve.plot(ax=ax[0], label='curve')
ax[0].legend()

freq = curve.frequency()
freq.plot(ax=ax[1], color='orange', marker='o', label='frequency')
ax[1].legend();

png

curve.plot()

Plots the curve using matplotlib.pyplot.plot().

:param ax: If provided, plots on the given axes. Otherwise,
           uses the current axes.
:param xscale: Multiplier for x-axis values.
:param yscale: Multiplier for y-axis values.
:param kwargs: Additional keyword arguments passed to
               matplotlib.pyplot.plot().