2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013,2014 by the GROMACS development team.
5 * Copyright (c) 2015,2018,2019,2020, by the GROMACS development team, led by
6 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
7 * and including many others, as listed in the AUTHORS file in the
8 * top-level source directory and at http://www.gromacs.org.
10 * GROMACS is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public License
12 * as published by the Free Software Foundation; either version 2.1
13 * of the License, or (at your option) any later version.
15 * GROMACS is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with GROMACS; if not, see
22 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
25 * If you want to redistribute modifications to GROMACS, please
26 * consider that scientific software is very special. Version
27 * control is crucial - bugs must be traceable. We will be happy to
28 * consider code for inclusion in the official distribution, but
29 * derived work must not be called official GROMACS. Details are found
30 * in the README & COPYING files - if they are missing, get the
31 * official version at http://www.gromacs.org.
33 * To help us fund GROMACS development, we humbly ask that you cite
34 * the research papers on the package. Check out http://www.gromacs.org.
38 * Declares gmx::AnalysisDataAverageModule.
40 * \author Teemu Murtola <teemu.murtola@gmail.com>
42 * \ingroup module_analysisdata
44 #ifndef GMX_ANALYSISDATA_MODULES_AVERAGE_H
45 #define GMX_ANALYSISDATA_MODULES_AVERAGE_H
49 #include "gromacs/analysisdata/abstractdata.h"
50 #include "gromacs/analysisdata/arraydata.h"
51 #include "gromacs/analysisdata/datamodule.h"
52 #include "gromacs/utility/classhelpers.h"
58 * Data module for independently averaging each column in input data.
60 * Computes the average and standard deviation independently for each column in
61 * the input data. Multipoint data, multiple data sets, and missing data
62 * points are all supported.
63 * The average is always calculated over all frames and data points for a
66 * Output data contains a column for each data set in the input data, and a
67 * frame for each column in the input data. If different data sets have
68 * different number of columns, the frame count accomodates the largest data
69 * set. Other columns are padded with zero values that are additionally marked
71 * Each value in the output data is the average of the corresponding
72 * input column in the corresponding input data set. The error value for each
73 * value provides the standard deviation of the corresponding input column.
74 * average(), standardDeviation(), and sampleCount() methods are also
75 * provided for convenient access to these properties.
77 * The output data becomes available only after the input data has been
81 * \ingroup module_analysisdata
83 class AnalysisDataAverageModule : public AbstractAnalysisArrayData, public AnalysisDataModuleSerial
86 AnalysisDataAverageModule();
87 ~AnalysisDataAverageModule() override;
89 using AbstractAnalysisArrayData::setXAxis;
90 using AbstractAnalysisArrayData::setXAxisValue;
93 * Sets the averaging to happen over entire data sets.
95 * If \p bDataSets is false (the default), the module averages each
96 * column separately. The output will have a column for each data set,
97 * and a row for each column.
99 * If \p bDataSets is true, the module averages all values within
100 * a single data set into a single average/standard deviation.
101 * The output will have only one column, with one row for each data
104 void setAverageDataSets(bool bDataSets);
106 int flags() const override;
108 void dataStarted(AbstractAnalysisData* data) override;
109 void frameStarted(const AnalysisDataFrameHeader& header) override;
110 void pointsAdded(const AnalysisDataPointSetRef& points) override;
111 void frameFinished(const AnalysisDataFrameHeader& header) override;
112 void dataFinished() override;
115 * Convenience access to the average of a data column.
117 * Note that the interpretation of the parameters follows their naming:
118 * with \c setAverageDataSets(false), \p dataSet corresponds to a
119 * column in the output, but with \c setAverageDataSets(false) it
120 * corresponds to an output row. In both cases, it selects the data
121 * set; with \c setAverageDataSets(false), \p column should always be
122 * zero as there is only one value per data set.
124 real average(int dataSet, int column) const;
126 * Convenience access to the standard deviation of a data column.
128 * See average() for the interpretation of the parameters.
130 real standardDeviation(int dataSet, int column) const;
132 * Access the number of samples for a data column.
134 * See average() for the interpretation of the parameters.
136 int sampleCount(int dataSet, int column) const;
141 PrivateImplPointer<Impl> impl_;
144 //! Smart pointer to manage an AnalysisDataAverageModule object.
145 typedef std::shared_ptr<AnalysisDataAverageModule> AnalysisDataAverageModulePointer;
148 * Data module for averaging of columns for each frame.
150 * Output data has the same number of frames as the input data.
151 * The number of columns in the output data is the same as the number of data
152 * sets in the input data.
153 * Each frame in the output contains the average of the column values for each
154 * data set in the corresponding frame of the input data.
156 * Multipoint data and missing data points are both supported. The average
157 * is always calculated over all data points present in a column for a data
161 * \ingroup module_analysisdata
163 class AnalysisDataFrameAverageModule : public AbstractAnalysisData, public AnalysisDataModuleSerial
166 AnalysisDataFrameAverageModule();
167 ~AnalysisDataFrameAverageModule() override;
169 int frameCount() const override;
171 int flags() const override;
173 void dataStarted(AbstractAnalysisData* data) override;
174 void frameStarted(const AnalysisDataFrameHeader& header) override;
175 void pointsAdded(const AnalysisDataPointSetRef& points) override;
176 void frameFinished(const AnalysisDataFrameHeader& header) override;
177 void dataFinished() override;
180 AnalysisDataFrameRef tryGetDataFrameInternal(int index) const override;
181 bool requestStorageInternal(int nframes) override;
185 PrivateImplPointer<Impl> impl_;
188 //! Smart pointer to manage an AnalysisDataFrameAverageModule object.
189 typedef std::shared_ptr<AnalysisDataFrameAverageModule> AnalysisDataFrameAverageModulePointer;