lightlab.util.data.one_dim module

One-dimensional data structures with substantial processing abilities

Summary

Classes:

MeasuredFunction	Array of x,y points.
Spectrum	Adds handling of linear/dbm units.
SpectrumGHz	Spectrum with GHz units in the abscissa
Waveform	Typically used for time, voltage functions.

Functions:

prbs_generator	Generator of PRBS bits.
prbs_pattern	Returns an array containing a sequence of a PRBS pattern.

Reference

prbs_generator(characteristic, state)

Generator of PRBS bits.

Example: polynomial = 0b1000010001 # 1 + X^5 + X^9 seed = 0b111100000

The above parameters will give you a PRBS9 bit sequence. Note: it might be inverted compared to the official definition, i.e., 1s are 0s and vice versa.

prbs_pattern(polynomial, seed, length=None)

Returns an array containing a sequence of a PRBS pattern.

If length is not set, the sequence will be 2^n-1 long, corresponding to the repeating pattern of the PRBS sequence.

class MeasuredFunction(abscissaPoints, ordinatePoints, unsafe=False)

Bases: object

Array of x,y points. This is the workhorse class of lightlab data structures. Examples can be found throughout Test notebooks.

Supports many kinds of operations:

1. Data access (mf(x), len(mf), mf[i], getData())

   Calling the object with x-values interpolates and returns y-values.

2. Storage (copy(), save(), load(), loadFromFile())

   see method docstrings

3. x-axis signal processing (getSpan(), crop(), shift(), flip(), resample(), uniformlySample())

   see method docstrings

4. y-axis signal processing (getRange(), clip(), debias(), unitRms(), getMean(), moment())

   see method docstrings

5. Advanced signal processing (invert(), lowPass(), centerOfMass(), findResonanceFeatures())

   see method docstrings

6. Binary math (+, -, *, /, ==)

   Operands must be either

   • the same subclass of MeasuredFunction, or
   • scalar numbers, or
   • functions/bound methods: these must be callable with one argument that is an ndarray

   If both are MeasuredFunction, the domain used will be the smaller of the two

7. Plotting (simplePlot())

   Args and Kwargs are passed to pyplot’s plot function. Supports live plotting for notebooks

8. Others (deleteSegment(), splice())

   see method docstrings

Parameters:

• abscissaPoints (array) – abscissa, a.k.a. independent variable, a.k.a. domain
• ordinatePoints (array) – ordinate, a.k.a. dependent variable, a.k.a. range
• unsafe (bool) – if True, faster, give it 1-D np.ndarrays of the same length, or you will get weird errors later on

absc = None

abscissa, a.k.a. the x-values or domain

ordi = None

ordinate, a.k.a. the y-values

getData()

Gives a tuple of the enclosed array data.

It is copied, so you can do what you want with it

Returns:the enclosed data Return type:tuple(array,array)

copy()

Gives a copy, so that further operations can be performed without side effect.

Returns:new object with same properties Return type:(MeasuredFunction/<childClass>)

save(savefile)

classmethod load(savefile)

simplePlot(*args, livePlot=False, **kwargs)

Plots on the current axis

Parameters:

• livePlot (bool) – if True, displays immediately in IPython notebook
• *args (tuple) – arguments passed through to pyplot.plot
• **kwargs (dict) – arguments passed through to pyplot.plot

Returns:

Whatever is returned by pyplot.plot

subsample(newAbscissa)

Returns a new MeasuredFunction sampled at given points.

getSpan()

The span of the domain

Returns:the minimum and maximum abscissa points Return type:(list[float,float])

abs()

Computes the absolute value of the measured function.

mean()

max()

Returns the maximum value of the ordinate axis, ignoring NaNs.

argmax()

Returns the abscissa value at which the ordinate is maximum.

min()

Returns the minimum value of the ordinate axis, ignoring NaNs.

argmin()

Returns the abscissa value at which the ordinate is minimum.

getRange()

The span of the ordinate

Returns:the minimum and maximum values Return type:(list[float,float])

crop(segment)

Crop abscissa to segment domain.

Parameters:segment (list[float,float]) – the span of the new abscissa domain Returns:new object Return type:MeasuredFunction

clip(amin, amax)

Clip ordinate to min/max range

Parameters:

• amin (float) – minimum value allowed in the new MeasuredFunction
• amax (float) – maximum value allowed in the new MeasuredFunction

Returns:

new object

Return type:

MeasuredFunction

shift(shiftBy)

Shift abscissa. Good for biasing wavelengths.

Parameters:shiftBy (float) – the number that will be added to the abscissa Returns:new object Return type:MeasuredFunction

flip()

Flips the abscissa, BUT DOES NOTHING the ordinate.

Usually, this is meant for spectra centered at zero. I.e.: flipping would be the same as negating abscissa

Returns:new object Return type:MeasuredFunction

reverse()

Flips the ordinate, keeping abscissa in order

Returns:new object Return type:MeasuredFunction

debias()

Removes mean from the function

Returns:new object Return type:MeasuredFunction

unitRms()

Returns function with unit RMS or power

getMean()

getMedian()

getVariance()

getStd()

resample(nsamp=100)

Resample over the same domain span, but with a different number of points.

Parameters:nsamp (int) – number of samples in the new object Returns:new object Return type:MeasuredFunction

uniformlySample()

Makes sure samples are uniform

Returns:new object Return type:MeasuredFunction

addPoint(xyPoint)

Adds the (x, y) point to the stored absc and ordi

Parameters:xyPoint (tuple) – x and y values to be inserted Returns:it modifies this object Return type:None

correlate(other)

Correlate signals with scipy.signal.correlate.

Only full mode and direct method is supported for now.

lowPass(windowWidth=None, mode=None)

movingAverage(windowWidth=None, mode='valid')

Low pass filter performed by convolving a moving average window.

The convolutional mode can be one of the following string tokens

• ‘valid’: the new span is reduced, but data is good looking
• ‘same’: new span is the same as before, but there are edge artifacts

Parameters:

• windowWidth (float) – averaging window width in units of the abscissa
• mode (str) – convolutional mode

Returns:

new object

Return type:

MeasuredFunction

butterworthFilter(fc, order, btype)

Applies a Butterworth filter to the signal.

Side effects: the waveform will be resampled to have equally-sampled points.

Parameters:fc (float) – cutoff frequency of the filter (cf. input to signal.butter) Returns:New object containing the filtered waveform

lowPassButterworth(fc, order=1)

Applies a low-pass Butterworth filter to the signal.

Side effects: the waveform will be resampled to have equally-sampled points.

Parameters:fc (float) – cutoff frequency of the filter Returns:New object containing the filtered waveform

highPassButterworth(fc, order=1)

Applies a high-pass Butterworth filter to the signal.

Side effects: the waveform will be resampled to have equally-sampled points.

Parameters:fc (float) – cutoff frequency of the filter Returns:New object containing the filtered waveform

bandPassButterworth(fc, order=1)

Applies a high-pass Butterworth filter to the signal.

Side effects: the waveform will be resampled to have equally-sampled points.

Parameters:fc (length-2 float sequence) – cutoff frequency of the filter Returns:New object containing the filtered waveform

deleteSegment(segment)

Removes the specified segment from the abscissa.

This means calling within this segment will give the first-order interpolation of its edges.

Usually, deleting is followed by splicing in some new data in this span

Parameters:segment (list[float,float]) – span over which to delete stored points Returns:new object Return type:MeasuredFunction

splice(other, segment=None)

Returns a Spectrum that is this one, except with the segment replaced with the other one’s data

The abscissa of the other matters. There is nothing changing (abscissa, ordinate) point pairs, only moving them around from other to self.

If segment is not specified, uses the full domain of the other

Parameters:

• other (MeasuredFunction) – the origin of new data
• segment (list[float,float]) – span over which to do splice stored points

Returns:

new object

Return type:

MeasuredFunction

invert(yVals, directionToDescend=None)

Descends down the function until yVal is reached in ordi. Returns the absc value

If the function is peaked, you should specify a direction to descend.

If the function is approximately monotonic, don’t worry about it.

Parameters:

• yVals (scalar, ndarray) – array of y values to descend to
• directionToDescend (['left', 'right', None]) – use if peaked function to tell which side. Not used if monotonic

Returns:

corresponding x values

Return type:

(scalar, ndarray)

centerOfMass()

Returns abscissa point where mass is centered

moment(order=2, relativeGauss=False)

The order’th moment of the function

Parameters:order (integer) – the polynomial moment of inertia. Don’t trust the normalization of > 2’th order. order = 1: mean order = 2: variance order = 3: skew order = 4: kurtosis Returns:the specified moment Return type:(float)

findResonanceFeatures(**kwargs)

A convenient wrapper for findPeaks()

Parameters:**kwargs – passed to findPeaks() Returns:the detected features as nice objects Return type:list[ResonanceFeature]

norm(ord=None)

class Spectrum(nm, power, inDbm=True, unsafe=False)

Bases: lightlab.util.data.one_dim.MeasuredFunction

Adds handling of linear/dbm units.

Use lin() and dbm() to make sure what you’re getting what you expect for things like binary math and peakfinding, etc.

Parameters:

• nm (array) – abscissa
• power (array) – ordinate
• inDbm (bool) – is the power in linear or dbm units?

inDbm

Is it in dbm units currently?

Returns: Return type:bool

lin()

The spectrum in linear units

Returns:new object Return type:Spectrum

db()

The spectrum in decibel units

Returns:new object Return type:Spectrum

simplePlot(*args, livePlot=False, **kwargs)

More often then not, this is db vs. wavelength, so label it

refineResonanceWavelengths(filtShapes, seedRes=None, isPeak=None)

Convolutional resonance correction to get very robust resonance wavelengths

Does the resonance finding itself, unless an initial approximation is provided.

Also, has some special options for Spectrum types to make sure db/lin is optimal

Parameters:

• filtShapes (list[MeasuredFunction]) – shapes of each resonance. Must be in order of ascending abscissa/wavelength
• seedRes (list[ResonanceFeature]) – rough approximation of resonance properties. If None, this method will find them.
• isPeak (bool) – required to do peak finding, but not used if seedRes is specified

Returns:

the detected and refined features as nice objects

Return type:

list[ResonanceFeature]

Todo

take advantage of fft convolution for speed

findResonanceFeatures(**kwargs)

Overloads MeasuredFunction.findResonanceFeatures() to make sure it’s in db scale

Parameters:**kwargs – kwargs passed to findPeaks Returns:the detected features as nice objects Return type:list[ResonanceFeature]

GHz()

Convert to SpectrumGHz

class SpectrumGHz(GHz, power, inDbm=True, unsafe=False)

Bases: lightlab.util.data.one_dim.Spectrum

Spectrum with GHz units in the abscissa

Use lin() and dbm() to make sure what you’re getting what you expect for things like binary math and peakfinding, etc.

Parameters:

• GHz (array) – abscissa
• power (array) – ordinate
• inDbm (bool) – is the power in linear or dbm units?

simplePlot(*args, livePlot=False, **kwargs)

More often then not, this is db vs. wavelength, so label it

nm()

Convert to Spectrum

class Waveform(t, v, unit='V', unsafe=False)

Bases: lightlab.util.data.one_dim.MeasuredFunction

Typically used for time, voltage functions. This is very similar to what is referred to as a “signal.”

Use the unit attribute to set units different than Volts.

Has class methods for generating common time-domain signals

unit = None

classmethod pulse(tArr, tOn, tOff)

classmethod whiteNoise(tArr, rmsPow)