Preprocessor¶

The preprocessor provides a variety of functions to assist quick loading and processing of traces. A trace is represented by a preprocessor.Buffer with a certain data type and can be stored (preprocessor.write_file()) or read (preprocessor.load_file()) from files on the harddrive.

The system has been designed to be more or less type-independent, allowing to process a trace of a certain type while outputing to another data type. This makes sense for example for the preprocessor.integrate() function, that often produces values that are out of range of the source data type. Accordingly, the preprocessor.average() function typically outputs floats, so a precission loss will occur unless a conversion is requested. Nearly all functions thus accept a dst_type parameter, that controls the output data type and defaults to zero and is then set to the same data type as the input data type.

To see which types have been compiled into this module run:

$ pydoc dpa.preprocessor.types

class dpa.preprocessor.AverageCounter¶

The AverageCounter processes traces sequentially and calculates a average and variance trace based on the input traces.

>>> a = AverageCounter(size=5, type=types.float)
>>> a.add_trace(buffer_from_list(types.uint8_t, [0, 1, 2, 3, 4]))
>>> a.add_trace(buffer_from_list(types.uint8_t, [2, 2, 2, 2, 2]))
>>> len(a)
2
>>> avg, var = a.get_buf()
>>> print avg
[1.0, 1.5, 2.0, 2.5, 3.0]
>>> print var
[1.0, 0.25, 0.0, 0.25, 1.0]

get_buf() -> (avg_buf, var_buf)¶: returns one float buffer for Buffer the average and one for the variance of all processed traces

class dpa.preprocessor.Buffer¶

Provides a interface for wrapping and keeping track of native C buffers

>>> buf_a = new_buffer(5, types.int8_t)
>>> buf_a[0] = 255
>>> print buf_a[0]
-1
>>> buf_b = buffer_from_list(types.float, [1.5, 2.25, 3.75])
>>> print buf_b.as_list()
[1.5, 2.25, 3.75]

as_list()¶: returns a list representation of the whole Buffer

zero()¶: fills the whole buffer with zeros

dpa.preprocessor.analyze(buf, include_variance=True) -> (average, variance, min, max)¶

calculates above characteristics for the Buffer buf

If variance is not needed, calculation is slightly quicker.

dpa.preprocessor.average(buf, n, skip=1, scale=1, dst_type=types.void) → :class:`Buffer`¶

average n samples of Buffer buf, the result is scaled by scale

skip is a skip-divisor. i.e. skip=2 returns every 2nd result sample

If signed_scale is set, a signed scale will be performed with the value signed_scale as the virtual zero (i.e. y = (x - signed_scale) * scale + signed_scale). A good value for signed_scale is thus the average of the trace.

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.buffer_from_list(type, list) → :class:`Buffer`¶: allocates a new Buffer and fills its values with the ones found in list

dpa.preprocessor.diff(a, b, absolute=True, dst_type=types.void) → :class:`Buffer`¶

calculates abs(a[i] - b[i]) for each sample of Buffer a and b, returns a new Buffer of length min(len(a), len(b))

If the output Buffer type is unsigned and absolute is not set the Buffer will be shifted by max_{datatype}/2.

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.filter(buf, filter_data, scale=1, dst_type=types.void) → :class:`Buffer`¶

applies a FIR filter to the Buffer buf

filter_data is a types.int8_t Buffer containing the filter coefficients, which are automatically scaled by 1/sum(filter_data)

The result can be scaled by scale.

If signed_scale is set, a signed scale will be performed with the value signed_scale as the virtual zero (i.e. y = (x - signed_scale) * scale + signed_scale). A good value for signed_scale is thus the average of the trace

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.free_buffer()¶: free_buffer(buf) – explicitly free an allocated Buffer. This is usually not needed!

dpa.preprocessor.integrate(buf, n, dst_type=types.void) → :class:`Buffer`¶

builds the sum of n samples each

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.load_file(filename, type, length=0) → :class:`Buffer`¶

reads a file into memory returning a Buffer

a non-zero length specifies the maximum amounts of bytes read

dpa.preprocessor.new_buffer(length, type, ptr=0)¶: allocate a new Buffer or generate one from an existing ptr

dpa.preprocessor.normalize(buf, min=NaN, max=NaN, adjust_factor=1.2, dst_type=types.void) → :class:`Buffer`¶

normalizes a trace with values in ]min, max[ to fit the whole range of the dst_type

If min and max are not set, they will be computed from the current trace with a border of adjust_factor (e.g. [0, 1] is adjusted to [-0.2, 1.2]).

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.peak_extract(buf, avg=-1, std_dev=-1, break_count=0, break_length=0, dst_type=types.void) → :class:`Buffer`¶

extracts high peaks from Buffer buf

If avg and std_dev are not set they are calculated in an analysis phase first.

break_count

specifies the number of pause at the beginning of the trace

If traces are not aligned in the time domain, but include a distinct pattern (i.e. a pause in signal), this can be used to align them.

break_length

specifies the minimum length of each pause in samples

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.raster(buf, edge, period, dst_type=types.void) → :class:`Buffer`¶

aligns a given trace buf using the pattern defined by edge

edge: is a buffer of the same type as buf
period: specifies the length of a period in samples each period in Buffer buf is linearly interpolated to fit the length specified by period

See also raster_config() to specify advanced attributes such as trigger_values and expected pause intervals.

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.rectify(buf, avg, dst_type=types.void) → :class:`Buffer`¶

rectifies a traces, by calculating the absolute difference to avg

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.reorder(buf, period, dst_type=types.void) → :class:`Buffer`¶

reorders a rasterized Buffer buf so that

period buffers are created, each containing only one sample of each period i.e. the buffer contains only the first sample of each period and so on

all buffers are concatenated again

By explicitly specifying a dst_type the result Buffer is forced to this type.

>>> reorder(buffer_from_list(types.uint8_t, [1,2,3,4,5,6,7,8,9,10,11]), 3)
[1, 4, 7, 10, 2, 5, 8, 11, 3, 6, 9]
>>> reorder(buffer_from_list(types.uint8_t, [1,2,3,4,5,6,7,8,9,10]), 3)
[1, 4, 7, 10, 2, 5, 8, 3, 6, 9]

dpa.preprocessor.scale(buf, scale=1.0, signed_scale=0, dst_type=types.void) → :class:`Buffer`¶

scales buffers values by scale (i.e. buf[i] *= scale)

If signed_scale is set, a signed scale will be performed with the value signed_scale as the virtual zero (i.e. y = (x - signed_scale) * scale + signed_scale). A good value for signed_scale is thus the average of the trace.

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.spline(buf, target_size, dst_type=types.void) → :class:`Buffer`¶

linearly interpolates a Buffer buf to fit a given length

For reasons of efficiency this does not do averaging, if size is significantly smaller than buf’s size.

spline interpolation is not yet implemented

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.square(buf, dst_type=types.void) → :class:`Buffer`¶

calculates the square of each value in Buffer buf

By explicitly specifying a dst_type the result Buffer is forced to this type.

dpa.preprocessor.write_file(filename, buf, length=0)¶

dumps the Buffer buf to a file

a non-zero length specifies the maximum amounts of bytes written

Preprocessor¶

Previous topic

Next topic

This Page