1 /***************************************************************************
2                           qgshistogram.h
3                           --------------
4     begin                : May 2015
5     copyright            : (C) 2015 by Nyall Dawson
6     email                : nyall dot dawson at gmail dot com
7  ***************************************************************************/
8 
9 /***************************************************************************
10  *                                                                         *
11  *   This program is free software; you can redistribute it and/or modify  *
12  *   it under the terms of the GNU General Public License as published by  *
13  *   the Free Software Foundation; either version 2 of the License, or     *
14  *   (at your option) any later version.                                   *
15  *                                                                         *
16  ***************************************************************************/
17 
18 #ifndef QGSHISTOGRAM_H
19 #define QGSHISTOGRAM_H
20 
21 #include <QList>
22 
23 #include "qgis_core.h"
24 #include "qgsfeedback.h"
25 
26 class QgsVectorLayer;
27 
28 
29 /**
30  * \ingroup core
31  * \class QgsHistogram
32  * \brief Calculator for a numeric histogram from a list of values.
33  *
34  * \since QGIS 2.9
35  */
36 
37 class CORE_EXPORT QgsHistogram
38 {
39   public:
40 
41     /**
42      * Constructor for QgsHistogram.
43      */
44     QgsHistogram() = default;
45 
46     virtual ~QgsHistogram() = default;
47 
48     /**
49      * Assigns numeric source values for the histogram.
50      * \param values list of doubles
51      */
52     void setValues( const QList<double> &values );
53 
54     /**
55      * Assigns numeric source values for the histogram from a vector layer's field or as the
56      * result of an expression.
57      * \param layer vector layer
58      * \param fieldOrExpression field name or expression to be evaluated
59      * \param feedback optional feedback object to allow cancellation of calculation
60      * \returns TRUE if values were successfully set
61      */
62     bool setValues( const QgsVectorLayer *layer, const QString &fieldOrExpression, QgsFeedback *feedback = nullptr );
63 
64     /**
65      * Calculates the optimal bin width using the Freedman-Diaconis rule. Bins widths are
66      * determined by the inter-quartile range of values and the number of values.
67      * \returns optimal width for bins
68      * \see optimalNumberBins
69      * \note values must first be specified using setValues()
70      */
71     double optimalBinWidth() const;
72 
73     /**
74      * Returns the optimal number of bins for the source values, calculated using the
75      * Freedman-Diaconis rule. The number of bins are determined by the inter-quartile range
76      * of values and the number of values.
77      * \returns optimal number of bins
78      * \see optimalBinWidth
79      * \note values must first be specified using setValues()
80      */
81     int optimalNumberBins() const;
82 
83     /**
84      * Returns a list of edges for the histogram for a specified number of bins. This list
85      * will be length bins + 1, as both the first and last value are also included.
86      * \param bins number of bins
87      * \returns list of bin edges
88      * \note values must first be specified using setValues()
89      */
90     QList<double> binEdges( int bins ) const;
91 
92     /**
93      * Returns the calculated list of the counts for the histogram bins.
94      * \param bins number of histogram bins
95      * \returns list of histogram counts
96      * \note values must first be specified using setValues()
97      */
98     QList<int> counts( int bins ) const;
99 
100   private:
101 
102     QList<double> mValues;
103     double mMax = 0;
104     double mMin = 0;
105     double mIQR = 0;
106 
107     void prepareValues();
108 
109 };
110 
111 #endif // QGSHISTOGRAM_H
112