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
31 /*! \page histograms Histogram calculation
33 * Functions to calculate histograms are defined in histogram.h.
34 * The principle is simple: histogram calculation is set up with
35 * gmx_histogram_create() and gmx_histogram_set_*(), the histogram is sampled
36 * using the provided functions, and gmx_histogram_finish() is called to
37 * finish the sampling.
38 * Various post-processing functions can then be used to normalize the
39 * histogram in various ways and to write it into a file.
40 * gmx_histogram_get_*() can be used to access data from the histogram.
41 * gmx_histogram_free() can be used to free the memory allocated for a
45 * \section histogram_sampling Initialization and sampling
47 * A histogram calculation is initialized by calling gmx_histogram_create()
48 * or gmx_histogram_create_range().
49 * The first function takes the type of the histogram (see \ref e_histogram_t)
50 * and the number of bins, and allocates the necessary memory.
51 * The bin locations can be initialized with gmx_histogram_set_integerbins()
52 * and one of gmx_histogram_set_binwidth() and gmx_histogram_set_range().
53 * Only uniformly spaced bins are currently supported.
54 * The second initialization function takes the beginning and end of the range
56 * The treatment of values that fall outside the histogram range can be
57 * set with gmx_histogram_set_all().
58 * gmx_histogram_set_blocksize() can be used to specify a block size for error
59 * estimates. If not called, no error estimates are calculated.
60 * Otherwise, a histogram is calculated for each block of given number of
61 * frames, and the error estimated as the error of the mean of these block
63 * If the number of frames is not divisible by the block size,
64 * the last block is discarded.
65 * gmx_histogram_set_block_output() can be used to write the individual
66 * block histograms to a file (it is currently not very flexible).
68 * After initialization, three sets of sampling functions are provided
69 * to sample the differen types of histograms:
70 * - Use gmx_histogram_increment() or gmx_histogram_increment_bin() to
71 * calculate simple histograms (\ref HIST_SIMPLE histograms).
72 * - Use gmx_histogram_add() or gmx_histogram_add_to_bin() to calculate
73 * histograms where different points can have different weight
74 * (\ref HIST_WEIGHT histograms).
75 * - Use gmx_histogram_add_item() or gmx_histogram_add_item_to_bin() to
76 * calculate averages within each bin
77 * (\ref HIST_BINAVER histograms).
79 * The functions aboge that take bin indices directly do no range checking,
80 * i.e., one must ensure that the bin number is between 0 and the number of
81 * bins in the histogram. In contrast, the functions that use real values to
82 * locate the correct bin use range checking, and silently discard values
83 * outside the histogram (unless gmx_histogram_set_all() has been called).
84 * gmx_histogram_find_bin() can be used to find the bin number corresponding
85 * to a value, adhering to the gmx_histogram_set_all() setting.
87 * After a frame is sampled, gmx_histogram_finish_frame() needs to be
89 * After all data is sampled, gmx_histogram_finish() should be called.
90 * After these calls, the histogram will be normalized such that the
91 * sum over all bins equals the average number of samples per frame, and
92 * the error field contains the error of the mean at each bin.
95 * \section histogram_processing Post-processing
97 * The following functions can be used to process the histograms:
98 * - gmx_histogram_clone() makes a deep copy.
99 * - gmx_histogram_resample_dblbw() also makes a deep copy,
100 * but uses a binwidth that is double of the input one
101 * (see below for usage).
102 * - gmx_histogram_normalize_prob() normalizes a histogram such that its
103 * integral becomes one.
104 * - gmx_histogram_scale() and gmx_histogram_scale_vec() can be used
105 * to scale a histogram uniformly or non-uniformly, respectively.
107 * There are also functions to write histograms to a file:
108 * - gmx_histogram_write() writes a single histogram, optionally with
110 * - gmx_histogram_write_array() writes multiple histograms with identical
111 * bins. Values and/or errors can be written.
112 * - gmx_histogram_write_cum_array() writes cumulative histograms for
113 * multiple histograms with identical bins.
115 * gmx_histogram_resample_dblbw() is useful if a histogram and its
116 * cumulative sum are required at same points.
117 * One can then sample the histogram with half the desired binwidth, and
118 * then use gmx_histogram_resample_dblbw() to construct two different
119 * versions of the histogram (by changing \p bIntegerBins), one suitable for
120 * writing out the histogram and the other for writing the cumulative
123 * Access to the histogram data is also provided through the following
125 * - gmx_histogram_get_nbins()
126 * - gmx_histogram_get_binwidth()
127 * - gmx_histogram_get_value()
128 * - gmx_histogram_get_bin_value()
129 * - gmx_histogram_get_values()
130 * - gmx_histogram_get_errors()
132 * gmx_histogram_free() can be used to free memory associated with a
133 * histogram when it is no longer needed.
136 * \brief Implementation of functions in histogram.h.
148 #include <histogram.h>
151 * Stores data for a histogram.
153 struct gmx_histogram_t
155 /** The left edge of the first bin. */
157 /** The right edge of the last bin. */
161 /** Number of bins. */
163 /** The final histogram. */
165 /** Standard deviation of each bin (calculated from block histograms). */
168 /** Histogram type. */
170 /** Histogram flags; */
172 /** Block size for averaging. */
174 /** Output file for block histograms (can be NULL). */
177 /** Inverse bin width. */
179 /** Current histogram value. */
181 /** Current histogram count. */
183 /** Number of frames read for the current block so far. */
185 /** Number of blocks averaged so far. */
190 * \param[out] hp Histogram to create.
191 * \param[in] type Histogram type to create;
192 * \param[in] nbins Number of bins.
193 * \returns 0 on success, a non-zero error code on error.
195 * Initialized the histogram structure \p h with the provided values,
196 * allocating the necessary memory.
199 gmx_histogram_create(gmx_histogram_t
**hp
, e_histogram_t type
, int nbins
)
206 gmx_incons("number of histogram bins <= 0");
229 snew(h
->hist
, nbins
+ 1);
230 snew(h
->histerr
, nbins
+ 1);
231 snew(h
->cn
, nbins
+ 1);
232 if (type
!= HIST_SIMPLE
)
234 snew(h
->chist
, nbins
+ 1);
236 gmx_histogram_clear(h
);
243 * \param[out] hp Histogram to create.
244 * \param[in] type Histogram type to create;
245 * \param[in] start Left edge/center of the first bin
246 * (depending on \p bIntegerBins).
247 * \param[in] end Right edge/center of the last bin
248 * (depending on \p bIntegerBins).
249 * \param[in] binw Bin width.
250 * \param[in] bIntegerBins If true, histogram bins are centered at
251 * \c start+n*binwidth, otherwise the centers are at
252 * \c start+(n+0.5)*binwidth.
253 * \returns 0 on success, a non-zero error code on error.
255 * Initialized the histogram structure \p h with the provided values,
256 * allocating the necessary memory.
259 gmx_histogram_create_range(gmx_histogram_t
**hp
, e_histogram_t type
,
260 real start
, real end
, real binw
, gmx_bool bIntegerBins
)
267 if (start
>= end
|| binw
<= 0)
269 gmx_incons("histogram left edge larger than right edge or bin width <= 0");
273 /* Adjust the end points and calculate the number of bins */
276 nbins
= ceil((end
- start
) / binw
) + 1;
277 end
= start
+ (nbins
- 1) * binw
;
281 start
= binw
* floor(start
/ binw
);
282 end
= binw
* ceil(end
/ binw
);
288 nbins
= (int)((end
- start
) / binw
+ 0.5);
290 /* Create the histogram */
291 rc
= gmx_histogram_create(&h
, type
, nbins
);
297 gmx_histogram_set_integerbins(h
, bIntegerBins
);
298 gmx_histogram_set_binwidth(h
, start
, binw
);
305 * \param[in,out] h Histogram to clear.
307 * Histograms are automatically cleared when initialized; you only need to
308 * call this function if you want to reuse a histogram structure that has
309 * already been used for sampling.
312 gmx_histogram_clear(gmx_histogram_t
*h
)
320 for (i
= 0; i
<= h
->nbins
; ++i
)
335 * \param[in] h Histogram to free.
337 * The pointer \p h is invalid after the call.
340 gmx_histogram_free(gmx_histogram_t
*h
)
350 * \param[in,out] h Histogram data structure.
351 * \param[in] start Left edge/center of the first bin
352 * (depending on gmx_histogram_set_integerbins()).
353 * \param[in] binw Bin width.
354 * \returns 0 on success, a non-zero error code on error.
357 gmx_histogram_set_binwidth(gmx_histogram_t
*h
, real start
, real binw
)
361 gmx_incons("histogram binwidth <= 0");
364 if (h
->flags
& HIST_INTEGERBINS
)
370 h
->end
= start
+ h
->nbins
* binw
;
372 h
->flags
|= HIST_INITBW
;
377 * \param[in,out] h Histogram data structure.
378 * \param[in] start Left edge/center of the first bin
379 * (depending on gmx_histogram_set_integerbins()).
380 * \param[in] end Right edge/center of the last bin
381 * (depending on gmx_histogram_set_integerbins()).
382 * \returns 0 on success, a non-zero error code on error.
385 gmx_histogram_set_range(gmx_histogram_t
*h
, real start
, real end
)
389 gmx_incons("histogram left edge larger than right edge");
394 if (h
->flags
& HIST_INTEGERBINS
)
396 h
->binwidth
= (end
- start
) / (h
->nbins
- 1);
397 start
-= 0.5*h
->binwidth
;
398 end
+= 0.5*h
->binwidth
;
402 h
->binwidth
= (end
- start
) / h
->nbins
;
404 h
->invbw
= 1.0/h
->binwidth
;
405 h
->flags
&= ~HIST_INITBW
;
410 * \param[in,out] h Histogram data structure.
411 * \param[in] bIntegerBins If true, histogram bins are centered at
412 * \c start+n*binwidth, otherwise the centers are at
413 * \c start+(n+0.5)*binwidth.
416 gmx_histogram_set_integerbins(gmx_histogram_t
*h
, gmx_bool bIntegerBins
)
418 /* Adjust the ranges if they have been initialized */
419 if (h
->start
< h
->end
)
421 if (h
->flags
& HIST_INTEGERBINS
)
423 h
->start
+= 0.5*h
->binwidth
;
424 if (h
->flags
& HIST_INITBW
)
426 h
->end
+= 0.5*h
->binwidth
;
430 h
->end
-= 0.5*h
->binwidth
;
435 h
->start
-= 0.5*h
->binwidth
;
436 if (h
->flags
& HIST_INITBW
)
438 h
->end
-= 0.5*h
->binwidth
;
442 h
->end
+= 0.5*h
->binwidth
;
448 h
->flags
|= HIST_INTEGERBINS
;
452 h
->flags
&= ~HIST_INTEGERBINS
;
457 * \param[in,out] h Histogram data structure.
458 * \param[in] bAll If true, values outside the histogram edges are added
459 * to the bins at the edges.
461 * \p bAll can be used to avoid rounding errors in cases where the histogram
462 * spans the full range of possible values. If set, the values that are at
463 * the exact maximum are still correctly included.
466 gmx_histogram_set_all(gmx_histogram_t
*h
, gmx_bool bAll
)
470 h
->flags
|= HIST_ALL
;
474 h
->flags
&= ~HIST_ALL
;
479 * \param[in,out] h Histogram data structure.
480 * \param[in] bsize Block size for error estimates.
481 * \returns 0 on success, a non-zero error code on error.
483 * If \p bsize is zero, no block averaging or error estimates are done.
484 * This is also the case if this function is not called.
487 gmx_histogram_set_blocksize(gmx_histogram_t
*h
, int bsize
)
491 gmx_incons("histogram block size < 0");
499 * \param[in,out] h Histogram data structure.
500 * \param[in] fp File for block output.
501 * \returns 0 on success, a non-zero error code on error.
503 * Sets a file into which each block histogram (the histogram after each
504 * \c gmx_histogram_t::bsize frames) is written.
505 * All histograms are written to the same file, separated by empty lines.
506 * If this function is not called, the block histograms are only used for
507 * error estimation, not written to a file.
510 gmx_histogram_set_block_output(gmx_histogram_t
*h
, FILE *fp
)
514 gmx_incons("histogram block size not set but output initialized");
522 * \param[in] h Histogram data.
523 * \param[in] pos Position.
524 * \returns Bin index in \p h corresponding to \p pos, or -1 if there is no
527 * If gmx_histogram_set_all() has been called with TRUE, values outside the
528 * histogram are mapped to the bins at the edges.
531 gmx_histogram_find_bin(gmx_histogram_t
*h
, real pos
)
535 if (h
->flags
& HIST_ALL
)
544 else if (pos
>= h
->end
)
546 if (h
->flags
& HIST_ALL
)
555 /* Calculate the bin index if we are inside the box */
556 return (int)((pos
- h
->start
)*h
->invbw
);
560 * \param[in] h Histogram data.
561 * \returns Number of bins in \p h.
564 gmx_histogram_get_nbins(gmx_histogram_t
*h
)
570 * \param[in] h Histogram data.
571 * \returns Bin width of \p h, 0 if no binwidth has been set.
574 gmx_histogram_get_binwidth(gmx_histogram_t
*h
)
580 * \param[in] h Histogram data.
581 * \param[in] pos Position.
582 * \param[out] value Pointer to receive the value (can be NULL).
583 * \param[out] err Pointer to receive the value (can be NULL).
585 * If \p pos is outside the range of the histogram, zeros are returned.
588 gmx_histogram_get_value(gmx_histogram_t
*h
, real pos
, double *value
, double *err
)
593 if (pos
< h
->start
|| pos
> h
->end
)
599 bin
= gmx_histogram_find_bin(h
, pos
);
621 * \param[in] h Histogram data.
622 * \param[in] bin Bin number.
623 * \param[out] value Pointer to receive the value (can be NULL).
624 * \param[out] err Pointer to receive the value (can be NULL).
626 * If \p bin is outside the valid range, zeros are returned.
629 gmx_histogram_get_bin_value(gmx_histogram_t
*h
, int bin
, double *value
, double *err
)
633 if (bin
< 0 || bin
>= h
->nbins
)
653 * \param[in] h Histogram data.
654 * \returns Pointer to an array of values for \p h.
656 * The returned array has one element for each bin of \p h.
657 * The returned pointer should not be freed.
660 gmx_histogram_get_values(gmx_histogram_t
*h
)
666 * \param[in] h Histogram data.
667 * \returns Pointer to an array of errors for \p h.
669 * The returned array has one element for each bin of \p h.
670 * The returned pointer should not be freed.
673 gmx_histogram_get_errors(gmx_histogram_t
*h
)
679 * \param[in,out] h Histogram data.
680 * \param[in] pos Position.
683 gmx_histogram_increment(gmx_histogram_t
*h
, real pos
)
685 int bin
= gmx_histogram_find_bin(h
, pos
);
694 * \param[in,out] h Histogram data.
695 * \param[in] pos Position.
696 * \param[in] value Value to add.
699 gmx_histogram_add(gmx_histogram_t
*h
, real pos
, double value
)
701 int bin
= gmx_histogram_find_bin(h
, pos
);
706 h
->chist
[bin
] += value
;
710 * \param[in,out] h Histogram data.
711 * \param[in] pos Position.
712 * \param[in] value Value to add.
715 gmx_histogram_add_item(gmx_histogram_t
*h
, real pos
, double value
)
717 int bin
= gmx_histogram_find_bin(h
, pos
);
722 h
->chist
[bin
] += value
;
727 * \param[in,out] h Histogram data.
728 * \param[in] bin Bin number.
730 * No checks for out-of-bound errors are done: \p bin should be >=0 and
734 gmx_histogram_increment_bin(gmx_histogram_t
*h
, int bin
)
740 * \param[in,out] h Histogram data.
741 * \param[in] bin Bin number.
742 * \param[in] value Value to add.
744 * No checks for out-of-bound errors are done: \p bin should be >=0 and
748 gmx_histogram_add_to_bin(gmx_histogram_t
*h
, int bin
, double value
)
750 h
->chist
[bin
] += value
;
754 * \param[in,out] h Histogram data.
755 * \param[in] bin Bin number.
756 * \param[in] value Value to add.
758 * No checks for out-of-bound errors are done: \p bin should be >=0 and
762 gmx_histogram_add_item_to_bin(gmx_histogram_t
*h
, int bin
, double value
)
764 h
->chist
[bin
] += value
;
769 * Processes a sampled block histogram.
771 * \param[in,out] h Histogram data structure.
774 finish_histogram_block(gmx_histogram_t
*h
)
784 if (h
->flags
& HIST_ALL
)
788 h
->chist
[h
->nbins
-1] += h
->chist
[h
->nbins
];
790 h
->cn
[h
->nbins
-1] += h
->cn
[h
->nbins
];
793 for (i
= 0; i
<= h
->nbins
; ++i
)
797 v
= h
->chist
[i
] / (h
->cn
[i
] > 0 ? h
->cn
[i
] : h
->nframes
);
801 v
= ((real
)h
->cn
[i
]) / h
->nframes
;
805 fprintf(h
->blockfp
, "%10g %10g\n", h
->start
+ (i
+0.5)*h
->binwidth
, v
);
808 h
->histerr
[i
] += sqr(v
);
817 fprintf(h
->blockfp
, "\n");
824 * \param[in,out] h Histogram data structure.
826 * Should be called after each frame of data.
828 * \see gmx_histogram_finish()
831 gmx_histogram_finish_frame(gmx_histogram_t
*h
)
834 if (h
->nframes
== h
->bsize
)
836 finish_histogram_block(h
);
841 * \param[in,out] h Histogram data structure.
843 * Normalizes the histogram.
844 * Should be called after all frames have been sampled and before any
845 * post-processing of the histogram.
846 * If block size has not been set with gmx_histogram_set_blocksize(),
847 * this function does no normalization, but it should still be called,
848 * otherwise the \c gmx_histogram_t::hist array will contain only zeros.
850 * \see gmx_histogram_finish_frame()
853 gmx_histogram_finish(gmx_histogram_t
*h
)
857 if (h
->nframes
> 0 || h
->bsize
== 0)
859 if (h
->nframes
< h
->bsize
)
861 fprintf(stderr
, "Last block smaller (%d frames) than the target size (%d frames) skipped \n",
862 h
->nframes
, h
->bsize
);
866 finish_histogram_block(h
);
874 for (i
= 0; i
<= h
->nbins
; ++i
)
876 h
->hist
[i
] /= h
->nblocks
;
877 h
->histerr
[i
] /= h
->nblocks
;
878 h
->histerr
[i
] = sqrt((h
->histerr
[i
] - sqr(h
->hist
[i
])) / h
->nblocks
);
883 * \param[out] destp Destination histogram.
884 * \param[in] src Source histogram.
885 * \param[in] bIntegerBins Control bin center position.
887 * Uses \p src to create a new histogram that has double the binwidth.
888 * If \p bIntegerBins is TRUE, the first new bin will be centered at
889 * \c src->start, otherwise the left edge will be at \c src->start.
891 * This function is mostly useful if one needs to sample both the
892 * histogram and the cumulative histogram at same points.
893 * To achieve this, first sample a histogram with half the desired
894 * binwidth, and then use this function to create two different verions
895 * of it with different values of \p bIntegerBins.
896 * gmx_histogram_write_array() and gmx_histogram_write_cum_array() can
897 * now used to write out the values correctly at identical values.
899 * Should be called only after gmx_histogram_finish() has been called.
900 * \p src should have been sampled without gmx_histogram_set_integerbins().
903 gmx_histogram_resample_dblbw(gmx_histogram_t
**destp
, gmx_histogram_t
*src
,
904 gmx_bool bIntegerBins
)
906 gmx_histogram_t
*dest
;
910 gmx_histogram_create(destp
, src
->type
, src
->nbins
/ 2);
912 sfree(dest
->chist
); dest
->chist
= NULL
;
913 sfree(dest
->cn
); dest
->cn
= NULL
;
914 gmx_histogram_set_binwidth(dest
, src
->start
, src
->binwidth
* 2);
915 gmx_histogram_set_integerbins(dest
, bIntegerBins
);
917 for (i
= j
= 0; i
< dest
->nbins
; ++i
)
919 if (bIntegerBins
&& i
== 0)
922 ve
= sqr(src
->histerr
[0]);
927 v
= src
->hist
[j
] + src
->hist
[j
+1];
928 ve
= sqr(src
->histerr
[j
]) + sqr(src
->histerr
[j
+1]);
933 dest
->histerr
[i
] = ve
;
935 dest
->hist
[dest
->nbins
] = 0;
936 dest
->histerr
[dest
->nbins
] = 0;
940 * \param[out] destp Destination histogram.
941 * \param[in] src Source histogram.
943 * Makes a clone of \p src for post-processing.
946 gmx_histogram_clone(gmx_histogram_t
**destp
, gmx_histogram_t
*src
)
948 gmx_histogram_t
*dest
;
951 memcpy(dest
, src
, sizeof(*dest
));
953 /* These are not needed in post-processing */
954 dest
->blockfp
= NULL
;
958 /* Make a deep copy of the actual histograms */
959 snew(dest
->hist
, src
->nbins
+1);
960 snew(dest
->histerr
, src
->nbins
+1);
961 memcpy(dest
->hist
, src
->hist
, (src
->nbins
+1)*sizeof(real
));
962 memcpy(dest
->histerr
, src
->histerr
, (src
->nbins
+1)*sizeof(real
));
968 * \param[in,out] h Histogram to normalize.
970 * Normalizes the histogram such that its integral equals one.
973 gmx_histogram_normalize_prob(gmx_histogram_t
*h
)
980 for (i
= 0; i
<= h
->nbins
; ++i
)
985 normfac
= h
->invbw
/ sum
;
986 gmx_histogram_scale(h
, normfac
);
990 * \param[in,out] h Histogram to normalize.
991 * \param[in] norm Scaling factor.
993 * All bin values are multiplied by \p norm.
996 gmx_histogram_scale(gmx_histogram_t
*h
, real norm
)
1000 for (i
= 0; i
<= h
->nbins
; ++i
)
1003 h
->histerr
[i
] *= norm
;
1008 * \param[in,out] h Histogram to normalize.
1009 * \param[in] norm Scaling vector.
1011 * The i'th bin is multiplied by \p norm[i].
1014 gmx_histogram_scale_vec(gmx_histogram_t
*h
, real norm
[])
1018 for (i
= 0; i
< h
->nbins
; ++i
)
1020 h
->hist
[i
] *= norm
[i
];
1021 h
->histerr
[i
] *= norm
[i
];
1023 h
->hist
[h
->nbins
] *= norm
[h
->nbins
-1];
1024 h
->histerr
[h
->nbins
] *= norm
[h
->nbins
-1];
1028 * Makes some checks on output histograms and finds the maximum number of bins.
1030 * \param[in] n Number of histograms in \p h.
1031 * \param[in] h Array of histograms.
1032 * \param[out] nbins Pointer to a value that will receive the maximum number
1036 prepare_output(int n
, gmx_histogram_t
*h
[], int *nbins
)
1041 for (j
= 0; j
< n
; ++j
)
1043 if (!gmx_within_tol(h
[j
]->start
, h
[0]->start
, GMX_REAL_EPS
))
1045 fprintf(stderr
, "gmx_ana_histogram_write: histogram start values not identical\n");
1047 if (!gmx_within_tol(h
[j
]->binwidth
, h
[0]->binwidth
, GMX_REAL_EPS
))
1049 fprintf(stderr
, "gmx_ana_histogram_write: bin widths not identical\n");
1051 if (*nbins
< h
[j
]->nbins
)
1053 *nbins
= h
[j
]->nbins
;
1059 * \param[in] fp Output file.
1060 * \param[in] h Array of histograms to write.
1061 * \param[in] bErrors If TRUE, histogram errors are written.
1063 * Convenience wrapper for gmx_histogram_write_array() for writing a single
1066 * \see gmx_histogram_write_array()
1069 gmx_histogram_write(FILE *fp
, gmx_histogram_t
*h
, gmx_bool bErrors
)
1071 gmx_histogram_write_array(fp
, 1, &h
, TRUE
, bErrors
);
1075 * \param[in] fp Output file.
1076 * \param[in] n Number of histograms in \p h.
1077 * \param[in] h Array of histograms to write.
1078 * \param[in] bValue If TRUE, histogram values are written.
1079 * \param[in] bErrors If TRUE, histogram errors are written.
1081 * All the histograms in the array \p h should have the same bin widths and
1082 * left edges, otherwise the behavior is undefined.
1083 * The output format is one bin per line. The first number on the line is the
1084 * center of the bin, followed by one or two numbers for each histogram
1085 * (depending on \p bValue and \p bErrors).
1086 * If both \p bValue and \p bErrors are both TRUE, the values are written
1087 * before the errors.
1090 gmx_histogram_write_array(FILE *fp
, int n
, gmx_histogram_t
*h
[],
1091 gmx_bool bValue
, gmx_bool bErrors
)
1095 prepare_output(n
, h
, &nbins
);
1096 for (i
= 0; i
< nbins
; ++i
)
1098 fprintf(fp
, "%10g", h
[0]->start
+ (i
+0.5)*h
[0]->binwidth
);
1099 for (j
= 0; j
< n
; ++j
)
1103 fprintf(fp
, " %10g", i
< h
[j
]->nbins
? h
[j
]->hist
[i
] : 0.0);
1107 fprintf(fp
, " %10g", i
< h
[j
]->nbins
? h
[j
]->histerr
[i
] : 0.0);
1116 * \param[in] fp Output file.
1117 * \param[in] n Number of histograms in \p h.
1118 * \param[in] h Array of histograms to write.
1119 * \param[in] bValue If TRUE, histogram values are written.
1120 * \param[in] bErrors If TRUE, histogram errors are written.
1122 * Works as gmx_histogram_write_array(), but writes the cumulative
1124 * The first column in output will be the right edges of the bins.
1127 * Error output is not currently supported (zeros will be written if asked).
1129 * \see gmx_histogram_write_array()
1132 gmx_histogram_write_cum_array(FILE *fp
, int n
, gmx_histogram_t
*h
[],
1133 gmx_bool bValue
, gmx_bool bErrors
)
1138 prepare_output(n
, h
, &nbins
);
1141 fprintf(fp
, "%10g", h
[0]->start
);
1142 for (j
= 0; j
< n
; ++j
)
1146 fprintf(fp
, " %10g", 0.0);
1150 fprintf(fp
, " %10g", 0.0);
1154 for (i
= 0; i
< nbins
; ++i
)
1156 fprintf(fp
, "%10g", h
[0]->start
+ (i
+1)*h
[0]->binwidth
);
1157 for (j
= 0; j
< n
; ++j
)
1159 sum
[j
] += i
< h
[j
]->nbins
? h
[j
]->hist
[i
] : 0.0;
1162 fprintf(fp
, " %10g", sum
[j
]);
1164 /* TODO: Error output not implemented */
1167 fprintf(fp
, " %10g", 0.0);