function  canvas = Hinton_diag(data,Hparams,data_range,zero_level)

%HINTON_DIAG -- Plot a Hinton diagram.
%
%  Hinton_diag(data,Hparams,[data_range,[zero_level]])
%  canvas = Hinton_diag(...)
%
%  HPARAMS is a parameter structure produced by HINTON_PARAMS.
%  DATA is a vector or a matrix with prod(size(data))==prod(Hparams.rep_sz).
%  Typically, DATA is either an activation pattern or a weight matrix.
%  DATA_RANGE(1) specifies the data value to be mapped to 'black color'.
%  When not supplied or NaN, it defaults to min(min(data(:)),zero_level).
%  DATA_RANGE(2) specifies the data value to be mapped to 'white color'.
%  When not supplied or set to NaN, it defaults to max(data(:)).
%  ZERO_LEVEL is the data value mapped to HPARAMS.colors.zero. %e.g, gray
%  When not supplied, ZERO_LEVEL defaults to 0.
%
%  Example (plot the internal representation of a stimulus):
%    P = PLExp1_params ; stim = make_PLE_stim(P,1,1,1) ;
%    Idef=make_PLFrontend(PLM_input_params); rep=PLFrontend(stim,Idef);
%    Hparams=Hinton_params('gray1'); Hinton_diag(rep,Hparams);
%
%  See also HINTON_PARAMS, PLFRONTEND, SPECTRAL_DIAG.

%  Original coding by Alexander Petrov, UC Irvine.
%  $Revision: 1.3 $  $Date: 2003/06/24 18:14 $

%-- Supply defaults
if (nargin < 4)  zero_level = 0 ; end            % default
if (nargin < 3)  data_range = [NaN,NaN] ;  end   % default
if (length(data_range)==1)  data_range = [NaN,data_range] ; end

if (isnan(data_range(1)))  
  data_range(1) = min(min(data(:)),zero_level) ;
end
if (isnan(data_range(2)))
  data_range(2) = max(data(:)) ;
end

%-- Scale DATA
span = max(data_range(2)-zero_level , zero_level-data_range(1)) ;
data = (data(:)-zero_level)./ span ;    % remap to [0:1] or [-1:+1]
colors = Hparams.colors ;
pixel_colors = round(data.*colors.span) + colors.zero ;

%-- Prepare the canvas as prescribed by HPARAMS
canvas = repmat(Hparams.colors.canv,Hparams.canv_sz) ;
if (isfield(colors,'ordinate'))
   ordinate = colors.ordinate ;
   if (ordinate > 0)      % Draw a vertical line through the middle
      midY = ceil(size(canvas,2)/2) ;
      canvas(:,midY) = ordinate ;
   end
end

%-- Represent the data by the color of various pixels on the canvas
if (~isfield(colors,'fill'))    % colored rectangular 'elements', default
   pixel_colors = repmat(pixel_colors,1,prod(Hparams.elt_sz)) ;
   canvas(Hparams.mapping(:)) = pixel_colors ;
   if (isfield(Hparams,'frame'))    % frame around each element
      canvas(Hparams.frame(:)) = Hparams.colors.frame ;
   end
else   % BW 'fill' diagram
   mapping = Hparams.mapping ;      % [35x25]
   fill_color = colors.fill ;
   for k = 1:length(data)
      idx = mapping(k,1:pixel_colors(k)) ;
      canvas(idx) = fill_color ;
   end
end

%-- Plot the diagram
image(canvas) ;       % <-- sic!
axis image xy ;       % keep the aspect ratio
set(gca,'xtick',Hparams.axis.xtick,'xticklabel',Hparams.axis.xticklabel) ;
set(gca,'ytick',Hparams.axis.ytick,'yticklabel',Hparams.axis.yticklabel) ;

%-- Apply the colormap and plot a colorbar if requested
colormap(colors.map) ;
%-  Color limits, ticks and tick labels
if (data_range(1)==0)     % min = 0
   Lim = [colors.zero colors.zero+colors.span] ;    % [2 64]
   M = data_range(2) ;    % max
   if     (M>=5)   Tick = [0:0.2:1] .* ceil(M) ;
   elseif (M>=2)   Tick = [0:0.5:ceil(M)] ;
   elseif (M>0.5)  Tick = [0:0.5:ceil(2*M)]/2 ;
   elseif (M>0.1)  Tick = [0:0.2:1] .* ceil(2*M)/2 ;
   else            Tick = [0:0.2:1] .* M ;
   end
elseif (data_range(1)<0 & data_range(2)>0)   % min<0 & max>0
   Lim = [colors.zero-colors.span colors.zero+colors.span] ;  % [2 64]
   M = data_range(2) ;    % max
   if     (M>=4)   Tick = [-1 -.5 0 +.5 +1] .* ceil(M) ;
   elseif (M>=2)   Tick = [-ceil(M):+ceil(M)] ;
   elseif (M>0.5)  Tick = [-ceil(2*M):0.5:+ceil(2*M)]/2 ;
   elseif (M>0.1)  Tick = [-ceil(5*M):0.5:+ceil(5*M)]/5 ;
   else            Tick = [-1:0.5:1] .* M ;
   end      
else
   Lim=round(((data_range-zero_level)./span).*colors.span)+colors.zero;
   Tick = data_range ;
end
Tick1 = ((Tick-zero_level)./span).*colors.span + colors.zero ;
TickLabel = reshape(sprintf('%4.1f',Tick)',4,length(Tick))' ;
%- Colorbar
if (strcmp(colors.colorbar,'vert'))
   h = colorbar('vert') ;
   set(h,'YLim',Lim,'YTick',Tick1,'YTickLabel',TickLabel) ;
elseif (strcmp(colors.colorbar,'horiz'))
   h = colorbar('horiz') ;
   set(h,'XLim',Lim,'XTick',Tick1,'XTickLabel',TickLabel) ;
end

%--- Return CANVAS
%%%%% End of file HINTON_DIAG.M
