Processing of HiSPARC traces

Process HiSPARC traces

This module can be used analyse (raw) traces. It implements the same algorithms as are implemented in the HiSPARC DAQ.

The MeanFilter is meant to mimic the filter in the HiSPARC DAQ. It is reproduced here to make it easy to read the algorithm.

sapphire.analysis.process_traces.PRE_TRIGGER = 400

Default pre trigger window, i.e. 1000 ns

sapphire.analysis.process_traces.TRIGGER = 600

Default trigger window, i.e. 1500 ns

sapphire.analysis.process_traces.POST_TRIGGER = 1400

Default post trigger window, i.e. 3500 ns

sapphire.analysis.process_traces.ADC_FILTER_THRESHOLD = 10

Default Mean filter threshold of -6 mV

sapphire.analysis.process_traces.ADC_BASELINE_THRESHOLD = 17

Default Baseline threshold of -10 mV

sapphire.analysis.process_traces.ADC_LOW_THRESHOLD = 253

Default low ADC threshold for HiSPARC II

sapphire.analysis.process_traces.ADC_HIGH_THRESHOLD = 323

Default high ADC threshold for HiSPARC II

sapphire.analysis.process_traces.ADC_LOW_THRESHOLD_III = 82

Default low ADC threshold for HiSPARC III

sapphire.analysis.process_traces.ADC_HIGH_THRESHOLD_III = 150

Default high ADC threshold for HiSPARC III

sapphire.analysis.process_traces.DATA_REDUCTION_PADDING = 26

Padding to allow later baseline determination

class sapphire.analysis.process_traces.TraceObservables(traces, threshold=17, padding=26)

Reconstruct trace observables

If one wants to reconstruct trace observables from existing data some caveats apply. If the station applied the Mean Filter the trace values will no longer match the raw values used to determine the observables on the station. Additionally, if data reduction was active the trace may be missing samples without a significant signal, this complicates the determination of the baseline. Moreover, data reduction uses the ADC_BASELINE_THRESHOLD to determine what signals to keep, so tiny pulses may be removed making it impossible to reconstruct tiny pulseheights.

The (default) value of ADC_BASELINE_THRESHOLD is different for the HiSPARC DAQ prior to v4 and also for PySPARC. Those use 25 ADC as threshold.

Each returned list contains at least 4 elements, if there are less than 4 traces the list is padded with the code for missing detectors: -1.

Initialize the class

Parameters:

• traces – a NumPy array of traces, ordered such that the first element is the first sample of each trace.

• threshold – value of the threshold to use, in ADC counts.

• padding – number of samples which should be usuable to determine the baseline.

property baselines

Mean value of the first part of the trace

This does not perfectly match the implementation in the DAQ which is more complicated, this does provide the correct value in most cases, or is off by 1 in most other.

Usually this value is either around 200 or 30, depending on the used version of the DAQ.

Returns:

the baseline in ADC count.

property std_dev

Standard deviation of the first part of the trace

Returns:

the standard deviation in milli ADC count.

property pulseheights

Maximum peak to baseline value in trace

Returns:

the pulseheights in ADC count.

property integrals

Integral of trace for all values over threshold

The threshold is defined by ADC_BASELINE_THRESHOLD

Returns:

the pulse integral in ADC count * sample.

property n_peaks

Number of peaks in the trace

The peak threshold is defined by ADC_LOW_THRESHOLD

Returns:

the pulse integral in ADC count * sample.

class sapphire.analysis.process_traces.MeanFilter(use_threshold=True, threshold=10)

Filter raw traces

This class replicates the behavior of the Mean_Filter.vi in the HiSPARC DAQ. A sawtooth-like pattern may be visible in traces due to ADC misalignment and the synchronization pulse (?). This filter removes such small oscillations but keeps significant pulses.

Warning

This is a destructive algorithm which removes important information from the data.

Verified, by eye, with the LabView VI and Bachelor thesis Oostenbrugge2014.

Initialize the class

Parameters:

• use_threshold – use a threshold when filtering traces.

• threshold – value of the threshold to use.

filter_traces(raw_traces)

Apply the mean filter to multiple traces

Parameters:

raw_traces – list of raw event traces.

Returns:

filtered traces.

filter_trace(raw_trace)

Apply the mean filter to a single trace

First separate the even and odd ADC traces, filter each separately. Then recombine them and pass the entire trace through the filter.

Parameters:

raw_trace – raw event trace.

Returns:

filtered trace.

mean_filter_with_threshold(trace)

The mean filter in case use_threshold is True

mean_filter_without_threshold(trace)

The mean filter in case use_threshold is False

class sapphire.analysis.process_traces.DataReduction(threshold=17, padding=26)

Data reduce traces

This class replicates the behavior also implemented in the HiSPARC DAQ. The threshold and padding values used by the DAQ may be slightly different, but these should closely match the defaults.

The default padding of 25 samples matches the number of samples used by the TraceObservables to determine the baseline.

Initialize the class

Parameters:

• threshold – value of the threshold to use, in ADC counts.

• padding – number of samples to keep around the determined cuts.

reduce_traces(traces, baselines=None, return_offset=False)

Apply data reduction to the given traces

Parameters:

• traces – a NumPy array of traces, ordered such that the first element is the first sample of each trace.

• baselines – list of baselines for the traces, if None the baselines will be determined using TraceObservables.

• return_offset – if True the left cut will also be returned.

Returns:

data reduced traces, including the left cut if return_offset is True.

determine_cuts(traces, baselines)

Determine the left and right cuts for an event

Note that this does not include the padding.

Parameters:

• traces – a NumPy array of traces, ordered such that the first element is the first sample of each trace.

• baselines – list of baselines for the traces.

Returns:

indices into traces where the first signals from left and right cross the threshold.

add_padding(left, right, length=None)

Add padding around the cuts to allow later baseline determination

The right value may be larger than the length of the traces if length is not given. This is only an issues if the actual value is of interest, because:

>>> [1, 2, 3][:6]
[1, 2, 3]

Parameters:

• left,right – the left and right cuts from determine_cuts().

• length – optionally the length of the list can be given to prevent the right cut to be larger than the maximum length of the trace, this is not required.

Returns:

indices into traces where to cut the trace.