jumpCheckData.m

Go to the documentation of this file.

% =========================================================================== %
%> @brief checks data structure
%>
%> @details this function checks the data structure of the provided data
%> structure and returns a boolean indicating if the data structure is valid.
%> Also, if only small, obvious errors are found, the function tries to correct
%> them.
%>
%> @param data - data structure to check
%>
%> @retval valid - boolean indicating if the data structure is valid
%> @retval corrected - boolean indicating if the data structure was corrected
%> @retval data - corrected data structure
%>
%> @details the data structure must be a struct containing the following fields:
%> - tt: timetable containing the sensor data
%>   - t: datetime vector
%>   - acc: acceleration data (m/s^2), Nx3 matrix
%>   - gyr: angular velocity data (°/s), Nx3 matrix
%>   - hig: high G acceleration data (m/s^2), Nx3 matrix
%>   - mag: magnetometer data (uT), Nx3 matrix
%>   - prs: pressure data (mbar), Nx1 vector
%>   - tmp: temperature data (°C), Nx1 vector
%> - t_start: start time of the data
%> - ID: sensor ID (string)
%> - UID: sensor UID (string)
%> - name: sensor name (string)
%> - sw_version: sensor software version (string)
%> - hw_version: sensor hardware version (string)
%> - acc_range: accelerometer range (in g) (double)
%> - gyro_range: gyroscope range (in °/s) (double)
%> - mpu_cal: mpu calibration (double)
%> - act_thrs: activity threshold (double)
%> - inact_dur: inactivity duration (double)
%> - mpu_rate: mpu rate (double)
%> - adxl_rate: adxl rate (double)
%> - pres_rate: pressure rate (double)
%> - magn_en: magnetometer enable (254: off, 255: on) (double)
%> - sync: sync mode (0: idle, 1: slave, 2: master) (double)
%> - ble_address: ble address (string)
%>
%> @file jumpCheckData.m
%>
%> @copyright see the file @ref LICENSE in the root directory of the repository
% =========================================================================== %
 
function [valid, corrected, data] = jumpCheckData(data)
 
arguments
    data (1,1) struct
end
 
% initialize output
valid     = true;
corrected = false;
error_msg = "The following errors were found in the data structure:" + newline;
 
%% check if all fields are present
 
% define fields
fields = [ ...
    "tt", ...
    "t_start", ...
    "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" ...
    ];
 
% provided fields in the provided data
provided_fields = string(fieldnames(data));
 
% check for missing and additional fields
missing_fields = setdiff(fields, provided_fields);
additional_fields = setdiff(provided_fields, fields);
 
% check if all fields are present
if ~isempty(missing_fields)
    valid = false;
    error_msg = error_msg + "Missing fields: " + strjoin(missing_fields, ", ") + newline;
end
 
% check if additional fields are present
if ~isempty(additional_fields)
    valid = true;
    for i = 1:numel(additional_fields)
        % remove additional fields
        data.(additional_fields(i)) = [];
    end
end
 
%% check fields for correct data types
 
% check tt
if ~istimetable(data.tt)
    valid = false;
    error_msg = error_msg + "Field tt is not a timetable." + newline;
end
 
% check t_start
if ~isdatetime(data.t_start)
    valid = false;
    error_msg = error_msg + "Field t_start is not a datetime." + newline;
end
 
% check Strings
string_fields = ["ID", "UID", "name", "sw_version", "hw_version", "ble_address"];
for i = 1:numel(string_fields)
    if ~isstring(data.(string_fields(i)))
        if ischar(data.(string_fields(i)))
            data.(string_fields(i)) = string(data.(string_fields(i)));
            corrected = true;
        else
            valid = false;
            error_msg = error_msg + "Field " + string_fields(i) + " is not a string." + newline;
        end
    end
end
 
% check numeric fields
numeric_fields = ["acc_range", "gyro_range", "mpu_cal", "act_thrs", "inact_dur", "mpu_rate", "adxl_rate", "pres_rate", "magn_en", "sync"];
for i = 1:numel(numeric_fields)
    if ~isnumeric(data.(numeric_fields(i)))
        valid = false;
        error_msg = error_msg + "Field " + numeric_fields(i) + " is not numeric." + newline;
    end
end
 
%% check content of timetable
 
% check if all variables are present
variables = ["acc", "gyr", "hig", "mag", "prs", "tmp"];
provided_variables = string(data.tt.Properties.VariableNames);
missing_variables = setdiff(variables, data.tt.Properties.VariableNames);
if ~isempty(missing_variables)
    valid = false;
    error_msg = error_msg + "Missing variables in timetable: " + strjoin(missing_variables, ", ") + newline;
end
 
% check units of variables
units = ["m/s^2", "°/s", "m/s^2", "uT", "mbar", "°C"];
provided_units = string(data.tt.Properties.VariableUnits);
mising_units = setdiff(units, provided_units);
 
if ~isempty(mising_units)
    new_units = string(zeros(numel(mising_units), 1));
    for i = 1:numel(variables)
        this_var_idx = cell2mat(strfind(provided_variables, variables(i)));
        new_units(i) = units(this_var_idx);
    end
    data.tt.Properties.VariableUnits = new_units;
    corrected = true;
end
 
% check if is datetime
if ~isdatetime(data.tt.t)
    if isduration(data.tt.t)
        data.tt.t = data.t_start + data.tt.t;
        corrected = true;
    else
        valid = false;
        error_msg = error_msg + "Time variable is not a datetime." + newline;
    end
end
 
% check if t is the time variable
if ~strcmp(data.tt.Properties.DimensionNames{1}, "t")
    data.tt.Properties.DimensionNames{1} = "t";
    corrected = true;
end
 
 
 
% check if the time format is correct
if ~strcmp(data.tt.t.Format, "dd.MM.uuuu HH:mm:ss.SSS")
    data.tt.t.Format = "dd.MM.uuuu HH:mm:ss.SSS";
    corrected = true;
end
 
% check if first time is correct
if ~isequal(data.tt.t(1), data.t_start)
    data.t_start = data.tt.t(1);
    corrected = true;
end
 
%% output
if ~valid
    error(error_msg);
end
 
end % function