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 classes for accessing data frame information.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_analysisdata
39 #ifndef GMX_ANALYSISDATA_DATAFRAME_H
40 #define GMX_ANALYSISDATA_DATAFRAME_H
44 #include "../legacyheaders/types/simple.h"
46 #include "../fatalerror/gmxassert.h"
47 #include "../utility/arrayref.h"
48 #include "../utility/flags.h"
54 * Value type for representing a single value in analysis data objects.
56 * Default copy constructor and assignment operator are used and work as
59 * Methods in this class do not throw.
62 * \ingroup module_analysisdata
64 class AnalysisDataValue
68 * Constructs an unset value.
70 AnalysisDataValue() : value_(0.0), error_(0.0) {}
72 * Constructs a value object with the given value.
74 * The constructed object is marked as set and present.
76 explicit AnalysisDataValue(real value)
77 : value_(value), error_(0.0)
80 flags_.set(efPresent);
84 * Direct access to the value.
86 * Assigning a value to this does not mark the value as set; setValue()
87 * must be used for this.
89 real &value() { return value_; }
91 * Direct access to the error estimate.
93 * Assigning a value to this does not mark the error estimate as set;
94 * setValue() must be used for this.
96 real &error() { return error_; }
97 //! Returns the value for this value.
98 real value() const { return value_; }
99 //! Returns the error estimate for this value, or zero if not set.
100 real error() const { return error_; }
102 * Returns whether this value has been set.
104 * If this method returns false, the return value of value() and
105 * error() are undefined.
107 bool isSet() const { return flags_.test(efSet); }
109 * Returns whether the error estimate for this value has been set.
111 * If this method returns false, but isSet() returns true, error()
114 bool hasError() const { return flags_.test(efErrorSet); }
116 * Returns whether this value has been marked as present.
118 * If this method returns false, it is up to the source data to define
119 * whether isSet() may return true.
121 bool isPresent() const { return flags_.test(efPresent); }
123 //! Clears and unsets this value.
126 *this = AnalysisDataValue();
129 void setValue(real value, bool bPresent = true)
133 flags_.set(efPresent, bPresent);
135 //! Sets this value and its error estimate.
136 void setValue(real value, real error, bool bPresent = true)
141 flags_.set(efErrorSet);
142 flags_.set(efPresent, bPresent);
144 //! Set only error estimate for this value.
145 void setError(real error)
148 flags_.set(efErrorSet);
152 //! Possible flags for \a flags_.
155 efSet = 1<<0, //!< Value has been set.
156 efErrorSet = 1<<1, //!< Error estimate has been set.
157 efPresent = 1<<2 //!< Value is set as present.
160 //! Value for this value.
162 //! Error estimate for this value, zero if not set.
164 //! Status flags for thise value.
165 FlagsTemplate<Flag> flags_;
168 //! Shorthand for reference to an array of data values.
169 typedef ConstArrayRef<AnalysisDataValue> AnalysisDataValuesRef;
173 * Value type for storing frame-level information for analysis data.
175 * Default copy constructor and assignment operator are used and work as
177 * Typically new objects of this type are only constructed internally by the
178 * library and in classes that are derived from AbstractAnalysisData.
180 * Methods in this class do not throw, but may contain asserts for incorrect
184 * \ingroup module_analysisdata
186 class AnalysisDataFrameHeader
190 * Constructs an invalid frame header.
192 * Return values of other methods than isValid() are unspecified for
193 * the constructed object.
195 AnalysisDataFrameHeader();
197 * Constructs a frame header from given values.
199 * \param[in] index Index of the frame. Must be >= 0.
200 * \param[in] x x coordinate for the frame.
201 * \param[in] dx Error estimate for x.
203 AnalysisDataFrameHeader(int index, real x, real dx);
206 * Returns whether the frame header corresponds to a valid frame.
208 * If returns false, return values of other methods are not specified.
215 * Returns zero-based index of the frame.
217 * The return value is >= 0 for valid frames.
218 * Should not be called for invalid frames.
222 GMX_ASSERT(isValid(), "Tried to access invalid frame header");
226 * Returns the x coordinate for the frame.
228 * Should not be called for invalid frames.
232 GMX_ASSERT(isValid(), "Tried to access invalid frame header");
236 * Returns error in the x coordinate for the frame (if applicable).
238 * All data do not provide error estimates.
239 * Typically returns zero in those cases.
241 * Should not be called for invalid frames.
245 GMX_ASSERT(isValid(), "Tried to access invalid frame header");
257 * Value type wrapper for non-mutable access to a set of data column values.
259 * Default copy constructor and assignment operator are used and work as
261 * Typically new objects of this type are only constructed internally by the
262 * library and in classes that are derived from AbstractAnalysisData.
264 * Methods in this class do not throw, but may contain asserts for incorrect
267 * The design of the interfaces is such that all objects of this type should be
268 * valid, i.e., header().isValid() should always return true.
271 * \ingroup module_analysisdata
273 class AnalysisDataPointSetRef
277 * Constructs a point set reference from given values.
279 * \param[in] header Header for the frame.
280 * \param[in] firstColumn Zero-based index of the first column.
282 * \param[in] values Values for each column.
284 * The first element in \p values should correspond to \p firstColumn.
286 AnalysisDataPointSetRef(const AnalysisDataFrameHeader &header,
288 const AnalysisDataValuesRef &values);
290 * Constructs a point set reference from given values.
292 * \param[in] header Header for the frame.
293 * \param[in] values Values for each column.
295 * The first element in \p values should correspond to the first
298 AnalysisDataPointSetRef(const AnalysisDataFrameHeader &header,
299 const std::vector<AnalysisDataValue> &values);
301 * Constructs a point set reference to a subset of columns.
303 * \param[in] points Point set to use as source.
304 * \param[in] firstColumn First column index to include.
305 * \param[in] columnCount Number of columns to include.
307 * Creates a point set that contains \p columnCount columns starting
308 * from \p firstColumn from \p points, or a subset if all requested
309 * columns are not present in \p points. If the requested column range
310 * and the range in \p points do not intersect, the result has
311 * columnCount() == 0.
313 * \p firstColumn is relative to the whole data set, i.e., not relative
314 * to points.firstColumn().
316 * Mainly intended for internal use.
318 AnalysisDataPointSetRef(const AnalysisDataPointSetRef &points,
319 int firstColumn, int columnCount);
322 * Returns the frame header for the frame of this point set.
324 const AnalysisDataFrameHeader &header() const
328 //! \copydoc AnalysisDataFrameHeader::index()
329 int frameIndex() const
331 return header_.index();
333 //! \copydoc AnalysisDataFrameHeader::x()
338 //! \copydoc AnalysisDataFrameHeader::dx()
343 //! Returns zero-based index of the first column included in this set.
344 int firstColumn() const
348 //! Returns the number of columns included in this set.
349 int columnCount() const
351 return values().size();
353 //! Returns zero-based index of the last column included in this set (inclusive).
354 int lastColumn() const
356 return firstColumn_ + columnCount() - 1;
359 * Returns reference container for all values.
361 * First value in the returned container corresponds to firstColumn().
363 const AnalysisDataValuesRef &values() const
368 * Returns data value for a column in this set.
370 * \param[in] i Zero-based column index relative to firstColumn().
371 * Should be >= 0 and < columnCount().
375 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
376 return values()[i].value();
379 * Returns error estimate for a column in this set if applicable.
381 * \param[in] i Zero-based column index relative to firstColumn().
382 * Should be >= 0 and < columnCount().
384 * Currently, this method returns zero if the source data does not
389 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
390 return values()[i].error();
393 * Returns whether a column is present in this set.
395 * \param[in] i Zero-based column index relative to firstColumn().
396 * Should be >= 0 and < columnCount().
398 * If present(i) returns false, it is depends on the source data
399 * whether y(i) and/or dy(i) are defined.
401 bool present(int i) const
403 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
404 return values()[i].isPresent();
407 * Returns true if all points in this point set are present.
409 * That is, if present() would return true for all points.
411 bool allPresent() const;
414 AnalysisDataFrameHeader header_;
416 AnalysisDataValuesRef values_;
421 * Value type wrapper for non-mutable access to a data frame.
423 * Default copy constructor and assignment operator are used and work as
425 * Typically new objects of this type are only constructed internally by the
426 * library and in classes that are derived from AbstractAnalysisData.
428 * Methods in this class do not throw, but may contain asserts for incorrect
432 * Support for multipoint data.
435 * \ingroup module_analysisdata
437 class AnalysisDataFrameRef
441 * Constructs an invalid frame reference.
443 * Return values of other methods than isValid() are unspecified for
444 * the constructed object.
446 AnalysisDataFrameRef();
448 * Constructs a frame reference from given values.
450 * \param[in] header Header for the frame.
451 * \param[in] values Values for each column.
453 AnalysisDataFrameRef(const AnalysisDataFrameHeader &header,
454 const AnalysisDataValuesRef &values);
456 * Constructs a frame reference from given values.
458 * \param[in] header Header for the frame.
459 * \param[in] values Values for each column.
461 AnalysisDataFrameRef(const AnalysisDataFrameHeader &header,
462 const std::vector<AnalysisDataValue> &values);
464 * Constructs a frame reference to a subset of columns.
466 * \param[in] frame Frame to use as source.
467 * \param[in] firstColumn First column index to include.
468 * \param[in] columnCount Number of columns to include.
470 * Creates a frame reference that contains \p columnCount columns
471 * starting from \p firstColumn from \p frame, or a subset if all
472 * requested columns are not present in \p frame.
474 * Mainly intended for internal use.
476 AnalysisDataFrameRef(const AnalysisDataFrameRef &frame,
477 int firstColumn, int columnCount);
480 * Returns whether the object refers to a valid frame.
482 * If returns false, return values of other methods are not specified.
486 return header().isValid();
488 //! Returns the header for this frame.
489 const AnalysisDataFrameHeader &header() const
493 //! \copydoc AnalysisDataFrameHeader::index()
494 int frameIndex() const
496 return header().index();
498 //! \copydoc AnalysisDataFrameHeader::x()
503 //! \copydoc AnalysisDataFrameHeader::dx()
506 return header().dx();
509 * Returns point set reference to the column values of this frame.
511 * Should not be called for invalid frames.
513 AnalysisDataPointSetRef points() const
515 GMX_ASSERT(isValid(), "Invalid data frame accessed");
516 return AnalysisDataPointSetRef(header_, 0, values_);
519 * Returns number of columns in this frame.
521 * Returns zero for an invalid frame.
523 int columnCount() const
525 return values_.size();
528 * Returns reference container for all column values.
530 const AnalysisDataValuesRef &values() const
535 * Convenience method for accessing a column value.
537 * \copydetails AnalysisDataPointSetRef::y()
541 GMX_ASSERT(isValid(), "Invalid data frame accessed");
542 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
543 return values_[i].value();
546 * Convenience method for accessing error for a column value.
548 * \copydetails AnalysisDataPointSetRef::dy()
552 GMX_ASSERT(isValid(), "Invalid data frame accessed");
553 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
554 return values_[i].error();
557 * Convenience method for accessing present status for a column.
559 * \copydetails AnalysisDataPointSetRef::present()
561 bool present(int i) const
563 GMX_ASSERT(isValid(), "Invalid data frame accessed");
564 GMX_ASSERT(i >= 0 && i < columnCount(), "Out of range data access");
565 return values_[i].isPresent();
568 * Returns true if all points in this frame are present.
570 bool allPresent() const;
573 AnalysisDataFrameHeader header_;
574 AnalysisDataValuesRef values_;