2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2010,2011,2012,2013,2014, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source directory and at http://www.gromacs.org.
9 * GROMACS is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public License
11 * as published by the Free Software Foundation; either version 2.1
12 * of the License, or (at your option) any later version.
14 * GROMACS is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with GROMACS; if not, see
21 * http://www.gnu.org/licenses, or write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
24 * If you want to redistribute modifications to GROMACS, please
25 * consider that scientific software is very special. Version
26 * control is crucial - bugs must be traceable. We will be happy to
27 * consider code for inclusion in the official distribution, but
28 * derived work must not be called official GROMACS. Details are found
29 * in the README & COPYING files - if they are missing, get the
30 * official version at http://www.gromacs.org.
32 * To help us fund GROMACS development, we humbly ask that you cite
33 * the research papers on the package. Check out http://www.gromacs.org.
37 * Implements gmx::analysismodules::Distance.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
40 * \ingroup module_trajectoryanalysis
48 #include "gromacs/analysisdata/analysisdata.h"
49 #include "gromacs/analysisdata/modules/average.h"
50 #include "gromacs/analysisdata/modules/histogram.h"
51 #include "gromacs/analysisdata/modules/plot.h"
52 #include "gromacs/fileio/trx.h"
53 #include "gromacs/math/vec.h"
54 #include "gromacs/options/basicoptions.h"
55 #include "gromacs/options/filenameoption.h"
56 #include "gromacs/options/options.h"
57 #include "gromacs/pbcutil/pbc.h"
58 #include "gromacs/selection/selection.h"
59 #include "gromacs/selection/selectionoption.h"
60 #include "gromacs/trajectoryanalysis/analysissettings.h"
61 #include "gromacs/utility/arrayref.h"
62 #include "gromacs/utility/exceptions.h"
63 #include "gromacs/utility/stringutil.h"
68 namespace analysismodules
74 class Distance : public TrajectoryAnalysisModule
79 virtual void initOptions(Options *options,
80 TrajectoryAnalysisSettings *settings);
81 virtual void initAnalysis(const TrajectoryAnalysisSettings &settings,
82 const TopologyInformation &top);
84 virtual void analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
85 TrajectoryAnalysisModuleData *pdata);
87 virtual void finishAnalysis(int nframes);
88 virtual void writeOutput();
92 std::string fnAverage_;
95 std::string fnHistogram_;
96 std::string fnAllStats_;
101 AnalysisData distances_;
103 AnalysisDataAverageModulePointer summaryStatsModule_;
104 AnalysisDataAverageModulePointer allStatsModule_;
105 AnalysisDataFrameAverageModulePointer averageModule_;
106 AnalysisDataSimpleHistogramModulePointer histogramModule_;
108 // Copy and assign disallowed by base.
112 : TrajectoryAnalysisModule(DistanceInfo::name, DistanceInfo::shortDescription),
113 meanLength_(0.1), lengthDev_(1.0), binWidth_(0.001)
115 summaryStatsModule_.reset(new AnalysisDataAverageModule());
116 summaryStatsModule_->setAverageDataSets(true);
117 distances_.addModule(summaryStatsModule_);
118 allStatsModule_.reset(new AnalysisDataAverageModule());
119 distances_.addModule(allStatsModule_);
120 averageModule_.reset(new AnalysisDataFrameAverageModule());
121 distances_.addModule(averageModule_);
122 histogramModule_.reset(new AnalysisDataSimpleHistogramModule());
123 distances_.addModule(histogramModule_);
125 registerAnalysisDataset(&distances_, "dist");
126 registerAnalysisDataset(&xyz_, "xyz");
127 registerBasicDataset(summaryStatsModule_.get(), "stats");
128 registerBasicDataset(allStatsModule_.get(), "allstats");
129 registerBasicDataset(averageModule_.get(), "average");
130 registerBasicDataset(&histogramModule_->averager(), "histogram");
135 Distance::initOptions(Options *options, TrajectoryAnalysisSettings * /*settings*/)
137 static const char *const desc[] = {
138 "[THISMODULE] calculates distances between pairs of positions",
139 "as a function of time. Each selection specifies an independent set",
140 "of distances to calculate. Each selection should consist of pairs",
141 "of positions, and the distances are computed between positions 1-2,",
143 "[TT]-oav[tt] writes the average distance as a function of time for",
145 "[TT]-oall[tt] writes all the individual distances.",
146 "[TT]-oxyz[tt] does the same, but the x, y, and z components of the",
147 "distance are written instead of the norm.",
148 "[TT]-oh[tt] writes a histogram of the distances for each selection.",
149 "The location of the histogram is set with [TT]-len[tt] and",
150 "[TT]-tol[tt]. Bin width is set with [TT]-binw[tt].",
151 "[TT]-oallstat[tt] writes out the average and standard deviation for",
152 "each individual distance, calculated over the frames.[PAR]",
153 "Note that [THISMODULE] calculates distances between fixed pairs",
154 "(1-2, 3-4, etc.) within a single selection. To calculate distances",
155 "between two selections, including minimum, maximum, and pairwise",
156 "distances, use [gmx-pairdist]."
159 options->setDescription(desc);
161 options->addOption(FileNameOption("oav").filetype(eftPlot).outputFile()
162 .store(&fnAverage_).defaultBasename("distave")
163 .description("Average distances as function of time"));
164 options->addOption(FileNameOption("oall").filetype(eftPlot).outputFile()
165 .store(&fnAll_).defaultBasename("dist")
166 .description("All distances as function of time"));
167 options->addOption(FileNameOption("oxyz").filetype(eftPlot).outputFile()
168 .store(&fnXYZ_).defaultBasename("distxyz")
169 .description("Distance components as function of time"));
170 options->addOption(FileNameOption("oh").filetype(eftPlot).outputFile()
171 .store(&fnHistogram_).defaultBasename("disthist")
172 .description("Histogram of the distances"));
173 options->addOption(FileNameOption("oallstat").filetype(eftPlot).outputFile()
174 .store(&fnAllStats_).defaultBasename("diststat")
175 .description("Statistics for individual distances"));
176 options->addOption(SelectionOption("select").storeVector(&sel_)
177 .required().dynamicMask().multiValue()
178 .description("Position pairs to calculate distances for"));
179 // TODO: Extend the histogramming implementation to allow automatic
180 // extension of the histograms to cover the data, removing the need for
181 // the first two options.
182 options->addOption(DoubleOption("len").store(&meanLength_)
183 .description("Mean distance for histogramming"));
184 options->addOption(DoubleOption("tol").store(&lengthDev_)
185 .description("Width of full distribution as fraction of [TT]-len[tt]"));
186 options->addOption(DoubleOption("binw").store(&binWidth_)
187 .description("Bin width for histogramming"));
192 * Checks that selections conform to the expectations of the tool.
194 void checkSelections(const SelectionList &sel)
196 for (size_t g = 0; g < sel.size(); ++g)
198 if (sel[g].posCount() % 2 != 0)
200 std::string message = formatString(
201 "Selection '%s' does not evaluate into an even number of positions "
202 "(there are %d positions)",
203 sel[g].name(), sel[g].posCount());
204 GMX_THROW(InconsistentInputError(message));
206 if (sel[g].isDynamic())
208 for (int i = 0; i < sel[g].posCount(); i += 2)
210 if (sel[g].position(i).selected() != sel[g].position(i+1).selected())
212 std::string message =
213 formatString("Dynamic selection %d does not select "
214 "a consistent set of pairs over the frames",
215 static_cast<int>(g + 1));
216 GMX_THROW(InconsistentInputError(message));
225 Distance::initAnalysis(const TrajectoryAnalysisSettings &settings,
226 const TopologyInformation & /*top*/)
228 checkSelections(sel_);
230 distances_.setDataSetCount(sel_.size());
231 xyz_.setDataSetCount(sel_.size());
232 for (size_t i = 0; i < sel_.size(); ++i)
234 const int distCount = sel_[i].posCount() / 2;
235 distances_.setColumnCount(i, distCount);
236 xyz_.setColumnCount(i, distCount * 3);
238 const double histogramMin = (1.0 - lengthDev_) * meanLength_;
239 const double histogramMax = (1.0 + lengthDev_) * meanLength_;
240 histogramModule_->init(histogramFromRange(histogramMin, histogramMax)
241 .binWidth(binWidth_).includeAll());
243 if (!fnAverage_.empty())
245 AnalysisDataPlotModulePointer plotm(
246 new AnalysisDataPlotModule(settings.plotSettings()));
247 plotm->setFileName(fnAverage_);
248 plotm->setTitle("Average distance");
249 plotm->setXAxisIsTime();
250 plotm->setYLabel("Distance (nm)");
251 for (size_t g = 0; g < sel_.size(); ++g)
253 plotm->appendLegend(sel_[g].name());
255 averageModule_->addModule(plotm);
260 AnalysisDataPlotModulePointer plotm(
261 new AnalysisDataPlotModule(settings.plotSettings()));
262 plotm->setFileName(fnAll_);
263 plotm->setTitle("Distance");
264 plotm->setXAxisIsTime();
265 plotm->setYLabel("Distance (nm)");
266 // TODO: Add legends? (there can be a massive amount of columns)
267 distances_.addModule(plotm);
272 AnalysisDataPlotModulePointer plotm(
273 new AnalysisDataPlotModule(settings.plotSettings()));
274 plotm->setFileName(fnAll_);
275 plotm->setTitle("Distance");
276 plotm->setXAxisIsTime();
277 plotm->setYLabel("Distance (nm)");
278 // TODO: Add legends? (there can be a massive amount of columns)
279 xyz_.addModule(plotm);
282 if (!fnHistogram_.empty())
284 AnalysisDataPlotModulePointer plotm(
285 new AnalysisDataPlotModule(settings.plotSettings()));
286 plotm->setFileName(fnHistogram_);
287 plotm->setTitle("Distance histogram");
288 plotm->setXLabel("Distance (nm)");
289 plotm->setYLabel("Probability");
290 for (size_t g = 0; g < sel_.size(); ++g)
292 plotm->appendLegend(sel_[g].name());
294 histogramModule_->averager().addModule(plotm);
297 if (!fnAllStats_.empty())
299 AnalysisDataPlotModulePointer plotm(
300 new AnalysisDataPlotModule(settings.plotSettings()));
301 plotm->setFileName(fnAllStats_);
302 plotm->setErrorsAsSeparateColumn(true);
303 plotm->setTitle("Statistics for individual distances");
304 plotm->setXLabel("Distance index");
305 plotm->setYLabel("Average/standard deviation (nm)");
306 for (size_t g = 0; g < sel_.size(); ++g)
308 plotm->appendLegend(std::string(sel_[g].name()) + " avg");
309 plotm->appendLegend(std::string(sel_[g].name()) + " std.dev.");
311 // TODO: Consider whether this output format is the best possible.
312 allStatsModule_->addModule(plotm);
318 Distance::analyzeFrame(int frnr, const t_trxframe &fr, t_pbc *pbc,
319 TrajectoryAnalysisModuleData *pdata)
321 AnalysisDataHandle distHandle = pdata->dataHandle(distances_);
322 AnalysisDataHandle xyzHandle = pdata->dataHandle(xyz_);
323 const SelectionList &sel = pdata->parallelSelections(sel_);
325 checkSelections(sel);
327 distHandle.startFrame(frnr, fr.time);
328 xyzHandle.startFrame(frnr, fr.time);
329 for (size_t g = 0; g < sel.size(); ++g)
331 distHandle.selectDataSet(g);
332 xyzHandle.selectDataSet(g);
333 for (int i = 0, n = 0; i < sel[g].posCount(); i += 2, ++n)
335 const SelectionPosition &p1 = sel[g].position(i);
336 const SelectionPosition &p2 = sel[g].position(i+1);
340 pbc_dx(pbc, p2.x(), p1.x(), dx);
344 rvec_sub(p2.x(), p1.x(), dx);
346 real dist = norm(dx);
347 bool bPresent = p1.selected() && p2.selected();
348 distHandle.setPoint(n, dist, bPresent);
349 xyzHandle.setPoints(n*3, 3, dx);
352 distHandle.finishFrame();
353 xyzHandle.finishFrame();
358 Distance::finishAnalysis(int /*nframes*/)
360 AbstractAverageHistogram &averageHistogram = histogramModule_->averager();
361 averageHistogram.normalizeProbability();
362 averageHistogram.done();
367 Distance::writeOutput()
369 SelectionList::const_iterator sel;
371 for (sel = sel_.begin(), index = 0; sel != sel_.end(); ++sel, ++index)
373 printf("%s:\n", sel->name());
374 printf(" Number of samples: %d\n",
375 summaryStatsModule_->sampleCount(index, 0));
376 printf(" Average distance: %-8.5f nm\n",
377 summaryStatsModule_->average(index, 0));
378 printf(" Standard deviation: %-8.5f nm\n",
379 summaryStatsModule_->standardDeviation(index, 0));
385 const char DistanceInfo::name[] = "distance";
386 const char DistanceInfo::shortDescription[] =
387 "Calculate distances between pairs of positions";
389 TrajectoryAnalysisModulePointer DistanceInfo::create()
391 return TrajectoryAnalysisModulePointer(new Distance);
394 } // namespace analysismodules