averager.h

Go to the documentation of this file.

/*
 * Author: Steven Ludtke, 04/10/2003 (sludtke@bcm.edu)
 * Copyright (c) 2000-2006 Baylor College of Medicine
 *
 * This software is issued under a joint BSD/GNU license. You may use the
 * source code in this file under either license. However, note that the
 * complete EMAN2 and SPARX software packages have some GPL dependencies,
 * so you are responsible for compliance with the licenses of these packages
 * if you opt to use BSD licensing. The warranty disclaimer below holds
 * in either instance.
 *
 * This complete copyright notice must be included in any revised version of the
 * source code. Additional authorship citations may be added, but existing
 * author citations must be preserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 *
 * */
 
#ifndef eman_averager_h__
#define eman_averager_h__ 1
 
#include "emobject.h"
#include "emdata.h"
 
#include <vector>
using std::vector;
 
namespace EMAN
{
        class EMData;
        class XYData;
 
        class Averager
        {
          public:
                Averager() : result(0) {}
 
                virtual ~ Averager()
                {
                }
 
                virtual void add_image(EMData * image);
 
                virtual void add_image_list(const vector<EMData*> & images);
 
                virtual EMData * finish() = 0;
 
                virtual string get_name() const = 0;
 
                virtual string get_desc() const = 0;
 
                virtual void set_params(const Dict & new_params)
                {
                        params = new_params;
                }
 
                virtual void mult(const float& s);
 
                virtual TypeDict get_param_types() const
                {
                        TypeDict d;
                        return d;
                }
                
          protected:
                mutable Dict params;
                EMData *result;
        };
 
        class ImageAverager:public Averager
        {
          public:
                ImageAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Simple mean average of images";
                }
 
                static Averager *NEW()
                {
                        return new ImageAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("sigma", EMObject::EMDATA, "sigma value");
                        d.put("normimage", EMObject::EMDATA, "In conjunction with ignore0, the number of non zero values for each pixel will be stored in this image.");
                        d.put("ignore0", EMObject::INT, "if set, ignore zero value pixels");
                        return d;
                }
 
                virtual void mult(const float&) { }
 
                static const string NAME;
                
        private:
                EMData *sigma_image,*normimage;
                int ignore0;
                int nimg;
                int freenorm;
        };
 
        class LocalWeightAverager:public Averager
        {
          public:
                LocalWeightAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Average of images weighted by local similarity to unweighted average";
                }
 
                static Averager *NEW()
                {
                        return new LocalWeightAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
//                      d.put("weight", EMObject::XYDATA, "Radial weight. X: 0 - 0.5*sqrt(2). Y contains weights.");
                        d.put("normimage", EMObject::EMDATA, "After finish() will contain the sum of the weights in real-space");
                        d.put("dampnoise", EMObject::FLOAT, "Will set a minimum mean*x for the norm image, damping regions with poor information. Default = 0.5, 0 disables. ");
                        d.put("fourier", EMObject::INT, "If set does local weighting in Fourier rather than real space ");
                        return d;
                }
 
                static const string NAME;
                
        private:
                std::vector<EMData*> images;
                EMData *normimage;
                int freenorm;
                int nimg;
                int fourier;
        };
 
        class IterAverager:public Averager
        {
          public:
                IterAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "EXPERIMENTAL!  Not suggested for normal use. An iterative averager making use of local correlations for noise reduction";
                }
 
                static Averager *NEW()
                {
                        return new IterAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        return d;
                }
 
                static const string NAME;
                
        private:
                std::vector<EMData*> images;
        };
 
        
        class FourierWeightAverager:public Averager
        {
          public:
                FourierWeightAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Weighted mean of images in Fourier space. Each image must have weighting curve in its header, an XYData object called 'avg_weight'.";
                }
 
                static Averager *NEW()
                {
                        return new FourierWeightAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
//                      d.put("weight", EMObject::XYDATA, "Radial weight. X: 0 - 0.5*sqrt(2). Y contains weights.");
                        d.put("normimage", EMObject::EMDATA, "After finish() will contain the sum of the weights in each Fourier location. Size must be ((nx+1)/2,y)");
                        return d;
                }
 
                static const string NAME;
                
        private:
                EMData *normimage;
                int freenorm;
                int nimg;
        };
 
        
        class TomoAverager:public Averager
        {
          public:
                TomoAverager();
                virtual ~ TomoAverager()
                {
                        if (norm_image!=0) delete norm_image;
                        if (result!=0) delete result;
                }
                
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Average of volumes in Fourier space, excluding any pixels with near 0 intensity.";
                }
 
                static Averager *NEW()
                {
                        return new TomoAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("thresh_sigma", EMObject::FLOAT, "multiplied by the standard deviation of the image, below-which values are considered zero. Default = .01");
                        d.put("save_norm", EMObject::INT, "If set, will save the normalization volume as norm.hdf. Mainly for debugging purposes.");
                        d.put("normout", EMObject::EMDATA, "If set, will save the normalization volume in the given EMData object.");
                        d.put("doift", EMObject::INT, "IFT the resulting volume. Default is 1.");
 
                        return d;
                }
 
                virtual void mult(const float&) { }
 
                static const string NAME;
                
        private:
                EMData *norm_image;
                float thresh_sigma;
                float overlap;
                int nimg;
        };
 
        
        class MinMaxAverager:public Averager
        {
          public:
                MinMaxAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Finds the minimum or maximum value in each pixel";
                }
 
                static Averager *NEW()
                {
                        return new MinMaxAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        d.put("max", EMObject::INT, "If set, will find the max value, otherwise finds min");
                        d.put("abs", EMObject::INT, "If set, will find the value with the min or max absolute value. The actual value is preserved.");
                        d.put("owner", EMObject::EMDATA, "Contains the number of the input image which 'owns' the max/min value. Value will be insertion sequence number unless 'ortid' is set in each image being averaged.");
                        return d;
                }
 
                virtual void mult(const float&) { }
                
                static const string NAME;
                
        private:
                int ismax;
                int isabs;
                int nimg;
        };
 
        class MedianAverager:public Averager
        {
        public:
                MedianAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Computes the median value instead of the mean. If even number of images, averages the middle two.";
                }
 
                static Averager *NEW()
                {
                        return new MedianAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        //d.put("min", EMObject::INT, "If set, will average to minimum absolute value, by default average to max");
                        return d;
                }
 
                static const string NAME;
 
        private:
                std::vector<EMData*> imgs;
                
        };
 
 
        class CtfWtAverager:public Averager
        {
          public:
            CtfWtAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Average without CTF correction but with CTF weighting. Smoothed SNR can still have large uncertainty, so weighting by envelope-free CTF may provide more uniform results.";
                }
 
                static Averager *NEW()
                {
                        return new CtfWtAverager();
                }
 
                void set_params(const Dict & new_params)
                {
                        params = new_params;
//                      outfile = params["outfile"];
                }
                
                static const string NAME;
                
          protected:
                EMData *ctfsum;   // contains the summed SNR for the average
                int nimg;
        };
 
        class CtfWtFiltAverager:public Averager
        {
          public:
            CtfWtFiltAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Average without CTF correction but with CTF weighting and automatic filter estimated from the data. Smoothed SNR can still have large uncertainty, so weighting by envelope-free CTF may provide more uniform results.";
                }
 
                static Averager *NEW()
                {
                        return new CtfWtFiltAverager();
                }
 
                void set_params(const Dict & new_params)
                {
                        params = new_params;
//                      outfile = params["outfile"];
                }
                
                static const string NAME;
                
          protected:
                EMData *results[2];             // even/odd split for filter estimate
                EMData *ctfsum[2];              // contains the summed SNR for the average
                int nimg[2],eo;
        };
 
 
        class CtfCAutoAverager:public Averager
        {
          public:
            CtfCAutoAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Averaging with automatic CTF correction and SNR weight. No B-factor correction (as this is best done in 3-D). Bases estimated SSNR on CTF parameters, so requires EMAN2 CTF parameters.";
                }
 
                static Averager *NEW()
                {
                        return new CtfCAutoAverager();
                }
 
                void set_params(const Dict & new_params)
                {
                        params = new_params;
//                      outfile = params["outfile"];
                }
                
                static const string NAME;
                
          protected:
                EMData *snrsum;   // contains the summed SNR for the average
                int nimg;
        };
 
        class CtfCWautoAverager:public Averager
        {
          public:
            CtfCWautoAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Averaging with autmatic CTF correction. Does not require a structure factor, but only works with EMAN2's CTF model";
                }
 
                static Averager *NEW()
                {
                        return new CtfCWautoAverager();
                }
 
                void set_params(const Dict & new_params)
                {
                        params = new_params;
//                      outfile = params["outfile"];
                }
                
                static const string NAME;
                
          protected:
                EMData *snrsum;   // contains the summed SNR for the average
                int nimg;
        };
 
 
        class SigmaAverager:public Averager
        {
          public:
                SigmaAverager();
 
                void add_image( EMData * image);
                EMData * finish();
 
                string get_name() const
                {
                        return NAME;
                }
 
                string get_desc() const
                {
                        return "Computes the standard deviation of images";
                }
 
                static Averager *NEW()
                {
                        return new SigmaAverager();
                }
 
                TypeDict get_param_types() const
                {
                        TypeDict d;
                        //d.put("sigma", EMObject::EMDATA, "sigma value");
                        d.put("normimage", EMObject::EMDATA, "In conjunction with ignore0, the number of non zero values for each pixel will be stored in this image.");
                        d.put("ignore0", EMObject::INT, "if set, ignore zero value pixels");
                        return d;
                }
 
                virtual void mult(const float&) { }
 
                static const string NAME;
                
        private:
                EMData *mean_image,*normimage;
                int ignore0;
                int nimg;
                int freenorm;
        };
 
 
        // /** 
        // * VarianceAverager computes the pixel-wise variance of a list of images.
 //        */
 //        class VarianceAverager:public Averager
        // {
        //   public:
        //      VarianceAverager();
 
        //      void add_image( EMData * image);
        //      EMData * finish();
 
        //      string get_name() const
        //      {
        //              return NAME;
        //      }
 
        //      string get_desc() const
        //      {
        //              return "Pixel-wise variance of images";
        //      }
 
        //      static Averager *NEW()
        //      {
        //              return new VarianceAverager();
        //      }
 
        //      TypeDict get_param_types() const
        //      {
        //              TypeDict d;
        //              return d;
        //      }
 
        //      virtual void mult(const float&) { }
 
        //      static const string NAME;
                
        // private:
        //      EMData *mean;
        //      int nimg;
        // };
 
        template <> Factory < Averager >::Factory();
 
        void dump_averagers();
        map<string, vector<string> > dump_averagers_list();
}
 
 
        
 
 
#endif