% plot_traces - Plots a user specified portion of a matrix of traces and
% allows the user to "scroll" through the traces
%
% Inputs:
%  traces - a dataset with rows as traces and columns as time (or some
%    other variable you'd like to plot on the x-axis)
%
%  Options: 
%    Options can be added by flowing the traces variable by the
%    name of the option followed by the value for that option.
%    (See usage examples)
%
%    'StartTrace' - the first trace you'd like to display from the dataset
%    'StartPoint' - the first datapoint you'd like to display
%    'TracesPerScreen' - the number of traces to display per figure 
%    'PointsPerScreen' - number of points to display per subplot (trace)
%
% To scroll - type one of the following keys:
%    u = up
%    d = down
%    r = right
%    l = left
%    q = quit
%
% Usage:
%   plot_traces(traces) 
%      - plots each complete row (trace) as a subplot on a single figure
%   plot_traces(traces,'StartTrace',100,'TracesPerScreen',15)

% Last update: 2Oct10 - by Caroline Moore-Kochlacs (carolmk-at-salk.edu)
% Modified from a function by Glen Brown called 'waves'

function plot_traces(traces,varargin)

[n_traces n_points] = size(traces);

% set options (specified or default)

opt = set_options(varargin);

if isempty(get_option(opt,'StartTrace')), opt.StartTrace = 1; end
if isempty(get_option(opt,'StartPoint')), opt.StartPoint = 1; end
if isempty(get_option(opt,'TracesPerScreen')), opt.TracesPerScreen = n_traces; end
if isempty(get_option(opt,'PointsPerScreen')), opt.PointsPerScreen = n_points; end

% Plotting loop

figure;
x=' ';
stop_trace = opt.StartTrace + opt.TracesPerScreen - 1;
stop_point = opt.StartPoint + opt.PointsPerScreen - 1;

while x ~='q'
    
    % up
    if x=='u'
        if opt.StartTrace - 1 >= 1
            opt.StartTrace = opt.StartTrace - opt.TracesPerScreen;
            if opt.StartTrace < 1
                opt.StartTrace = 1;
            end
            stop_trace = opt.StartTrace + opt.TracesPerScreen - 1;
        end
    end
    
    % down
    if x=='d'
        if opt.StartTrace + opt.TracesPerScreen <= n_traces
            opt.StartTrace = opt.StartTrace + opt.TracesPerScreen;
            stop_trace = opt.StartTrace + opt.TracesPerScreen - 1;
        end
    end
    
    % left
    if x=='l'
        if opt.StartPoint - 1 >= 1
            opt.StartPoint = opt.StartPoint - opt.PointsPerScreen;
            if opt.StartPoint < 1
                opt.StartPoint = 1;
            end
            stop_point = opt.StartPoint + opt.PointsPerScreen - 1;
        end
    end
    
    % right
    if x=='r'
        if opt.StartPoint + opt.PointsPerScreen <= n_points
            opt.StartPoint = opt.StartPoint + opt.PointsPerScreen;
            stop_point = stop_point + opt.PointsPerScreen - 1;
        end
    end
    
    % check if run over the edge on the traces/points
    
    disp_stop_trace = stop_trace;
    n_traces_to_plot = opt.TracesPerScreen;
    if stop_trace > n_traces
        disp_stop_trace = n_traces;
        n_traces_to_plot = opt.TracesPerScreen - (n_traces - stop_trace);
    end
    
    disp_stop_point = stop_point;
    if stop_point > n_points
        disp_stop_point = opt.PointsPerScreen - (stop_point - n_points);
    end
    
    % plot the current portion of the traces
    
    % for positions of subplots (cause built-in subplot sucks)
    yHeight = .86;
    yMargin = (1 - yHeight)/2;
    ySubMargin = .01;
    ySubHeight = (yHeight - (opt.TracesPerScreen-1)*ySubMargin) / opt.TracesPerScreen;
    xWidth = .82;
    xLeft = .09;
    
    clf reset;
    
    % loop to plot each
    
    i_plot = 0;
    for i_plot_trace = opt.StartTrace:disp_stop_trace
        i_plot = i_plot+1;
        yBottom = 1 - yMargin - ySubHeight*i_plot - ySubMargin*(i_plot-1);
        position = [xLeft yBottom xWidth ySubHeight];
        subplot('position',position);
        plot(traces(i_plot_trace,opt.StartPoint:disp_stop_point),'k');
        axis tight;
        axis off;
    end
    
    fprintf('Signals %d to %d\n',opt.StartTrace,opt.StartTrace+n_traces_to_plot-1);
    fprintf('Timepoints %d to %d\n',opt.StartPoint,stop_point);
    orient tall;
    
    if (opt.StartTrace==1 && disp_stop_trace==n_traces && ...
            opt.StartPoint==1 && disp_stop_point==n_points)
        return;
    end
    
    x=input('u d l r q >> ','s');
    
end

end

% set_options - creates a structure with the options set by the user
% (simple recreation of Perl's GetOptions)

function opt = set_options(options)

n = length(options);
opt = struct();
if (ceil(n/2) ~= n/2) % check if even
    error('plot_traces:set_options','Each option requires both an option name and an option value');
else
    for i = 1:2:n
        opt = setfield(opt,options{i},options{i+1});
    end
end

end

% get_option - returns specified option (and empty if not)
function opt_value = get_option(options,opt_name)

if ~isfield(options,opt_name)
    opt_value = [];
else
    opt_value = getfield(options,opt_name);
end

end