Computes the average of a set of particles.
 
  Features:
 
       - missing/pyramide fweight compensation
 
       - application of alignment parameters (tables, models, external metadata formats)
 
       - control of NaN created by introduction of out of scope values.
 
       - local normalization.
 
 
  INPUT:
 
 
     (no input arguments)  :   if this function  is called without arguments, an user GUI is opened.
 
 
     data:       The subvolumes to average can be passed over in a variety of
                 ways:
                 1) For boxes (already cropped boxe)
                   - cellarray (of volumes of filenames)
                   - a vpr structure
                   - an .asel file
                   - the name of a data folder (formatted along the Dynamo convention)
                   - a Dynamo project database query
 
                 2) For tomograms (particles will be cropped on the fly)
                    - a tomogram file name
                    - a catalogue query (@{})
                    - a volume list (.vll file)
 
                 3) Any dData object of Dynamo: those are generic
                    containers for particle data: dTomograms, dBoxes,
                    dVolumeList, etc.
                    In such cases, the table will be read directly from
                    the metadata in this object
 
 
    EXAMPLE
 
    o = daverage('tutorials/thermo1/data','-t','tutorials/thermo1/real.tbl');
 
 
 --------------------------------------------------------------------------
 
    All further input is controlled by Parameter/Value couples.
 
    Possible modifiers embrace different categories:
 
 
    * Alignment:
 
    'table','t':  can be passed as:
                  - filename
                  - table variable
                  - database query
 
                  * If a table is included, the maps will be transformed
                    accordingly.
                  * The table  will also describe eventual fourier
                    sampling descriptors (columns 13-18)
                  * Finally, if the 'tags' parameter is empty, the table
                    itself codes which particles are included in the average.
                    In such a case, only particles marked with '1' in column 3
                    of the table will be included.
                  * Table input is vectorizable: you can pass a cell array
                    of tables to run all the associated averaging tasks at
                    once.
                  * You can also pass the code 'random' to produce a random
                    table object.
 
 
   EXAMPLE
 
   % passing a database query:
 
   daverage my_project:data  -t my_project:table:ite=1;
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 
    * Particle selection
 
    'tags':       * declares the particle tag number of each data object
                    passed as a cell array.
 
                  * If a table is passed, 'tags' also selects which particles
                    will be used in the average. In this case, tags can be:
                    - a set of values
                    - a .tags file
                    - a code word:
                      'all':    to force all particles listed in the table
                      'average: to include only particles marked in column 3
                                of the table.
                       (default action)
 
                  * 'tags' is vectorizable: if you pass a cell array
                    with different sets of tags at each entry, you will generate
                    a different average structure for each one.
 
 
     Different ways to further restrict set of tags.
 
 
   Table restriction operators
   ---------------------------
 
   The syntax for "table restrictors" is active in this function.
   Complete explanation can be found in the help of dynamo_table_grep.
 
   'table_restrict','tr'
 
    EXAMPLE
 
    daverage test/data -t test/real.tbl -tr (abs)tilt<30;
 
    % runs the average only on those particles whose tilt angle (column 8)
    % is smaller than 30 degrees (in absolute value)
 
  - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
 
   BEST (thresholding)
 
     'best'              Selects a number of tags
                         By default, the criterion is column 10 in the
                         passed table.
 
     'best_fraction'     Selects a fraction of tag set
 
     'best_threshold'    Selectc particles above this threshold
                         (t.b.i.)
 
     'best_column'       Explicites a column different to 10 from the table
 
     'best_scores'       Explicites a set of scores that attaches a
                         quality criterion to each tag.
                         The use of this option overrides 'best_column'.
                         The value can be passed as:
                         - numeric array
                         - a file  (.txt, .em)
 
 
    GREP
 
     grep operations and best operations are mutually excluding
 
     'grep_column'       indicates which column will provide the grep
                         selection criterion
 
     'grep_selection'    selects the tags presenting this particular set of values in the
                         column indicated with 'grep_selection'
 
     'grep_interval'     selects all tags in an interval
 
 
     EXCLUDE
 
     'exclude'           Explicitely exclude a set of tags from the average
                         - array of numeric values
                         - filename
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
     * Fourier sampling
 
    'fmask':          Specifies how to read the fourier mask.
                      If the particles are affected by a missing
                      fweight/pyramide, its concrete description for each
                      particle can be passed in different ways. The value of
                      this parameter can thus be:
                       - a cellarray of 3d binary maps (as volumes or files)
                       - an .asel file
                       - A code word:
                         * 'table', indicating that descriptions are
                                     contained in the table object that has been
                                     passed as the value of the parameter 'table'
                         * 'full' enforcing full coverage of fourier space
                         * 'file', indicating that fmasks are explicitely
                                 stored in a data folder
 
                     default: 'table'
 
 
 
     'force_fmask'   boolean
                     forces the explicite application of the fourier mask on each
                     data particle.
 
     'fcompensate'   boolean
                     It will divide each component of the "raw average" of the particles
                     with the number of particles actually contributing to
                     this particular component
                     - default:   0
 
 
     'fmin'          - boolean
                     Minimum number of particles that must contribute into
                     a fourier coefficient in order to accept it.
                     Only accepted if 'fcompensate' is set to 1
                     - default: 1
 
     'fminFraction'  - Default: empty [inactive]%
                     If set to a value between 0 and 1, it overrides 'fmin'
                     and sets the fraction of particles that are needed to 
                     to accept a fourier coeffient.
                     * 0: takes everything 
                     * 1: takes nothing
 
  
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
     * Particle preprocessing before averaging
 
 
    'actions':   An "action chain" string.
                 Actions chains are explained in dynamo_particle
                 - default: 'align;nmask;nan_zero;';
 
    Further
 
    'dim':        Allows downsizing the particles before transforming them.
                  Value must be an integer. Resizings that are not power of two
                  can take long time.
 
    'norm':       normalizes each volume (after alignment, before addition). Value is of the
                  form of an array with two entries:
                    - [mean, var]
                    - default: [0,1]
 
    'nmask':      volumes will be normalized  according to this mask, and
                  with the mean and std values defined by parameter 'norm'/
                  If the mask is smaller than the data, it will be embbeded
                  in the middle of a zero volume with the dimensions of the
                  data.
                  Values:
                   - 3d array (binary)
                   - 1d array (indices)
                   - 'full':  the full volume is taken as mask
                   - default: no normalization
 
 
    'smoothing': [fraction_radius_cutoff, fraction_mollify];
                     First entry is the radius of a smoothing mask to be
                     applied on the average (and each particle).
                     [0.5,0.1];
                     - default: [0.8, 0.1];
 
     'nyquist':   particles will be bandpass to this Nyquist fraction:
                    - default: 0.6
 
 
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  
  
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   * Variance computation
   ----------------------
 
 
   'var_compute','var'   boolean (1: perform, 0: skip)
                         -default: 0, skip
 
   'var_fcompensate'     boolean
                         Takes into account the effect of missing wedge
 
   'var_actions'         some "action_chain"
 
 
   EXAMPLE
 
   output = dynamo_average(my_data,'table', my_table,'var_compute',1);
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   * FSC computation
 
   'fsc'               switcher (boolean, 0/1, 'on'/'off')
                       - default: 0: no fsc is computed
 
   'fsc_actions'       "action_chain" type of string, signaling operations
                       to perform on the odd and even subaverages before
                       computing their FSC.
 
                       In string form, you need to replace blank spaces  with '__'
                       For instance 'sym c8' can be written as sym__c8
 
   'fsc_apix','apix'   angstroms per pixel.
                       - default: 1
 
   'fsc_mask'          if a mask is passed, even and odd subaverages will
                       be masked in direct space before computing their fsc.
                       - default: no masking.
 
   'output_eo'         boolean, 0/1, 'on'/'off'
                       will include the even and odd subaverages in the
                       output structure.
 
    EXAMPLE:
 
    output = dynamo_average(my_data,'table', my_table,'fsc',1,'fsc_mask',my_file,'fsc_actions','sym c16');
 
    % then you can plot directly the computed FSC with the right labels
    dynamo_fsc_plot(output);
 
    In string notation:
    dynamo_average my_data table my_table fsc on fsc_mask my_file fsc_actions sym__c16 ws output;
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    * Output redirection
 
    'o'        :   directs the output to a file (in .em format)
                  fourier compensated average     ->          
                            raw average           ->      raw_
                  fourier weights in raw average  ->  fweight_
 
    'ws'       :  directs the output to a workspace variable.
 
                  EXAMPLE:
                  dynamo_average my_data table my_table ws output;
                  is a compacter way to write:
                  output = dynamo_average(my_data,'table',my_table);
 
    'ofsc'     :   writes the fsc into a text file
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
    * Generic tools for flow control
 
 
    'v':          verbosity
 
    'output_eo'   returns the averages of odd and even subpopulations.
 
    'oaligned'    string: pass a directory name (different from the data folder)
                  This option writes a file for each aligned particle in
                  the indicated directory.
                   - default: aligned particles are not written.
 
    'ointermediate'  string: pass a directory name (different from the data folder)
                  writes a file for each accumulated average in this
                  directory.
                   - default: accumulated averages are not written.
 
 
 
    'scan':       Advanced flag to scan the evolution of the averaging
                  process.
                  Values are strings:
                  'pause'       :  stops at the end of each particle
                  'pause_slices':  plots the average attained at each
                                   particle
                  'no'          :  skip scanning
                  - default: 'none'
 
   'extension':   informs Dynamo that the data folder uses an extension
                  different to the default .em
 
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
   OUTPUT (to command line)
 
    The ouptut structure has the following fields:
 
     .average_raw:       without compensation for overweighting
 
     .average:           with compensation for overweighting
 
     .fweight:           overrepresentation map of the .average_raw
 
     .fmask:             binary mask denoting available fourier coefficients
 
     .variance:          variance map
 
     .fsc:               fsc values
 
     .fsc_labels:        useful information to annotate fsc plots
 
     .tags:              list of tags that did actually contribute to the
                         averaging procedure.
                         This is useful to control which is the final
                         result of confronting which data is available,
                         which tags are marked in the table, and also
                         which particles where excluded.
 
 
   NOTES
 
   * Particles that go out of scope are removed from the
 
 
   EXAMPLES:
 
 
   % create the average of the aligned particles.
   % from a project
   output = dynamo_average(my_vpr,'table',my_table);
 
   % or a data folder:
 
   output=dynamo_average(my_data_folder,'table',my_table);
 
   This can be done in short notation:
 
   daverage my_data_folder -t my_table;
 
 
   % Ensures the particles are mean-free  and have std=1 inside a
   % nomrlization mask:
 
   output=dynamo_average(vpr,'table',my_table,'nmask',my_mask);
 
   % Vectorizes the averaging procedure:
   %
   output=dynamo_average(my_vpr,'table',{my_table1,my_table_2,my_table_3});
   %
   % This instruction creates a cellarray of outputs
 
 
  SEE ALSO
 
  dynamo_suabaverages
  dynamo_fsc_plot
  dynamo_average_fast