cait.trigger

class cait.trigger.MovingAverageTrigger(q1, q2, q3, tres, down=1)[source]

Bases: object

Class to efficiently trigger a time series with moving averages on two time scales. Attention! This algorithm has potentially huge numerical problems because q must be very close to 1. Also, it might not be properly tested.

Parameters:

q1 (float in (0,1)) – The weight parameter for past samples in the long time scale.
q2 (float in (0,1)) – The weight parameter for past samples in the short time scale.
p (float in (0,1)) – The weight parameter for triggered samples.
tres (float) – The multiplicative factor for the sigma by which to trigger.
down (int) – The value how many sample we should average before handing it to the trigger.

get_down_value(x)[source]

Wrapper around the get_value routine to downsample first.

Parameters:: x (float) – The new value.
Returns:: 0 for trigger, -1 for neg trigger, 1 for pos trigger.
Return type:: int

get_value(x)[source]

Give a new timestep of the time series to the algo and trigger. Calculates moving average m1 on short time scale and moving average m2 and moving std sigma on long time scale, when m1 exceed m2 + tresh`*`sigma or goes below m2 - tresh`*`sigma, trigger.

Parameters:: x (float) – The next value of the time series.
Returns:: 0 for no trigger, 1 for positive trigger, -1 for negative trigger.
Return type:: int

set_first_value(x0)[source]

Set the first value of the moving average.

Parameters:: x0 – The first value.
Type:: float

cait.trigger.add_to_moments(x_new, mean, var, n)[source]

Update existing mean and variance values by adding a new data point.

Parameters:

x_new (float) – The new data point.
mean (float) – The old mean value.
var (float) – The old variance value.
n (int) – The number of data points used to calculate the old mean and var.

Returns:

The new mean value, the new variance, the new number of data points.

Return type:

list

cait.trigger.bin(s, nmbr_bits=None)[source]

Returns a string of 0/1 values for any datatype.

Parameters:: s (any) – Any variable or object.
Returns:: The 0/1’s of s’ bits.
Return type:: string

cait.trigger.exclude_testpulses(trigger_hours, tp_hours, max_time_diff=0.5, in_seconds=True)[source]

Exclude all trigger values from the array, that are closer than a minimal distance value to a test pulse time stamp. Also all triggers before and after the first and last test pulse are excluded.

Parameters:

trigger_hours (1D array) – The time stamps of the triggers in hours.
tp_hours (1D array) – The time stamps of the test pulses in hours.
max_time_diff (float) – Trigger values that are closer than this value to any test pulse time stamp get excluded. Per default in seconds.
in_seconds (bool) – If this is True, the max_time_diff should be handed in seconds. Otherwise, it should be handed in hours.

Returns:

A array of bool values, that tells which of the trigger time stamps should be kept and which excluded.

Return type:

1D array

cait.trigger.find_nearest(array, value)[source]

Find the nearest element in an array to a given value.

Parameters:

array (1D array) – The array.
value (float) – The value.

Returns:

The array index of the closest element to the value.

Return type:

int

cait.trigger.find_peaks(array, lag, threshold, init_mean, init_var, fixed_var=0)[source]

Find the peaks in an array and return an array with 1/0/-1.

Based on https://stackoverflow.com/a/22640362/15216821.

Parameters:

array (list) – The array in which we want to detect peaks.
lag (int) – The size of the window which we use for calculating a mean and variance.
threshold (float) – The sigma value of the threshold
init_mean (float) – Here we can provide an initial mean value, otherwise this is extracted from the data.
init_var (float) – Here we can provide an initial variance value, otherwise this is extracted from the data.
fixed_var (float) – In case you don’t want to calculate the variance with a moving window, you can provide a fixed value.

Returns:

The array with 1/0/-1, corresponding to positive/negative peaks at the sample position. The means at all sample positions. The variances at all sample positions.

Return type:

list

cait.trigger.get_offset(path_dig_stamps)[source]

Get the offset between start of the continuous DAQ and start of the CCS time recording.

Parameters:: path_dig_stamps (str) – The full path to the *.dig file.
Returns:: The offset that needs to be subtracted from all CCS time stamps, to get the time stamps w.r.t. the start of the CSMPL file.
Return type:: int

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For triggering, use cait.versatile.trigger_of() or cait.versatile.trigger_zscore().

cait.trigger.get_record_window(path, start_time, record_length, sample_duration=4e-05, down=1, bytes_per_sample=2)[source]

Get a record window from a stream *.csmpl file.

Parameters:

path (string) – The path to the *.csmpl file.
start_time (float) – The start time of the record window from beginning of the file, in seconds.
record_length (int) – The length of the record window in samples.
sample_duration (float) – The duration of the samples in the array.
down (int) – The array gets downsampled by this factor before it gets filtered.
bytes_per_sample

Returns:

(the values of the record window, the time stamps of the individual samples)

Return type:

2-tuple of 1D arrays

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For triggering, use cait.versatile.trigger_of() or cait.versatile.trigger_zscore().

cait.trigger.get_record_window_vdaq(path, start_time, record_length, dtype, key, header_size, sample_duration=4e-05, down=1, bits=16, vswing=39.3216)[source]

Get a record window from a stream *.bin file.

Parameters:

path (str) – The full path of the *.bin file.
start_time (float) – The start time in seconds, from where we want to read the record window, starting with 0 at the beginning of the file.
record_length (int) – The record length to read from the bin file.
dtype (numpy data type) – The data type with which we read the *.bin file.
key (str) – The key of the dtype, corresponding to the channel that we want to read.
header_size (int) – The size of the file header of the bin file, in bytes.
sample_duration (float) – The duration of a sample, in seconds.
down (int) – A factor by which the events are downsampled before they are returned.
bits (int) – The precision of the digitizer.
vswing (float) – The total volt region covered by the ADC.

Returns:

List of two 1D numpy arrays: The event read from the *.bin file, and the corresponding time grid.

Return type:

list

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files.

cait.trigger.get_starttime(path_sql, csmpl_channel, sql_file_label)[source]

Read the start time of a *.csmpl file from the SQL database.

Attention, the start time is only in seconds. This produces an error of the absolute time stamp of up to one second.

Parameters:

path_sql (string) – The path of the SQL file.
csmpl_channel (string) – The channel number of the *.csmpl file. This is either contained in the file name of the csmpl file or can be looked up in the SQL database.
sql_file_label (string) – The file label of the *.csmpl file within SQL database, e.g. bck_001.

Returns:

Time of file creation in seconds.

Return type:

float

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For triggering, use cait.versatile.trigger_of() or cait.versatile.trigger_zscore().

cait.trigger.get_triggers(array, lag, threshold, init_mean, init_var, look_ahead, fixed_var=0)[source]

Trigger the peaks in an array and return their indices and properties.

Based on https://stackoverflow.com/a/22640362/15216821.

Parameters:

array (list) – The array in which we want to detect peaks.
lag (int) – The size of the window which we use for calculating a mean and variance.
threshold (float) – The sigma value of the threshold
init_mean (float) – Here we can provide an initial mean value, otherwise this is extracted from the data.
init_var (float) – Here we can provide an initial variance value, otherwise this is extracted from the data.
look_ahead (int) – Look this number of samples in the future if another peak is higher than this one and overwrite if so.
fixed_var (float) – In case you don’t want to calculate the variance with a moving window, you can provide a fixed value.

Returns:

The array with the triggered indices. The corresponding peak heights. The means at all sample positions. The variances at all sample positions.

Return type:

list

cait.trigger.plot_csmpl(path, start_time=0, record_length=None, end_time=None, sample_duration=4e-05, hours=False, plot_stamps=None, plot_stamps_second=None, dpi=None, teststamp_path=None, clock=10000000.0, sec_offset=0, save_path=None)[source]

Plot a part of the stream together with provided trigger time stamps.

Parameters:

path (string) – The path to the *.csmpl file.
start_time (float) – The start time of the record window from beginning of the file, in seconds.
record_length (int) – The length of the record window in samples.
start_time – The end time of the record window from beginning of the file, in seconds.
sample_duration (float) – The duration of the samples in the array.
hours (bool) – If true, the plot has hours instead of seconds on the x axis.
plot_stamps (float) – If handed, all of these time stamps are plotted, if they are within the record window. In hours. This feature is useful, to debug the trigger algorithm, in case it shows unexpected behaviour.
plot_stamps_second (float) – If handed, all of these time stamps are plotted, if they are within the record window, in a different color than the first time stamps. In hours. This feature is useful to compare trigger values of different trigger algorithms.
dpi (int) – The dots per inch of the plots.
teststamp_path (string) – A path to a *.test_stamp file, these stamps are then plottet instead of the plot_stamps.
clock (int) – The Frequency of the time clock, in Hz. Standard for CRESST is 10MHz.
sec_offset (float) – This factor is substracted from the time stamps that are read from the *.test_stamps file.
save_path (string) – Save the figure at this path location.

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For displaying streams, use cait.versatile.StreamViewer.

cait.trigger.read_header(path_bin)[source]

Function that reads the header of a *.bin file.

Parameters:: f (string) – The path to the *.bin file.
Returns:: list (dictionary with infos from header, list of keys that are written in each sample, bool True if adc is 16 bit, bool True if dac is 16 bit)
Return type:: list

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files.

cait.trigger.readcs(path)[source]

This functions reads a continuous stream file, i.e. from CRESST.

Parameters:: path (string) – Path to the continuos stream file.
Returns:: Return the stream file. Use in a with context!
Return type:: BinaryFile

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files.

cait.trigger.sample_to_time(s, sample_duration=4e-05)[source]

Convert a sample index stamp to a seconds time stamp within the stream.

Parameters:

s (1D array) – The sample indices.
sample_duration (float) – The sample duration in second.

Returns:

The seconds time stamps.

Return type:

1D array

cait.trigger.sub_from_moments(x_new, mean, var, n)[source]

Update existing mean and variance values by substracting a new data point.

Parameters:

x_new (float) – The new data point.
mean (float) – The old mean value.
var (float) – The old variance value.
n (int) – The number of data points used to calculate the old mean and var.

Returns:

The new mean value, the new variance, the new number of data points.

Return type:

list

cait.trigger.time_to_sample(t, sample_duration=4e-05)[source]

Convert a seconds time stamp to a sample index within the stream.

Parameters:

t (1D array) – The seconds time stamps.
sample_duration (float) – The sample duration in second.

Returns:

The sample indices.

Return type:

1D array

cait.trigger.trigger_bin(paths, dtype, key, header_size, trigger_tres, bits=16, transfer_function=None, record_length=16384, overlap=None, sample_length=4e-05, take_samples=-1, start_hours=0, trigger_block=16384, return_info=False, down=1, window=True, square=False)[source]

Trigger a number of BIN files in one channel and return the time stamps of all triggers.

Parameters:

paths (list of strings) – The paths to all BIN files. It is not recommended to put more than one path, because this will set the time gap in between the files to zero.
dtype (numpy data type) – The data type with which we read the *.bin file.
key (str) – The key of the dtype, corresponding to the channel that we want to read.
header_size (int) – The size of the file header of the bin file, in bytes.
trigger_tres (list of floats) – The trigger thresholds for all channels.
bits (int) – The precision of the digitizer.
transfer_function (1D array of size record_length/2 +1) – The transfer function for the filter. If no transfer function is provided, a median filter is applied instead.
record_length (int) – The length of the record window in samples.
overlap (int) – The number of samples that overlap between two record windows that are to be filtered.
sample_length (float) – The sample length in seconds. If None, it is calculated from the sample frequency.
take_samples (int) – The number of samples, counted from the start of the of the stream, to trigger. If -1, take all samples.
start_hours (float) – An hours value that is added to all trigger time stamps.
trigger_block (int) – The first trigger_block samples cannot get triggered.
return_info (bool) – If true, instead of only the trigger time stamps a tuple is return. The first entry in the tuple are the trigger time stamps, the second the trigger heights, third the start values of the record windows, fourth the trigger block values of the individual trigger windows.
down (int) – The array gets downsampled by this factor before it gets filtered.
window (bool) – If true, a window function is applied to the record window before filtering. Recommended!
square (bool) – Square the stream values before triggering, this needs to be done for DAC channels.

Returns:

The hours time stamps of all triggers.

Return type:

1D array

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For triggering, use cait.versatile.trigger_of() or cait.versatile.trigger_zscore().

cait.trigger.trigger_csmpl(paths, trigger_tres, transfer_function=None, record_length=16384, overlap=None, sample_length=4e-05, take_samples=-1, start_hours=0, trigger_block=16384, return_info=False, down=1, window=True)[source]

Trigger a number of CSMPL file of one channel and return the time stamps of all triggers.

The data format and method was described in “(2018) N. Ferreiro Iachellini, Increasing the sensitivity to low mass dark matter in cresst-iii witha new daq and signal processing”, doi 10.5282/edoc.23762.

Parameters:

paths (list of strings) – The paths to all CSMPL files. It is not recommended to put more than one path, because this will set the time gap in between the files to zero.
trigger_tres (list of floats) – The trigger thresholds for all channels.
transfer_function (1D array of size record_length/2 +1) – The transfer function for the filter. If no transfer function is provided, a median filter is applied instead.
record_length (int) – The length of the record window in samples.
overlap (int) – The number of samples that overlap between two record windows that are to be filtered.
sample_length – The sample length in seconds. If None, it is calculated from the sample frequency. :type sample_length: float
take_samples (int) – The number of samples, counted from the start of the of the stream, to trigger. If -1, take all samples.
start_hours (float) – An hours value that is added to all trigger time stamps.
trigger_block (int) – The first trigger_block samples cannot get triggered.
down (int) – The array gets downsampled by this factor before it gets filtered.
return_info (bool) – If true, instead of only the trigger time stamps a tuple is return. The first entry in the tuple are the trigger time stamps, the second the trigger heights, third the start values of the record windows, fourth the trigger block values of the individual trigger windows.
window (bool) – If true, a window function is applied to the record window before filtering. Recommended!

Returns:

The hours time stamps of all triggers.

Return type:

1D array

Deprecated since version 1.3.0: This will be removed in 2.0.0. Use the cait.versatile.Stream class to interact with stream files. For triggering, use cait.versatile.trigger_of() or cait.versatile.trigger_zscore().