Tools#

Several tools for manipulation of BeForRecord and BeForEpochs data

BeForRecord functions#

`befordata.scale_record`(rec, factor)	Scales the force data (inplace) of the BeForRecord by a specified factor.
`befordata.concat_records`(record_list[, ...])	Concatenate a list or tuple of BeForRecord instances into a single BeForRecord.
`befordata.detect_sessions`(rec, time_gap)	Detects recording sessions in a BeForRecord based on time gaps.
`befordata.split_sessions`(rec)	Split the record into a list of BeForRecord objects, one per session.
`befordata.extract_epochs`(rec, column, ...[, ...])	Extracts epochs centred around specified zero samples or zero times, with a given number of samples before and after each zero point.

scale_record(rec, factor)#

Scales the force data (inplace) of the BeForRecord by a specified factor.

This function creates a deep copy of the input BeForRecord, multiplies the columns corresponding to force measurements by the given scaling factor, and returns a new BeForRecord with the scaled data. All other attributes (sampling rate, sessions, time column, and metadata) are preserved via deep copy to avoid side effects.

Return type:

None

Parameters:

recBeForRecord
factorfloat: The scaling factor to apply to the force data columns.

concat_records(record_list, no_sessions=False)#

Concatenate a list or tuple of BeForRecord instances into a single BeForRecord.

Return type:: BeForRecord

Returns a BeForRecord instance containing the concatenated records from: all input objects.

Parameters:

record_listlist or tuple of BeForRecord: A list or tuple containing BeForRecord objects to concatenate. All objects must have matching data columns, time_column, sampling rate.
no_sessionsbool, optional: If True, session information will be ignored during concatenation. Default is False.

Raises:

ValueError: If the input list or tuple is empty.
TypeError: If any element in the input is not a BeForRecord instance.

Notes

Metadata will not be copied and only the metadata of the first BeForRecord will be used.

detect_sessions(rec, time_gap)#

Detects recording sessions in a BeForRecord based on time gaps. The function modifies the sessions attribute of the BeForRecord in place.

This function analyses the time column of the provided BeForRecord and identifies breaks in the recording where the time difference between consecutive samples exceeds the specified time_gap. Each detected break marks the start of a new session.

Return type:

None

Parameters:

recBeForRecord
time_gapfloat: The minimum time difference (in the same units as the time column) that is considered a pause in the recording and thus the start of a new session.

split_sessions(rec)#

Split the record into a list of BeForRecord objects, one per session.

Returns a list of BeForRecord objects, each containing the data for one session.

Return type:

List[BeForRecord]

Parameters:

recBeForRecord

extract_epochs(rec, column, n_samples, n_samples_before, zero_samples=None, zero_times=None, design=Empty DataFrame Columns: [] Index: [], suppress_warnings=False)#

Extracts epochs centred around specified zero samples or zero times, with a given number of samples before and after each zero point.

Returns an BeForEpochs object containing the extracted epochs.

Return type:

BeForEpochs

Parameters:

recBeForRecord
columnstr: Name of the column containing the force data to extract.
n_samplesint: Number of samples to extract after the zero sample.
n_samples_beforeint: Number of samples to extract before the zero sample.
zero_sampleslist of int or np.ndarray, optional: List of sample indices to center epochs on.
zero_timeslist of float or np.ndarray, optional: List of time stamps to center epochs on.
designpd.DataFrame, optional: Optional design matrix or metadata for the epochs.
suppress_warningsbool, optional (default: False): If True, suppress incomplete epoch warnings during epoch extraction.

Raises:

ValueError: If neither or both of zero_samples and zero_times are provided.

Notes

Provide either zero_samples or zero_times, not both. Use find_samples_by_time to convert times to sample indices if needed.

Examples

>>> ep = extract_epochs(my_record, "Fx",
...          n_samples=5000,
...          n_samples_before=100,
...          design=my_design,
...          zero_times=my_design.trial_time)

BeForEpochs functions#

`befordata.scale_epochs`(epochs, factor)	Scales the force data (inplace) of the BeForEpochs structure by a specified factor.
`befordata.concat_epochs`(epochs_list)	Concatenate a list or tuple of BeForEpochs instances into a single BeForEpochs object.
`befordata.adjust_baseline`(epochs, ...)	Adjust the baseline of each epoch (inplace) of the BeForEpochs data using the mean value of a defined sample window.

scale_epochs(epochs, factor)#

Scales the force data (inplace) of the BeForEpochs structure by a specified factor.

This function multiplies all force data in the BeForEpochs instance by the given scaling factor. The baseline is also scaled accordingly. All other attributes (sampling rate, design, zero_sample) are preserved.

Return type:

None

Parameters:

epochsBeForEpochs
factorfloat: The scaling factor to apply to the force data and baseline.

concat_epochs(epochs_list)#

Concatenate a list or tuple of BeForEpochs instances into a single BeForEpochs object.

Return type:

BeForEpochs

Parameters:

epochs_listlist or tuple of BeForEpochs: A list or tuple containing BeForEpochs objects to concatenate. All objects must have matching sample count, sampling rate, zero sample, baseline adjustment status, and design columns.

Raises:

ValueError: If the input list or tuple is empty.
TypeError: If any element in the input is not a BeForEpochs instance.

Notes

Meta data will not be copied and only the meta data of the first BeForEpochs will be used in the resulting BeForEpochs.

adjust_baseline(epochs, reference_window)#

Adjust the baseline of each epoch (inplace) of the BeForEpochs data using the mean value of a defined sample window.

Return type:

None

Parameters:

reference_windowTuple[int, int]: Tuple specifying the sample range (start, stop) used for baseline adjustment. Samples from “start” to “stop-1” will be included in the adjustment.