3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
9 * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
10 * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
11 * Copyright (c) 2001-2009, The GROMACS development team,
12 * check out http://www.gromacs.org for more information.
14 * This program is free software; you can redistribute it and/or
15 * modify it under the terms of the GNU General Public License
16 * as published by the Free Software Foundation; either version 2
17 * of the License, or (at your option) any later version.
19 * If you want to redistribute modifications, please consider that
20 * scientific software is very special. Version control is crucial -
21 * bugs must be traceable. We will be happy to consider code for
22 * inclusion in the official distribution, but derived work must not
23 * be called official GROMACS. Details are found in the README & COPYING
24 * files - if they are missing, get the official version at www.gromacs.org.
26 * To help us fund GROMACS development, we humbly ask that you cite
27 * the papers on the package - you can find them in the top README file.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares analysis data modules for calculating histograms.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_analysisdata
39 #ifndef GMX_ANALYSISDATA_MODULES_HISTOGRAM_H
40 #define GMX_ANALYSISDATA_MODULES_HISTOGRAM_H
42 #include "../analysisdata.h"
43 #include "../arraydata.h"
44 #include "../datamodule.h"
49 class AnalysisHistogramSettings;
52 * Provides "named parameter" idiom for constructing histograms.
54 * \see histogramFromBins()
55 * \see histogramFromRange()
58 * \ingroup module_analysisdata
60 class AnalysisHistogramSettingsInitializer
64 * Creates an empty initializer.
66 * Should not be called directly, but histogramFromRange() or
67 * histogramFromBins() should be used instead.
69 AnalysisHistogramSettingsInitializer();
72 * Sets the first bin location.
74 * Typically should not be called directly, but through
75 * histogramFromBins().
77 AnalysisHistogramSettingsInitializer &start(real min)
78 { min_ = min; return *this; }
80 * Sets the number of bins in the histogram.
82 * If only the first bin location is specified, this value is required
83 * (and automatically provided if histogramFromBins() is used).
84 * If both the first and last bins are specified, either this value or
85 * binWidth() is required.
87 AnalysisHistogramSettingsInitializer &binCount(int binCount)
88 { binCount_ = binCount; return *this; }
90 * Sets the first and last bin locations.
92 * Typically should not be called directly, but through
93 * histogramFromRange().
95 AnalysisHistogramSettingsInitializer &range(real min, real max)
96 { min_ = min; max_ = max; return *this; }
98 * Sets the bin width of the histogram.
100 * If only the first bin location is specified, this value is required
101 * (and automatically provided if histogramFromBins() is used).
102 * If both the first and last bins are specified, either this value or
103 * binCount() is required.
104 * If a bin width is provided with both first and last bin locations,
105 * and the given bin width does not divide the range exactly, the last
106 * bin location is adjusted to match.
108 AnalysisHistogramSettingsInitializer &binWidth(real binWidth)
109 { binWidth_ = binWidth; return *this; }
111 * Indicate that first and last bin locations to specify bin centers.
113 * If set, the first and last bin locations are interpreted as bin
115 * If not set (the default), the first and last bin locations are
116 * interpreted as the edges of the whole histogram.
118 * Cannot be specified together with roundRange().
120 AnalysisHistogramSettingsInitializer &integerBins(bool enabled = true)
121 { bIntegerBins_ = enabled; return *this; }
123 * Round first and last bin locations.
125 * If set, the resulting histogram will cover the range specified, but
126 * the actual bin locations will be rounded such that the edges fall
127 * on multiples of the bin width.
128 * Only implemented when both first and last bin location and bin width
130 * Cannot be specified together with integerBins() or with binCount().
132 AnalysisHistogramSettingsInitializer &roundRange(bool enabled = true)
133 { bRoundRange_ = enabled; return *this; }
135 * Sets the histogram to match all values.
137 * If set, the histogram behaves as if the bins at the ends extended to
140 AnalysisHistogramSettingsInitializer &includeAll(bool enabled = true)
141 { bIncludeAll_ = enabled; return *this; }
152 friend class AnalysisHistogramSettings;
156 * Initializes a histogram using a range and a bin width.
160 inline AnalysisHistogramSettingsInitializer
161 histogramFromRange(real min, real max)
163 return AnalysisHistogramSettingsInitializer().range(min, max);
167 * Initializes a histogram using bin width and the number of bins.
171 inline AnalysisHistogramSettingsInitializer
172 histogramFromBins(real start, int nbins, real binwidth)
174 return AnalysisHistogramSettingsInitializer()
175 .start(start).binCount(nbins).binWidth(binwidth);
180 * Contains parameters that specify histogram bin locations.
183 * \ingroup module_analysisdata
185 class AnalysisHistogramSettings
188 //! Initializes undefined parameters.
189 AnalysisHistogramSettings();
191 * Initializes parameters based on a named parameter object.
193 * This constructor is not explicit to allow initialization of
194 * histograms directly from AnalysisHistogramSettingsInitializer:
196 gmx::AnalysisDataSimpleHistogramModule *hist =
197 new gmx::AnalysisDataSimpleHistogramModule(
198 histogramFromRange(0.0, 5.0).binWidth(0.5));
201 AnalysisHistogramSettings(const AnalysisHistogramSettingsInitializer &settings);
203 //! Returns the left edge of the first bin.
204 real firstEdge() const { return firstEdge_; }
205 //! Returns the right edge of the first bin.
206 real lastEdge() const { return lastEdge_; }
207 //! Returns the number of bins in the histogram.
208 int binCount() const { return binCount_; }
209 //! Returns the width of a bin in the histogram.
210 real binWidth() const { return binWidth_; }
211 //! Whether values beyond the edges are mapped to the edge bins.
212 bool includeAll() const { return bAll_; }
213 //! Returns a zero-based bin index for a value, or -1 if not in range.
214 int findBin(real y) const;
220 real inverseBinWidth_;
229 class BasicHistogramImpl;
231 } // namespace internal
235 * Base class for representing histograms averaged over frames.
237 * The averaging module for a per-frame histogram is always created by the
238 * AbstractHistogramModule class, and can be accessed using
239 * AbstractHistogramModule::averager().
240 * The user can alter some properties of the average histogram directly, but
241 * the main use of the object is to postprocess the histogram once the
242 * calculation is finished.
245 * \ingroup module_analysisdata
247 class AbstractAverageHistogram : public AbstractAnalysisArrayData
250 virtual ~AbstractAverageHistogram();
252 //! Returns bin properties for the histogram.
253 const AnalysisHistogramSettings &settings() const { return settings_; }
256 * Creates a copy of the histogram with double the bin width.
258 * The caller is responsible of deleting the returned object.
260 AbstractAverageHistogram *resampleDoubleBinWidth(bool bIntegerBins) const;
262 * Creates a deep copy of the histogram.
264 * The returned histogram is not necessarily of the same dynamic type
265 * as the original object, but contains the same data from the point of
266 * view of the AbstractAverageHistogram interface.
268 * The caller is responsible of deleting the returned object.
270 AbstractAverageHistogram *clone() const;
271 //! Normalizes the histogram such that the integral over it is one.
272 void normalizeProbability();
273 //! Scales the value of each bin by an uniform scaling factor.
274 void scale(real norm);
275 //! Scales the value of each bin by a different scaling factor.
276 void scaleVector(real norm[]);
278 * Notifies attached modules of the histogram data.
280 * After this function has been called, it is no longer possible to
281 * alter the histogram.
283 void done() { AbstractAnalysisArrayData::valuesReady(); }
287 * Creates a histogram module with undefined bins.
289 * Bin parameters must be defined with init() before data input is
292 AbstractAverageHistogram();
293 //! Creates a histogram module with defined bin parameters.
294 explicit AbstractAverageHistogram(const AnalysisHistogramSettings &settings);
297 * (Re)initializes the histogram from settings.
299 void init(const AnalysisHistogramSettings &settings);
302 AnalysisHistogramSettings settings_;
304 // Copy and assign disallowed by base.
309 * Data module for per-frame histograms.
311 * Output data contains the same number of frames as the input data.
312 * Each frame contains the histogram for the points in that frame.
313 * All input columns are averaged into the same histogram.
314 * The number of columns equals the number of bins in the histogram.
317 * \ingroup module_analysisdata
319 class AnalysisDataSimpleHistogramModule : public AbstractAnalysisData,
320 public AnalysisDataModuleInterface
324 * Creates a histogram module with undefined bins.
326 * Bin parameters must be defined with init() before data input is
329 AnalysisDataSimpleHistogramModule();
330 //! Creates a histogram module with defined bin parameters.
331 explicit AnalysisDataSimpleHistogramModule(const AnalysisHistogramSettings &settings);
332 virtual ~AnalysisDataSimpleHistogramModule();
335 * (Re)initializes the histogram from settings.
337 void init(const AnalysisHistogramSettings &settings);
340 * Returns the average histogram over all frames.
342 * Can be called already before the histogram is calculated to
343 * customize the way the average histogram is calculated.
345 * \see AbstractAverageHistogram
347 AbstractAverageHistogram *averager();
349 //! Returns bin properties for the histogram.
350 const AnalysisHistogramSettings &settings() const;
352 virtual int flags() const;
354 virtual void dataStarted(AbstractAnalysisData *data);
355 virtual void frameStarted(const AnalysisDataFrameHeader &header);
356 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
357 virtual void frameFinished(const AnalysisDataFrameHeader &header);
358 virtual void dataFinished();
361 virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
362 virtual bool requestStorageInternal(int nframes);
364 PrivateImplPointer<internal::BasicHistogramImpl> impl_;
366 // Copy and assign disallowed by base.
371 * Data module for per-frame weighted histograms.
373 * Output data contains the same number of frames as the input data.
374 * Each frame contains the histogram for the points in that frame, interpreted
375 * such that the first column passed to pointsAdded() determines the bin and
376 * the rest give weights to be added to that bin (input data should have at
377 * least two colums, and at least two columns should be added at the same time).
378 * All input columns are averaged into the same histogram.
379 * The number of columns equals the number of bins in the histogram.
382 * \ingroup module_analysisdata
384 class AnalysisDataWeightedHistogramModule : public AbstractAnalysisData,
385 public AnalysisDataModuleInterface
388 //! \copydoc AnalysisDataSimpleHistogramModule::AnalysisDataSimpleHistogramModule()
389 AnalysisDataWeightedHistogramModule();
390 //! \copydoc AnalysisDataSimpleHistogramModule::AnalysisDataSimpleHistogramModule(const AnalysisHistogramSettings &)
391 explicit AnalysisDataWeightedHistogramModule(const AnalysisHistogramSettings &settings);
392 virtual ~AnalysisDataWeightedHistogramModule();
394 //! \copydoc AnalysisDataSimpleHistogramModule::init()
395 void init(const AnalysisHistogramSettings &settings);
397 //! \copydoc AnalysisDataSimpleHistogramModule::averager()
398 AbstractAverageHistogram *averager();
400 //! \copydoc AnalysisDataSimpleHistogramModule::settings()
401 const AnalysisHistogramSettings &settings() const;
403 virtual int flags() const;
405 virtual void dataStarted(AbstractAnalysisData *data);
406 virtual void frameStarted(const AnalysisDataFrameHeader &header);
407 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
408 virtual void frameFinished(const AnalysisDataFrameHeader &header);
409 virtual void dataFinished();
412 virtual AnalysisDataFrameRef tryGetDataFrameInternal(int index) const;
413 virtual bool requestStorageInternal(int nframes);
415 PrivateImplPointer<internal::BasicHistogramImpl> impl_;
417 // Copy and assign disallowed by base.
422 * Data module for bin averages.
424 * Output data contains one row for each bin; see AbstractAverageHistogram.
425 * Output data contains three columns: the first is the average over all frames
426 * for that bin, the second is the standard deviation of the values, and the
427 * third is the number of samples in that bin.
428 * The input data is interpreted such that the first column passed to
429 * pointsAdded() determines the bin and the rest give values to be added to
430 * that bin (input data should have at least two colums, and at least two
431 * columns should be added at the same time).
432 * All input columns are averaged into the same histogram.
435 * \ingroup module_analysisdata
437 class AnalysisDataBinAverageModule : public AbstractAnalysisArrayData,
438 public AnalysisDataModuleInterface
441 //! \copydoc AnalysisDataSimpleHistogramModule::AnalysisDataSimpleHistogramModule()
442 AnalysisDataBinAverageModule();
443 //! \copydoc AnalysisDataSimpleHistogramModule::AnalysisDataSimpleHistogramModule(const AnalysisHistogramSettings &)
444 explicit AnalysisDataBinAverageModule(const AnalysisHistogramSettings &settings);
445 virtual ~AnalysisDataBinAverageModule();
447 //! \copydoc AnalysisDataSimpleHistogramModule::init()
448 void init(const AnalysisHistogramSettings &settings);
450 //! \copydoc AnalysisDataSimpleHistogramModule::settings()
451 const AnalysisHistogramSettings &settings() const { return settings_; }
453 virtual int flags() const;
455 virtual void dataStarted(AbstractAnalysisData *data);
456 virtual void frameStarted(const AnalysisDataFrameHeader &header);
457 virtual void pointsAdded(const AnalysisDataPointSetRef &points);
458 virtual void frameFinished(const AnalysisDataFrameHeader &header);
459 virtual void dataFinished();
462 AnalysisHistogramSettings settings_;
464 // Copy and assign disallowed by base.