ClassicalStatistics.h

Go to the documentation of this file.

//# Copyright (C) 2000,2001
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library 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 Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//#        Internet email: aips2-request@nrao.edu.
//#        Postal address: AIPS++ Project Office
//#                        National Radio Astronomy Observatory
//#                        520 Edgemont Road
//#                        Charlottesville, VA 22903-2475 USA
//#
 
#ifndef SCIMATH_CLASSICALSTATISTICSS_H
#define SCIMATH_CLASSICALSTATISTICSS_H
 
#include <casacore/casa/aips.h>
 
#include <casacore/scimath/StatsFramework/StatisticsAlgorithm.h>
 
#include <casacore/scimath/StatsFramework/ClassicalQuantileComputer.h>
#include <casacore/scimath/StatsFramework/StatisticsTypes.h>
#include <casacore/scimath/StatsFramework/StatisticsUtilities.h>
#include <set>
#include <vector>
#include <utility>
 
namespace casacore {
 
template <class T> class PtrHolder;
 
// Class to calculate statistics in a "classical" sense, ie using accumulators
// with no special filtering beyond optional range filtering etc.
//
// setCalculateAsAdded() allows one to specify if statistics should be
// calculated and updated on upon each call to set/addData(). If False,
// statistics will be calculated only when getStatistic(), getStatistics(), or
// similar statistics computing methods are called. Setting this value to True
// allows the caller to not have to keep all the data accessible at once. Note
// however, that all data must be simultaneously accessible if quantile-like
// (eg median) calculations are desired.
//
// Objects of this class are instantiated using a ClassicalQuantileComputer
// object for computation of quantile-like statistics. See the documentation
// of StatisticsAlgorithm for details relating QuantileComputer classes.
 
template <
    class AccumType, class DataIterator, class MaskIterator=const Bool*,
    class WeightsIterator=DataIterator
>
class ClassicalStatistics
    : public StatisticsAlgorithm<CASA_STATP> {
 
    using ChunkType = typename StatisticsDataset<CASA_STATP>::ChunkData;
 
public:
 
    ClassicalStatistics();
 
    // copy semantics
    ClassicalStatistics(const ClassicalStatistics& cs);
 
    virtual ~ClassicalStatistics();
 
    // copy semantics
    ClassicalStatistics& operator=(const ClassicalStatistics& other);
 
    // Clone this instance
    virtual StatisticsAlgorithm<CASA_STATP>* clone() const;
    
    // get the algorithm that this object uses for computing stats
    virtual StatisticsData::ALGORITHM algorithm() const {
        return StatisticsData::CLASSICAL;
    };
 
    // <group>
    // In the following group of methods, if the size of the composite dataset
    // is smaller than <src>binningThreshholdSizeBytes</src>, the composite
    // dataset will be (perhaps partially) sorted and persisted in memory during
    // the call. In that case, and if <src>persistSortedArray</src> is True,
    // this sorted array will remain in memory after the call and will be used
    // on subsequent calls of this method when
    // <src>binningThreshholdSizeBytes</src> is greater than the size of the
    // composite dataset. If <src>persistSortedArray</src> is False, the sorted
    // array will not be stored after this call completes and so any subsequent
    // calls for which the dataset size is less than
    // <src>binningThreshholdSizeBytes</src>, the dataset will be sorted from
    // scratch. Values which are not included due to non-unity strides, are not
    // included in any specified ranges, are masked, or have associated weights
    // of zero are not considered as dataset members for quantile computations.
    // If one has a priori information regarding the number of points (npts)
    // and/or the minimum and maximum values of the data set, these can be
    // supplied to improve performance. Note however, that if these values are
    // not correct, the resulting median and/or quantile values will also not be
    // correct (although see the following notes regarding max/min). Note that
    // if this object has already had getStatistics() called, and the min and
    // max were calculated, there is no need to pass these values in as they
    // have been stored internally and used (although passing them in shouldn't
    // hurt anything). If provided, npts, the number of points falling in the
    // specified ranges which are not masked and have weights > 0, should be
    // exactly correct. <src>min</src> can be less than the true minimum, and
    // <src>max</src> can be greater than the True maximum, but for best
    // performance, these should be as close to the actual min and max as
    // possible. In order for quantile computations to occur over multiple
    // datasets, all datasets must be available. This means that if
    // setCalculateAsAdded() was previously called by passing in a value of
    // True, these methods will throw an exception as the previous call
    // indicate