function  espec = expand_block_spec(spec,expansions)

%EXPAND_BLOCK_SPEC -- Expand the wildcards in PLM block specification.
%
%  espec = expand_block_spec(spec)
%  espec = expand_block_spec(spec,expansions)
%
%  SPEC is a "block specification", possibly with wildcards (i.e. zeros).
%  ESPEC is a longer specification without wildcards.
%  EXPANSIONS is an optional cell array of row vectors. When not supplied
%  it defaults to {[1 2],[1 2 3],[1 2]}, which means that a 0 in the first
%  position gets expanded to a mixture of 1s and 2s, a 0 in the second
%  position gets expanded to a mixture of 1s, 2s, and 3s, and so forth.
%  See the LEVELS argument to the function FACTOR_DESIGN.
%  When SPEC is a matrix, ESPEC is also a matrix (perhaps with more rows).
%  When SPEC is a cell array of matrices, ESPEC is the cell array of
%  the correspondingly expanded matrices.
%
%  Each row in SPEC has the following structure (see MAKE_PLE_STIM).
%   1. Gabor orientation: 1, 2, or 0 (wildcard)
%   2. Gabor contrast: 1, 2, 3, or 0 (wildcard)
%   3. noise orientation: 1, 2, or 0 (wildcard)
%   4. number of replications; must be divisible by the expansion factor
%   5,6,7... arbitrary elements copied verbatim (e.g. randomizep)
%
%  Example:   expand_block_spec([0 0 1 300 1])  ==>
%     1  1  1  50  1
%     2  1  1  50  1
%     1  2  1  50  1
%     2  2  1  50  1
%     1  3  1  50  1
%     2  3  1  50  1
%
%  Typical usage: (Reproduce the two schedules of PLExp1.)
%    a=1;a6=ones(1,6);a8=ones(1,8); b=2;b6=b.*a6;b8=b.*a8; T=300;
%    s1=[a,b8,a8,b8,a6,b]'; s2=[b,a8,b8,a8,b6,a]'; N=length(s1);  %N=32
%    sched1=expand_block_spec(num2cell([zeros(N,2),s1,repmat(T,N,1)],2));
%    sched2=expand_block_spec(num2cell([zeros(N,2),s2,repmat(T,N,1)],2));
%
%  See also BLOCK_FROM_CACHE, FACTOR_DESIGN, PLMODEL1.

%  Original coding by Alexander Petrov, UC Irvine.
%  $Revision: 2.0 $  $Date: 2002/05/14 14:14 $

%-- Supply default EXPANSIONS
if (nargin < 2)
   expansions = {[1 2],[1 2 3],[1 2]} ;
end

%-- Branch depending on the type of SPEC
if (isnumeric(spec))    % matrix
   [N_rows,N_cols] = size(spec) ;
   if (N_cols < 4)
      error('Eeach specification must have at least four elements.') ;
   end
   if (all(prod(spec(:,1:3))))  % are there any wildcards present?
      espec = spec ;      % there is nothing to expand
   else  % iterate over the rows
      espec = zeros(0,N_cols) ;
      for k = 1:N_rows
         curr_spec = spec(k,:) ;
         if (all(curr_spec(:,1:3)))
            curr_espec = curr_spec ;   % nothing to expand
         else  % the real work -- expand one row
            %- Prepare LEVELS and call FACTOR_DESIGN
            %  (Note that LEVELS are reversed and the DESIGN is FLIPLRed.)
            for l = 1:3
               if (curr_spec(l)==0)
                  levels{4-l} = expansions{l} ;   % multi-level factor
               else
                  levels{4-l} = curr_spec(l) ;    % single-level factor
               end
            end
            curr_espec = fliplr(factor_design(levels)) ;
            %- Calculate the number of repetitions and copy DATA, if any
            extension_factor = size(curr_espec,1) ;
            total_N = curr_spec(4) ;
            sub_N = total_N / extension_factor ;   % must be integer
            if (N_cols > 4)
               suffix = [sub_N,curr_spec(5:N_cols)] ;
            else
               suffix = [sub_N] ;
            end
            curr_espec = [curr_espec,repmat(suffix,extension_factor,1)] ;
         end
         espec = [espec ; curr_espec] ;
      end
   end
elseif (iscell(spec))   % cell array: recurse on the constituent matrices
   sz = size(spec) ; N = prod(sz) ;
   espec = cell(sz) ;
   for k = 1:N
      espec{k} = expand_block_spec(spec{k},expansions) ;
   end
else
   error('SPEC must be either a matrix or a cell array of matrices.') ;
end

%--- Return ESPEC
%%%%% End of file EXPAND_BLOCK_SPEC.M
