% PLOTPROJ - plot projections of one or more ICA components along with 
%              the original data (returns the data plotted)
%
% Usage:
%   >> [projdata] = plotproj(data,weights,compnums);
%   >> [projdata] = plotproj(data,weights,compnums, ...
%                                 title,limits,chanlist,channames,colors);
%
% Inputs:
%   data        = single epoch of RUNICA input data (chans,frames) 
%   weights     = unmixing matrix (=weights*sphere)
%   compnums    = vector of component numbers to project and plot 
%
% Optional inputs:
%   title       = 'fairly short plot title' {0 -> 'PLOTPROJ'}
%   limits      = [xmin xmax ymin ymax]  (x's in msec) 
%                          {0, or both y's 0 -> data limits}
%   chanlist    = list of data channels to plot {0 -> all}
%   channames   = channel location file or structure (see READLOCS)
%   colors      = file of color codes, 3 chars per line  ('.' = space)
%                          {0 -> default color order (black/white first)}
%
% Author: Scott Makeig, SCCN/INC/UCSD, La Jolla, 05-01-96 
%
% See also: PLOTDATA

% Without color arg, reads filename for PROJCOLORS from icadefs.m

% Copyright (C) 05-01-96 from PLOTDATA Scott Makeig, SCCN/INC/UCSD,
% scott@sccn.ucsd.edu
%
% This file is part of EEGLAB, see http://www.eeglab.org
% for the documentation and details.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are met:
%
% 1. Redistributions of source code must retain the above copyright notice,
% this list of conditions and the following disclaimer.
%
% 2. Redistributions in binary form must reproduce the above copyright notice,
% this list of conditions and the following disclaimer in the documentation
% and/or other materials provided with the distribution.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
% AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
% ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
% INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
% CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
% ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
% THE POSSIBILITY OF SUCH DAMAGE.

% 05-25-96 added chanlist, nargin tests, rearranged variable order -sm
% 07-29-96 debugged, added chanlist channames option -sm
% 10-26-96 added test for column of compnums  -sm
% 02-18-97 improved usage message -sm
% 02-19-97 merged versions -sm
% 03-19-97 changed VAR to diag(COV), use datamean arg instead of frames/baseframes -sm
% 04-24-97 tested datamean for 1-epoch; replaced COV with mean-squares -sm
% 05-20-97 read icadefs for PROJCOLORS & MAXPLOTDATACHANS -sm
% 06-05-97 use arbitrary chanlist as default channames -sm 
% 06-07-97 changed order of args to conform to runica -sm
% 06-12-97 made sumdata(chanlist in line 159 below -sm
% 07-23-97 removed datamean from args; let mean distribut4e over components -sm
% 09-09-97 corrected write out line " summing " -sm
% 10-31-97 removed errcode var -sm
% 11-05-97 added test for channames when chanlist ~= 1:length(chanlist) -sm & ch
% 12-19-00 adjusted new ICAPROJ args -sm
% 01-12-01 removed sphere arg -sm
% 01-25-02 reformated help & license, added links -ad 

function [projdata] = plotproj(data,weights,compnums,titl,limits,chanlist,channels,colors);

icadefs       % read default PROJCOLORS & MAXPLOTDATACHANS variables from icadefs.m
DEFAULT_TITLE = 'plotproj()';

%
% Substitute for missing arguments
%

if nargin < 8,
    colors = 'white1st.col';
elseif colors==0,
    colors = 'white1st.col';
end

if nargin < 7,
    channels = 0;
end
if nargin < 6
    chanlist = 0;
end
if nargin < 5,
    limits = 0;
end
if nargin < 4,
    titl = 0;
end
if titl==0,
    titl = DEFAULT_TITLE;
end

if nargin < 3,
    fprintf('plotproj(): must have at least four arguments.\n\n');
    help plotproj
    return
end
%
% Test data size
%
[chans,framestot] = size(data);

frames = framestot; % assume one epoch

[wr,wc]           = size(weights);

if wc ~= chans
    fprintf('plotproj(): sizes of weights and data incompatible.\n\n');
    return
end
%
% Substitute for 0 arguments
%
if chanlist == 0,
    chanlist = [1:chans];
end
if compnums == 0,
    compnums = [1:wr];
end
if size(compnums,1)>1,        % handle column of compnums !
    compnums = compnums';
end
if length(compnums) > 256,
    fprintf('plotproj(): cannot plot more than %d channels of data at once.\n',256);
    return
end

if channels ~= 0  % if chan name file given
   if ~all(chanlist == [1:length(chanlist)])
     fprintf('plotproj(): Cannot read an arbitrary chanlist of channel names.\n');
     return
   end
end
if channels==0,
    channels = chanlist;
end

if max(compnums)>wr,
   fprintf(...
 '\n    plotproj(): Component index (%d) > number of components (%d).\n', ...
                                 max(compnums),wr);
   return
end

fprintf('Reconstructing (%d chan, %d frame) data summing %d components.\n', ...
                   chans,frames,length(compnums));
%
% Compute projected data for single components
%
projdata = data(chanlist,:);
fprintf('plotproj(): Projecting component(s) ');
for s=compnums,            % for each component 
   fprintf('%d ',s);
   proj = icaproj(data,weights,s);   % let offsets distribute 
   projdata = [projdata proj(chanlist,:)];  % append projected data onto projdata
   % size(projdata) = [length(chanlist)  framestot*(length(compnums)+1)]
end
fprintf('\n');
%     
% Compute percentage of variance accounted for
%
sumdata = icaproj(data,weights,compnums);% let offsets distribute 
sigmssq = mean(sum(data(chanlist,:).*data(chanlist,:)));
   data(chanlist,:) = data(chanlist,:) - sumdata(chanlist,:);
difmssq = mean(sum(data(chanlist,:).*data(chanlist,:)));

pvaf   = round(100.0*(1.0-difmssq/sigmssq)); % percent variance accounted for

rtitl = ['(p.v.a.f. ' int2str(pvaf) '%)'];
%
% Make the plot
%
plotdata(projdata,length(data),limits,titl,channels,colors,rtitl);
                                                % make the plot
