jumpCombineData.m

Go to the documentation of this file.

% =========================================================================== %
%> @brief combines multiple JUMP sensor data structures into one
%>
%> This function combines the data from multiple jumps into a single dataset.
%> It takes in the data from each jump as input and returns a combined dataset.
%>
%> @param data : array of JUMP sensor data structures (see @ref jumpReadData)
%> @param options.max_t_gap : maximum time gap between two data structures
%> to be combined, if the time gap is larger, the data structures are not
%> combined. must be given as duration or in seconds. (default: 10 seconds)
%>
%> @retval data_combined : combined JUMP sensor data structure
%> @retval join_times : array of times when the data structures were combined
%>
%> @code{.m}
%> % example usage:
%> data(1) = jumpReadData("jump_1.BIN");
%> data(2) = jumpReadData("jump_2.BIN");
%> [data_combined, join_times] = jumpCombineData(data, max_t_gap=7);
%> @endcode
%>
%> @note The data structures must have the same header information.
%>
%> see also @ref jumpReadData, @ref jumpCheckData
%>
%> @file jumpCombineData.m
%>
%> @copyright see the file @ref LICENSE in the root directory of the repository
% =========================================================================== %
 
function [data_combined, join_times] = jumpCombineData(data, options)
 
arguments
    data (1,:) struct;
    options.max_t_gap (1,1) {mustBeA(options.max_t_gap, ["duration", "numeric"])} = seconds(10);
end
 
% check the data structure
for i = 1:length(data)
    [valid, ~, data(i)] = jumpCheckData(data(i));
    assert(valid, "Data structure %d is not valid", i);
end
 
% check if the max time gap is a duration, otherwise convert
if ~isa(options.max_t_gap, "duration")
    options.max_t_gap = seconds(options.max_t_gap);
end
 
 
% check if the structures have the same header information, the header contains
% ID, UID, name, sw_version, hw_version, acc_range, gyro_range, mpu_cal,
% act_thrs, inact_dur, mpu_rate, adxl_rate, pres_rate, magn_en, sync,
% ble_address. the t_start is not checked, as this must be different
try
    assert(length(unique([data.ID]))          == 1, "ID");
    assert(length(unique([data.UID]))         == 1, "UID");
    assert(length(unique([data.name]))        == 1, "name");
    assert(length(unique([data.sw_version]))  == 1, "sw_version");
    assert(length(unique([data.hw_version]))  == 1, "hw_version");
    assert(length(unique([data.acc_range]))   == 1, "acc_range");
    assert(length(unique([data.gyro_range]))  == 1, "gyro_range");
    assert(length(unique([data.mpu_cal]))     == 1, "mpu_cal");
    assert(length(unique([data.act_thrs]))    == 1, "act_thrs");
    assert(length(unique([data.inact_dur]))   == 1, "inact_dur");
    assert(length(unique([data.mpu_rate]))    == 1, "mpu_rate");
    assert(length(unique([data.adxl_rate]))   == 1, "adxl_rate");
    assert(length(unique([data.pres_rate]))   == 1, "pres_rate");
    assert(length(unique([data.magn_en]))     == 1, "magn_en");
    assert(length(unique([data.sync]))        == 1, "sync");
    assert(length(unique([data.ble_address])) == 1, "ble_address");
catch ME
    error("The data structures must have compatible headers. At least the field %s is not the same.", ME.message);
end
 
% sort the data structures by time
[~, idx] = sort([data.t_start]);
 
% check the time gaps between the data structures
for i = numel(idx)-1
    
    % check that the data is not overlapping
    if data(idx(i)).tt.t(end) > data(idx(i+1)).tt.t(1)
        error("Data structures %d and %d are overlapping", idx(i), idx(i+1));
    end
    
    % check the time gap
    t_gap = data(idx(i+1)).tt.t(1) - data(idx(i)).tt.t(end);
    if t_gap > options.max_t_gap
        error("Time gap between data structures %d and %d is too large. It is %.1f s and is allowed to be %.1f s", idx(i), idx(i+1), seconds(t_gap), seconds(options.max_t_gap));
    end
end
 
% combine the data structures
data_combined = data(idx(1));
join_times = NaT(numel(idx)-1, 1);
for i = 2:numel(idx)
    join_times(i-1) = data(idx(i)).t_start;
    data_combined.tt = [data_combined.tt; data(idx(i)).tt];
end
 
% update the t_start
data_combined.t_start = data_combined.tt.t(1);
 
% fill gaps
data_combined.tt = retime(data_combined.tt, 'regular', 'nearest', 'TimeStep', seconds(1/data_combined.mpu_rate));