Diffusion Instrument Control (TekRSA-Freq-vs-Time) Browse

MyLog.m
6a9eeca26bc9TekRSA-Freq-vs-Time

MyLog.m
View Options

			% Class to store data versus time.
			% Data can be continuously appended and saved. It is possible to add
			% labels (time marks) for particular moments in time. Data can be saved
			% and plotted with the time marks.
			% Metadata for this class is stored independently.
			% If instantiated as MyLog(load_path) then
			% the content is loaded from file

			classdef MyLog < matlab.mixin.Copyable

			properties (Access = public, SetObservable = true)

			% Save time as posixtime up to ms precision
			time_fmt = '%14.3f'

			% Save data as reals with up to 14 decimal digits. Trailing zeros
			% are removed by %g
			data_fmt = '%.14g'

			% Data column and line separators
			column_sep = '\t'
			line_sep = '\r\n'

			% File extension that is appended by default when saving the log
			% if a different one is not specified explicitly
			data_file_ext = '.log'

			% File extension for metadata
			meta_file_ext = '.meta'

			% Formatting options for the metadata
			metadata_opts = {}

			file_name = '' % Used to save or load the data
			data_headers = {} % Cell array of column headers

			length_lim = Inf % Keep the log length below this limit

			% Format for string representation of timestamps
			datetime_fmt = 'yyyy-MMM-dd HH:mm:ss'

			timestamps % Times at which data was aqcuired
			data % Array of measurements
			end

			properties (GetAccess = public, SetAccess = protected, ...
			SetObservable = true)

			% Structure array that stores labeled time marks
			TimeLabels = struct( ...
			'time', {}, ... % datetime object
			'time_str', {}, ... % time in text format
			'text_str', {}); % message string

			% Structure array that stores all the axes the log is plotted in
			PlotList = struct( ...
			'Axes', {}, ... % axes handles
			'DataLines',{}, ... % data line handles
			'LbLines', {}, ... % label line handles
			'BgLines', {}); % label line background handles
			end

			properties (Dependent = true)
			channel_no % Number of data colums

			data_line_fmt % Format specifier for one data row to be printed

			column_headers % Time column header + data column headers

			data_file_name % File name with extension for data saving
			meta_file_name % File name with extension for metadata saving

			timestamps_num % Timestamps converted to numeric format
			end

			methods (Access = public)
			function this = MyLog(varargin)
			P = MyClassParser(this);
			processInputs(P, this, varargin{:});
			end

			%% Save and load functionality
			% save the entire data record
			function save(this, filename)

			% Verify that the data can be saved
			assertDataMatrix(this);

			% File name can be either supplied explicitly or given as the
			% file_name property
			if nargin() < 2
			filename = this.file_name;
			else
			this.file_name = filename;
			end

			assert(~isempty(filename), 'File name is not provided.');

			datfname = this.data_file_name;

			stat = createFile(datfname);
			if ~stat
			return
			end

			% Save time labels in a separate file
			saveMetadata(this);

			fid = fopen(datfname, 'w');

			% Write column headers
			str = printDataHeaders(this);
			fprintf(fid, '%s', str);

			% Write the bulk of data
			fmt = this.data_line_fmt;
			for i = 1:length(this.timestamps)
			fprintf(fid, fmt, this.timestamps_num(i), this.data(i,:));
			end
			fclose(fid);
			end

			%% Plotting

			% Plot the log data with time labels. Reurns plotted line objects.
			function Pls = plot(this, varargin)

			% Verify that the data is a numeric matrix,
			% otherwise it cannot be plotted
			assertDataMatrix(this);

			[~, ncols] = size(this.data);

			p=inputParser();
			% Axes in which log should be plotted
			addOptional(p, 'Ax', [], @(x)assert( ...
			isa(x,'matlab.graphics.axis.Axes')\|\|...
			isa(x,'matlab.ui.control.UIAxes'),...
			'Argument must be axes or uiaxes.'));

			% If time labels are to be displayed
			addParameter(p, 'time_labels', true, @islogical);

			% If legend is to be displayed
			addParameter(p, 'legend', true, @islogical);

			% Logical vector defining the data columns to be displayed
			addParameter(p, 'isdisp', true(1,ncols), @(x) assert(...
			islogical(x) && isvector(x) && length(x)==ncols, ...
			['''isdisp'' must be a logical vector of the size ',...
			'equal to the number of data columns.']));

			% If 'reset' is true than all the data lines and time labels are
			% re-plotted with default style even if they are already present
			% in the plot
			addParameter(p, 'reset', false, @islogical);

			parse(p, varargin{:});

			if ~isempty(p.Results.Ax)
			Ax=p.Results.Ax;
			else
			Ax=gca();
			end

			% Find out if the log was already plotted in these axes. If
			% not, appned Ax to the PlotList.
			ind = findPlotInd(this, Ax);
			if isempty(ind)
			l = length(this.PlotList);
			this.PlotList(l+1).Axes = Ax;
			ind = l+1;
			end

			% Plot data
			if isempty(this.PlotList(ind).DataLines)

			% If the log was never plotted in Ax,
			% plot using default style and store the line handles
			Pls = line(Ax, this.timestamps, this.data);
			this.PlotList(ind).DataLines = Pls;
			else

			% Replace existing data
			Pls = this.PlotList(ind).DataLines;
			for i=1:length(Pls)
			Pls(i).XData = this.timestamps;
			Pls(i).YData = this.data(:,i);
			end
			end

			% Set the visibility of lines
			if ~ismember('isdisp',p.UsingDefaults)
			for i=1:ncols
			Pls(i).Visible = p.Results.isdisp(i);
			end
			end

			% Plot time labels and legend
			if (p.Results.time_labels)
			plotTimeLabels(this, Ax);
			end

			if (p.Results.legend)&&(~isempty(this.data_headers))&&...
			(~isempty(this.data))

			% Add legend only for for those lines that are displayed
			disp_ind = cellfun(@(x)strcmpi(x,'on'),{Pls.Visible});
			legend(Ax, Pls(disp_ind), this.data_headers{disp_ind},...
			'Location','southwest');
			end
			end

			%% Manipulations with log data

			% Append data point to the log
			function appendData(this, time, val, varargin)
			p = inputParser();
			addParameter(p, 'save', false, @islogical);
			parse(p, varargin{:});

			% Format checks on the input data
			assert(isa(time,'datetime')\|\|isnumeric(time),...
			['''time'' argument must be numeric or ',...
			'of the class datetime.']);
			assert(isrow(val),'''val'' argument must be a row vector.');

			if ~isempty(this.data)
			[~, ncols] = size(this.data);
			assert(length(val) == ncols,['Length of ''val'' ' ...
			'does not match the number of data columns']);
			end

			% Ensure time format
			if isa(time,'datetime')
			time.Format = this.datetime_fmt;
			end

			% Append new data and time stamps
			this.timestamps = [this.timestamps; time];
			this.data = [this.data; val];

			% Ensure the log length is within the length limit
			trim(this);

			% Optionally save the new data point to file
			if p.Results.save
			try
			if exist(this.data_file_name, 'file') == 2

			% Otherwise open for appending
			fid = fopen(this.data_file_name, 'a');
			else

			% If the file does not exist, create it and write
			% the column headers
			createFile(this.data_file_name);
			fid = fopen(this.data_file_name, 'w');

			str = printDataHeaders(this);
			fprintf(fid, '%s', str);
			end

			% Convert the new timestamps to numeric form for saving
			if isa(time,'datetime')
			time_num = posixtime(time);
			else
			time_num = time;
			end

			% Append new data points to file
			fprintf(fid, this.data_line_fmt, time_num, val);
			fclose(fid);
			catch
			warning(['Logger cannot save data at time = ',...
			datestr(datetime('now', ...
			'Format',this.datetime_fmt))]);

			% Try closing fid in case it is still open
			try
			fclose(fid);
			catch
			end
			end
			end
			end

			%% Time labels

			function plotTimeLabels(this, Ax)

			% Find out if the log was already plotted in these axes
			ind = findPlotInd(this, Ax);
			if isempty(ind)
			l = length(this.PlotList);
			this.PlotList(l+1).Axes = Ax;
			ind = l+1;
			end

			% Plot labels
			for i = 1:length(this.TimeLabels)
			T = this.TimeLabels(i);

			try
			Lbl = this.PlotList(ind).LbLines(i);

			% Update the existing label line
			Lbl.Value = T.time;
			Lbl.Label = T.text_str;

			% Update the background width - font size times the
			% number of lines
			this.PlotList(ind).BgLines(i).LineWidth = ...
			Lbl.FontSize*length(T.text_str);
			catch

			% Add new background line
			this.PlotList(ind).BgLines(i) = xline(T.time, ...
			'LineWidth', 10*length(T.text_str), ...
			'Color', [1, 1, 1]);

			% Add new label line
			this.PlotList(ind).LbLines(i) = xline(T.time, '-', ...
			T.text_str, ...
			'LineWidth', 0.5, ...
			'LabelHorizontalAlignment', 'center', ...
			'FontSize', 10);
			end
			end
			end

			% Remove existing labels from the plot
			function eraseTimeLabels(this, Ax)

			% Find out if the log was already plotted in these axes
			ind=findPlotInd(this, Ax);
			if ~isempty(ind)

			% Remove existing labels
			delete(this.PlotList(ind).LbLines);
			this.PlotList(ind).LbLines=[];
			delete(this.PlotList(ind).LbText);
			this.PlotList(ind).LbText=[];
			else
			warning('Cannot erase time labels. Axes not found.')
			end
			end

			% Add label
			% Form with optional arguments: addTimeLabel(this, time, str)
			function addTimeLabel(this, varargin)
			p=inputParser();
			addOptional(p, 'time', ...
			datetime('now', 'Format', this.datetime_fmt), ...
			@(x)assert(isa(x,'datetime'), ...
			'''time'' must be of the type datetime.'));
			addOptional(p, 'str', '', ...
			@(x) assert(iscellstr(x)\|\|ischar(x)\|\|isstring(x), ...
			'''str'' must be a string or cell array of strings.'));
			addParameter(p, 'save', false, @islogical);
			parse(p, varargin{:});

			if any(ismember({'time','str'}, p.UsingDefaults))
			% Invoke a dialog to add the label time and name
			answ = inputdlg({'Label text', 'Time'},'Add time label',...
			[2 40; 1 40],{'',datestr(p.Results.time)});

			if isempty(answ)\|\|isempty(answ{1})
			return
			else
			% Conversion of the inputed value to datetime to
			% ensure proper format
			time=datetime(answ{2}, 'Format', this.datetime_fmt);
			% Store multiple lines as cell array
			str=cellstr(answ{1});
			end
			end

			% Need to calculate length explicitly as using 'end' fails
			% for an empty array
			l = length(this.TimeLabels);

			this.TimeLabels(l+1).time=time;
			this.TimeLabels(l+1).time_str=datestr(time);
			this.TimeLabels(l+1).text_str=str;

			% Order time labels by ascending time
			sortTimeLabels(this);

			if p.Results.save == true
			saveMetadata(this);
			end
			end

			function deleteTimeLabel(this, ind)
			end

			% Modify text or time of an exising label. If new time and text are
			% not provided as arguments, modifyTimeLabel(this, ind, time, str),
			% invoke a dialog.
			% ind - index of the label to be modified in TimeLabels array.
			function modifyTimeLabel(this, ind, varargin)
			p=inputParser();
			addRequired(p, 'ind', @(x)assert((rem(x,1)==0)&&(x>0), ...
			'''ind'' must be a positive integer.'));
			addOptional(p, 'time', ...
			datetime('now', 'Format', this.datetime_fmt), ...
			@(x)assert(isa(x,'datetime'), ...
			'''time'' must be of the type datetime.'));
			addOptional(p, 'str', '', ...
			@(x) assert(iscellstr(x)\|\|ischar(x)\|\|isstring(x), ...
			'''str'' must be a string or cell array of strings.'));
			addParameter(p, 'save', false, @islogical);
			parse(p, ind, varargin{:});

			if any(ismember({'time','str'}, p.UsingDefaults))
			Tlb=this.TimeLabels(ind);
			answ = inputdlg({'Label text', 'Time'},'Modify time label',...
			[2 40; 1 40],{char(Tlb.text_str), Tlb.time_str});

			if isempty(answ)\|\|isempty(answ{1})
			return
			else
			% Convert the input value to datetime and ensure
			% proper format

			time=datetime(answ{2}, 'Format', this.datetime_fmt);

			% Store multiple lines as cell array
			str=cellstr(answ{1});
			end
			end

			this.TimeLabels(ind).time=time;
			this.TimeLabels(ind).time_str=datestr(time);
			this.TimeLabels(ind).text_str=str;

			% Order time labels by ascending time
			sortTimeLabels(this);

			if p.Results.save == true
			saveMetadata(this);
			end
			end

			% Show the list of labels in a readable format
			function lst = printTimeLabels(this)

			% The returned output is a list of character strings
			lst = cell(length(this.TimeLabels), 1);

			for i=1:length(this.TimeLabels)
			if ischar(this.TimeLabels(i).text_str) \|\|...
			isstring(this.TimeLabels(i).text_str)
			tmpstr = this.TimeLabels(i).text_str;
			elseif iscell(this.TimeLabels(i).text_str)

			% If text is cell array, elements corresponding to
			% multiple lines, display the first line
			tmpstr = this.TimeLabels(i).text_str{1};
			end
			lst{i}=[this.TimeLabels(i).time_str, ' ', tmpstr];
			end
			end

			%% Misc public functions

			% Clear log data and time labels
			function clear(this)

			% Clear while preserving the array types
			this.TimeLabels(:)=[];

			% Delete all the data lines and time labels
			for i=1:length(this.PlotList)
			delete(this.PlotList(i).DataLines);
			delete(this.PlotList(i).LbLines);
			delete(this.PlotList(i).LbText);
			end
			this.PlotList(:)=[];

			% Clear data and its type
			this.timestamps = [];
			this.data = [];
			end

			% Verify that the data can be saved or plotted
			function assertDataMatrix(this)
			assert(ismatrix(this.data)&&isnumeric(this.data),...
			['Data is not a numeric matrix, saving in '...
			'text format is not possible.']);
			end
			end

			methods (Access = public, Static = true)

			% Load log from file. Formatting parameters can be supplied as
			% varargin
			function L = load(filename, varargin)
			assert(exist(filename, 'file') == 2, ...
			['File ''', filename, ''' is not found.'])

			L = MyLog(varargin{:});
			L.file_name = filename;

			% Load metadata if file is found
			if exist(L.meta_file_name, 'file') == 2
			Mdt = MyMetadata.load(L.meta_file_name,L.metadata_opts{:});
			setMetadata(L, Mdt);
			else
			disp(['Log metadata file is not found, continuing ' ...
			'without it.']);
			end

			% Read column headers from the data file
			fid = fopen(filename,'r');
			dat_col_heads = strsplit(fgetl(fid), L.column_sep, ...
			'CollapseDelimiters', true);
			fclose(fid);

			% Assign column headers
			if length(dat_col_heads) > 1
			L.data_headers = dat_col_heads(2:end);
			end

			% Read data as delimiter-separated values and convert to cell
			% array, skip the first line containing column headers
			fulldata = dlmread(filename, L.column_sep, 1, 0);

			L.data = fulldata(:, 2:end);
			L.timestamps = fulldata(:, 1);

			% Convert time stamps to datetime if the time column header
			% is 'posixtime'
			if ~isempty(dat_col_heads) && ...
			contains(dat_col_heads{1}, 'posix', 'IgnoreCase', true)
			L.timestamps = datetime(L.timestamps, ...
			'ConvertFrom', 'posixtime', 'Format', L.datetime_fmt);
			end
			end
			end

			methods (Access = protected)
			%% Auxiliary private functions

			% Ensure the log length is within length limit
			function trim(this)
			len = length(this.timestamps);
			if len > this.length_lim

			% Remove data points beyond the length limit
			dn = len-this.length_lim;
			this.timestamps(1:dn) = [];
			this.data(1:dn) = [];

			% Remove the time labels which times fall outside the
			% range of trimmed data
			BeginTime = this.timestamps(1);
			ind = [this.TimeLabels.time] < BeginTime;
			this.TimeLabels(ind) = [];
			end
			end

			% Print column names to a string
			function str = printDataHeaders(this)
			cs = this.column_sep;
			str = sprintf(['%s',cs], this.column_headers{:});
			str = [str, sprintf(this.line_sep)];
			end

			% Find out if the log was already plotted in the axes Ax and return
			% the corresponding index of PlotList if it was
			function ind = findPlotInd(this, Ax)
			assert(isvalid(Ax),'Ax must be valid axes or uiaxes')

			if ~isempty(this.PlotList)
			ind_b=cellfun(@(x) isequal(x, Ax),{this.PlotList.Axes});
			% Find index of the first match
			ind=find(ind_b,1);
			else
			ind=[];
			end
			end

			% Re-order the elements of TimeLabels array so that labels
			% corresponding to later times have larger index
			function sortTimeLabels(this)
			times = [this.TimeLabels.time];
			[~,ind] = sort(times);
			this.TimeLabels = this.TimeLabels(ind);
			end

			% Create metadata from log properties
			function Mdt = getMetadata(this)

			if ~isempty(this.TimeLabels)

			% Add the textual part of TimeLabels structure
			Mdt = MyMetadata(this.metadata_opts{:}, ...
			'title', 'TimeLabels');

			Lbl = struct('time_str', {this.TimeLabels.time_str}, ...
			'text_str', {this.TimeLabels.text_str});
			addParam(Mdt, 'Lbl', Lbl);
			else
			Mdt = MyMetadata.empty();
			end
			end

			% Save log metadata, owerwriting existing
			function saveMetadata(this, Mdt)
			if exist('Mdt', 'var') == 0
			Mdt = getMetadata(this);
			end

			metfilename = this.meta_file_name;

			% Create or clear the file
			stat = createFile(metfilename, 'overwrite', true);
			if ~stat
			return
			end

			save(Mdt, metfilename);
			end

			% Process metadata
			function setMetadata(this, Mdt)

			% Assign time labels
			Tl = titleref(Mdt, 'TimeLabels');
			if ~isempty(Tl)
			Lbl = Tl.ParamList.Lbl;
			for i=1:length(Lbl)
			this.TimeLabels(i).time_str = Lbl(i).time_str;
			this.TimeLabels(i).time = datetime(Lbl(i).time_str, ...
			'Format', this.datetime_fmt);
			this.TimeLabels(i).text_str = Lbl(i).text_str;
			end
			end
			end
			end

			%% Set and get methods
			methods
			function set.length_lim(this, val)
			assert(isreal(val),'''length_lim'' must be a real number');

			% Make length_lim non-negative and integer
			this.length_lim = max(0, round(val));

			% Apply the new length limit to log
			trim(this);
			end

			function set.data_headers(this, val)
			assert(iscellstr(val) && isrow(val), ['''data_headers'' must '...
			'be a row cell array of character strings.']) %#ok<ISCLSTR>

			this.data_headers = val;
			end

			% The get function for file_name adds extension if it is not
			% already present and also ensures proper file separators
			% (by splitting and combining the file name)
			function fname = get.data_file_name(this)
			fname = this.file_name;
			[filepath,name,ext] = fileparts(fname);
			if isempty(ext)
			ext = this.data_file_ext;
			end
			fname = fullfile(filepath,[name,ext]);
			end

			function fname = get.meta_file_name(this)
			fname = this.file_name;
			[filepath,name,~] = fileparts(fname);
			ext=this.meta_file_ext;
			fname = fullfile(filepath,[name,ext]);
			end

			function data_line_fmt=get.data_line_fmt(this)
			cs=this.column_sep;
			nl=this.line_sep;

			if isempty(this.data)
			l=0;
			else
			[~,l]=size(this.data);
			end

			data_line_fmt = this.time_fmt;
			for i=1:l
			data_line_fmt = [data_line_fmt, cs, this.data_fmt]; %#ok<AGROW>
			end
			data_line_fmt = [data_line_fmt, nl];
			end

			function hdrs=get.column_headers(this)

			% Add header for the time column
			if isa(this.timestamps,'datetime')
			time_title_str = 'POSIX time (s)';
			else
			time_title_str = 'Time';
			end
			hdrs=[time_title_str,this.data_headers];
			end

			function time_num_arr=get.timestamps_num(this)

			% Convert time stamps to numbers
			if isa(this.timestamps,'datetime')
			time_num_arr=posixtime(this.timestamps);
			else
			time_num_arr=this.timestamps;
			end
			end

			function val = get.channel_no(this)
			val = length(this.data_headers);
			end
			end
			end

rINSTCONTROL/@MyLog/MyLog.m6a9eeca26bc9TekRSA-Freq-vs-Time

MyLog.mView Options

rINSTCONTROL/@MyLog/MyLog.m
6a9eeca26bc9TekRSA-Freq-vs-Time

MyLog.m
View Options