function fig_handle = frambi_plot(logs, a_names, e_names)
%frambi_plot Plot the agent and environment states
%   Usage: frambi_plot(logs, a_names, e_names);
%
%   Input parameters:
%     logs  : Cell array generated by FRAMBI_SIMULATE containing log 
%             entries for each simulation cycle (in rows) with the following
%             fields: 
%
%             - agent*: Structure containing the state of the agent.
%
%             - environment*: Structure containing the state of the environment. 
%
%             - response*: The response as returned by the function
%               agent.model.respond. Only the response of the last element 
%               in logs will be displayed, all other elements will be 
%               ignored. 
%
%     a_names : Cell array with strings specifying the field names to be 
%               plotted for the agent.
%     e_names : Cell array with strings specifying the field names to be 
%               plotted for the environment.
%
%   FRAMBI_PLOT(..) plots the specified agent and environment states obtained 
%   from FRAMBI_SIMULATE as a function of the cycle index or the time (if available). 
%   If e_names contains a state called time, this state is used for 
%   plotting instead of the cycle index. 
%
%   See the figure dynamic in EXP_BARUMERLI2024 for an example. 
%
%
%   See also: frambi_simulate frambi_disp exp_barumerli2024
%
%   References:
%     R. Barumerli and P. Majdak. FrAMBI: A Software Framework for Auditory
%     Modeling Based on Bayesian Inference. under review at Neuroinformatics,
%     2024.
%     
%
%   Url: http://amtoolbox.org/amt-1.6.0/doc/frambi/frambi_plot.php


%   #Author: Roberto Barumerli (2023): Original implementation.
%   #Author: Roberto Barumerli (2024): Integration in the AMT. 
%   #Author: Michael Mihocic (2024): Documentation fixed.
%   #Author: Piotr Majdak (2024): Adaptations for the AMT 1.6.

% This file is licensed unter the GNU General Public License (GPL) either 
% version 3 of the license, or any later version as published by the Free Software 
% Foundation. Details of the GPLv3 can be found in the AMT directory "licences" and 
% at <https://www.gnu.org/licenses/gpl-3.0.html>. 
% You can redistribute this file and/or modify it under the terms of the GPLv3. 
% This file is distributed without any warranty; without even the implied warranty 
% of merchantability or fitness for a particular purpose. 

% this helper plots the logs in a single figure

    assert(iscell(logs), 'logs should be a cell array')
%     assert(size(logs{1,1}, 2) == 2, 'logs should have two columns')
    
    % -1 since last one is dedicated to the response
    cycles = numel(logs)-1;

    % initialize
    anum = length(a_names);
    avalue = zeros(cycles, length(a_names));    
    enum = length(e_names);
    evalue = zeros(cycles, length(e_names));

    % loop over simuation cycles
    for ii=1:cycles
        if isempty(logs{ii}); continue; end

        for a=1:anum
            avalue(ii,a) = (logs{ii}.agent.(a_names{a}));
        end
        for e=1:enum
            evalue(ii,e) = (logs{ii}.environment.(e_names{e}));
        end
    end
    
    % look if time index is present otherwise use cycle's index 
    tidx = find(ismember(e_names, 'time'));
    e_names(tidx) = [];
    if isempty(tidx)
        time = 1:cycles;
    else
        time = evalue(:,tidx);
        evalue(:, tidx) = [];
    end

    % add names
    an = strcat({'Agent: '}, a_names);
    en = strcat({'Environment: '}, e_names);

    % plot
    fig_handle = figure;
    plot(time, avalue, 'o');
    hold on;
    plot(time, evalue, 's');
    xlabel('Time'); % TODO: this should be generalized
    e_names=e_names{1};
    ylabel([upper(e_names(1)) e_names(2:end)]);
    legend(horzcat(an, en), 'Interpreter','none','Location','best');
end