libMesh
Public Member Functions | List of all members
libMesh::StatisticsVector< T > Class Template Reference

The StatisticsVector class is derived from the std::vector<> and therefore has all of its useful features. More...

#include <statistics.h>

Inheritance diagram for libMesh::StatisticsVector< T >:
[legend]

Public Member Functions

 StatisticsVector (dof_id_type i=0)
 Call the std::vector constructor. More...
 
 StatisticsVector (dof_id_type i, T val)
 Call the std::vector constructor, fill each entry with val. More...
 
virtual ~StatisticsVector ()=default
 Destructor. More...
 
virtual Real l2_norm () const
 
virtual T minimum () const
 
virtual T maximum () const
 
virtual Real mean () const
 
virtual Real median ()
 
virtual Real median () const
 A const version of the median function. More...
 
virtual Real variance () const
 
virtual Real variance (const Real known_mean) const
 
virtual Real stddev () const
 
virtual Real stddev (const Real known_mean) const
 
void normalize ()
 Divides all entries by the largest entry and stores the result. More...
 
virtual void histogram (std::vector< dof_id_type > &bin_members, unsigned int n_bins=10)
 
void plot_histogram (const processor_id_type my_procid, const std::string &filename, unsigned int n_bins)
 Generates a Matlab/Octave style file which can be used to make a plot of the histogram having the desired number of bins. More...
 
virtual void histogram (std::vector< dof_id_type > &bin_members, unsigned int n_bins=10) const
 A const version of the histogram function. More...
 
virtual std::vector< dof_id_typecut_below (Real cut) const
 
virtual std::vector< dof_id_typecut_above (Real cut) const
 

Detailed Description

template<typename T>
class libMesh::StatisticsVector< T >

The StatisticsVector class is derived from the std::vector<> and therefore has all of its useful features.

It was designed to not have any internal state, i.e. no public or private data members. Also, it was only designed for classes and types for which the operators +,*,/ have meaning, specifically floats, doubles, ints, etc. The main reason for this design decision was to allow a std::vector<> to be successfully cast to a StatisticsVector, thereby enabling its additional functionality. We do not anticipate any problems with deriving from an stl container which lacks a virtual destructor in this case.

Where manipulation of the data set was necessary (for example sorting) two versions of member functions have been implemented. The non-const versions perform sorting directly in the data set, invalidating pointers and changing the entries. const versions of the same functions are generally available, and will be automatically invoked on const StatisticsVector objects. A draw-back to the const versions is that they simply make a copy of the original object and therefore double the original memory requirement for the data set.

Most of the actual code was copied or adapted from the GNU Scientific Library (GSL). More precisely, the recursion relations for computing the mean were implemented in order to avoid possible problems with buffer overruns.

Author
John W. Peterson
Date
2002 A std::vector derived class for implementing simple statistical algorithms.

Definition at line 67 of file statistics.h.

Constructor & Destructor Documentation

◆ StatisticsVector() [1/2]

template<typename T>
libMesh::StatisticsVector< T >::StatisticsVector ( dof_id_type  i = 0)
inlineexplicit

Call the std::vector constructor.

Definition at line 75 of file statistics.h.

75 : std::vector<T> (i) {}

◆ StatisticsVector() [2/2]

template<typename T>
libMesh::StatisticsVector< T >::StatisticsVector ( dof_id_type  i,
val 
)
inline

Call the std::vector constructor, fill each entry with val.

Definition at line 80 of file statistics.h.

80 : std::vector<T> (i,val) {}

◆ ~StatisticsVector()

template<typename T>
virtual libMesh::StatisticsVector< T >::~StatisticsVector ( )
virtualdefault

Destructor.

Virtual so we can derive from the StatisticsVector

Member Function Documentation

◆ cut_above()

template<typename T >
std::vector< dof_id_type > libMesh::StatisticsVector< T >::cut_above ( Real  cut) const
virtual
Returns
A vector of dof_id_types which corresponds to the indices of every member of the data set above the cutoff value cut.

I chose not to combine these two functions since the interface is cleaner with one passed parameter instead of two.

Reimplemented in libMesh::ErrorVector.

Definition at line 364 of file statistics.C.

365 {
366  LOG_SCOPE ("cut_above()", "StatisticsVector");
367 
368  const dof_id_type n = cast_int<dof_id_type>(this->size());
369 
370  std::vector<dof_id_type> cut_indices;
371  cut_indices.reserve(n/2); // Arbitrary
372 
373  for (dof_id_type i=0; i<n; i++)
374  if ((*this)[i] > cut)
375  cut_indices.push_back(i);
376 
377  return cut_indices;
378 }
uint8_t dof_id_type
Definition: id_types.h:67

◆ cut_below()

template<typename T >
std::vector< dof_id_type > libMesh::StatisticsVector< T >::cut_below ( Real  cut) const
virtual
Returns
A vector of dof_id_types which corresponds to the indices of every member of the data set below the cutoff value "cut".

Reimplemented in libMesh::ErrorVector.

Definition at line 340 of file statistics.C.

Referenced by main().

341 {
342  LOG_SCOPE ("cut_below()", "StatisticsVector");
343 
344  const dof_id_type n = cast_int<dof_id_type>(this->size());
345 
346  std::vector<dof_id_type> cut_indices;
347  cut_indices.reserve(n/2); // Arbitrary
348 
349  for (dof_id_type i=0; i<n; i++)
350  {
351  if ((*this)[i] < cut)
352  {
353  cut_indices.push_back(i);
354  }
355  }
356 
357  return cut_indices;
358 }
uint8_t dof_id_type
Definition: id_types.h:67

◆ histogram() [1/2]

template<typename T >
void libMesh::StatisticsVector< T >::histogram ( std::vector< dof_id_type > &  bin_members,
unsigned int  n_bins = 10 
)
virtual
Returns
A histogram with n_bins bins for the data set.

For simplicity, the bins are assumed to be of uniform size. Upon return, the bin_members vector will contain unsigned integers which give the number of members in each bin. WARNING: This non-const function sorts the vector, changing its order. Source: GNU Scientific Library.

Definition at line 179 of file statistics.C.

Referenced by libMesh::StatisticsVector< ErrorVectorReal >::histogram(), and main().

181 {
182  // Must have at least 1 bin
183  libmesh_assert (n_bins>0);
184 
185  const dof_id_type n = cast_int<dof_id_type>(this->size());
186 
187  std::sort(this->begin(), this->end());
188 
189  // The StatisticsVector can hold both integer and float types.
190  // We will define all the bins, etc. using Reals.
191  Real min = static_cast<Real>(this->minimum());
192  Real max = static_cast<Real>(this->maximum());
193  Real bin_size = (max - min) / static_cast<Real>(n_bins);
194 
195  LOG_SCOPE ("histogram()", "StatisticsVector");
196 
197  std::vector<Real> bin_bounds(n_bins+1);
198  for (auto i : index_range(bin_bounds))
199  bin_bounds[i] = min + Real(i) * bin_size;
200 
201  // Give the last bin boundary a little wiggle room: we don't want
202  // it to be just barely less than the max, otherwise our bin test below
203  // may fail.
204  bin_bounds.back() += 1.e-6 * bin_size;
205 
206  // This vector will store the number of members each bin has.
207  bin_members.resize(n_bins);
208 
209 #ifdef DEBUG
210  // we may not bin all values.
211  // Those we skip on purpose (e.g. inactive elements in an ErrorVector)
212  // should also not appear in the consistency-check below.
213  unsigned int unbinned=0;
214 #endif
215 
216  dof_id_type data_index = 0;
217  for (auto j : index_range(bin_members)) // bin vector indexing
218  {
219  // libMesh::out << "(debug) Filling bin " << j << std::endl;
220 
221  for (dof_id_type i=data_index; i<n; i++) // data vector indexing
222  {
223  //libMesh::out << "(debug) Processing index=" << i << std::endl;
224  Real current_val = static_cast<Real>( (*this)[i] );
225 
226  // There may be entries in the vector smaller than the value
227  // reported by this->minimum(). (e.g. inactive elements in an
228  // ErrorVector.) We just skip entries like that.
229  if (current_val < min)
230  {
231 #ifdef DEBUG
232  unbinned++;
233 #endif
234  // libMesh::out << "(debug) Skipping entry v[" << i << "]="
235  // << (*this)[i]
236  // << " which is less than the min value: min="
237  // << min << std::endl;
238  continue;
239  }
240 
241  if (current_val > bin_bounds[j+1]) // if outside the current bin (bin[j] is bounded
242  // by bin_bounds[j] and bin_bounds[j+1])
243  {
244  // libMesh::out.precision(16);
245  // libMesh::out.setf(std::ios_base::fixed);
246  // libMesh::out << "(debug) (*this)[i]= " << (*this)[i]
247  // << " is greater than bin_bounds[j+1]="
248  // << bin_bounds[j+1] << std::endl;
249  data_index = i; // start searching here for next bin
250  break; // go to next bin
251  }
252 
253  // Otherwise, increment current bin's count
254  bin_members[j]++;
255  // libMesh::out << "(debug) Binned index=" << i << std::endl;
256 #ifdef DEBUG
257  if (i== n-1) // we read the last 'i' only in the last bin.
258  libmesh_assert_equal_to(j, bin_members.size()-1);
259 #endif
260  }
261  }
262 
263 #ifdef DEBUG
264  // Check the number of binned entries
265  const dof_id_type n_binned = std::accumulate(bin_members.begin(),
266  bin_members.end(),
267  static_cast<dof_id_type>(0),
268  std::plus<dof_id_type>());
269 
270  if (n-unbinned != n_binned)
271  {
272  libMesh::out << "Warning: The number of binned entries, n_binned="
273  << n_binned
274  << ", did not match the total number of binnable entries, n="
275  << n-unbinned << "." << std::endl;
276  }
277 #endif
278 }
virtual T maximum() const
Definition: statistics.C:62
libmesh_assert(ctx)
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
OStreamProxy out
virtual T minimum() const
Definition: statistics.C:49
auto index_range(const T &sizable)
Helper function that returns an IntRange<std::size_t> representing all the indices of the passed-in v...
Definition: int_range.h:117
uint8_t dof_id_type
Definition: id_types.h:67

◆ histogram() [2/2]

template<typename T >
void libMesh::StatisticsVector< T >::histogram ( std::vector< dof_id_type > &  bin_members,
unsigned int  n_bins = 10 
) const
virtual

A const version of the histogram function.

Definition at line 328 of file statistics.C.

330 {
331  StatisticsVector<T> sv = (*this);
332 
333  return sv.histogram(bin_members, n_bins);
334 }

◆ l2_norm()

template<typename T >
Real libMesh::StatisticsVector< T >::l2_norm ( ) const
virtual
Returns
The l2 norm of the data set.

Definition at line 37 of file statistics.C.

Referenced by assemble_and_solve(), and main().

38 {
39  Real normsq = 0.;
40  const dof_id_type n = cast_int<dof_id_type>(this->size());
41  for (dof_id_type i = 0; i != n; ++i)
42  normsq += ((*this)[i] * (*this)[i]);
43 
44  return std::sqrt(normsq);
45 }
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
uint8_t dof_id_type
Definition: id_types.h:67

◆ maximum()

template<typename T >
T libMesh::StatisticsVector< T >::maximum ( ) const
virtual
Returns
The maximum value in the data set.

Definition at line 62 of file statistics.C.

Referenced by assemble_and_solve(), and main().

63 {
64  LOG_SCOPE ("maximum()", "StatisticsVector");
65 
66  const T max = *(std::max_element(this->begin(), this->end()));
67 
68  return max;
69 }

◆ mean()

template<typename T >
Real libMesh::StatisticsVector< T >::mean ( ) const
virtual
Returns
The mean value of the data set using a recurrence relation.

Source: GNU Scientific Library

Reimplemented in libMesh::ErrorVector.

Definition at line 75 of file statistics.C.

Referenced by main(), and libMesh::StatisticsVector< ErrorVectorReal >::variance().

76 {
77  LOG_SCOPE ("mean()", "StatisticsVector");
78 
79  const dof_id_type n = cast_int<dof_id_type>(this->size());
80 
81  Real the_mean = 0;
82 
83  for (dof_id_type i=0; i<n; i++)
84  {
85  the_mean += ( static_cast<Real>((*this)[i]) - the_mean ) /
86  static_cast<Real>(i + 1);
87  }
88 
89  return the_mean;
90 }
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
uint8_t dof_id_type
Definition: id_types.h:67

◆ median() [1/2]

template<typename T >
Real libMesh::StatisticsVector< T >::median ( )
virtual
Returns
The median (e.g. the middle) value of the data set.

This function modifies the original data by sorting, so it can't be called on const objects. Source: GNU Scientific Library.

Reimplemented in libMesh::ErrorVector.

Definition at line 96 of file statistics.C.

Referenced by libMesh::ErrorVector::median(), and libMesh::StatisticsVector< ErrorVectorReal >::median().

97 {
98  const dof_id_type n = cast_int<dof_id_type>(this->size());
99 
100  if (n == 0)
101  return 0.;
102 
103  LOG_SCOPE ("median()", "StatisticsVector");
104 
105  std::sort(this->begin(), this->end());
106 
107  const dof_id_type lhs = (n-1) / 2;
108  const dof_id_type rhs = n / 2;
109 
110  Real the_median = 0;
111 
112 
113  if (lhs == rhs)
114  {
115  the_median = static_cast<Real>((*this)[lhs]);
116  }
117 
118  else
119  {
120  the_median = ( static_cast<Real>((*this)[lhs]) +
121  static_cast<Real>((*this)[rhs]) ) / 2.0;
122  }
123 
124  return the_median;
125 }
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
uint8_t dof_id_type
Definition: id_types.h:67

◆ median() [2/2]

template<typename T >
Real libMesh::StatisticsVector< T >::median ( ) const
virtual

A const version of the median function.

Requires twice the memory of original data set but does not change the original.

Reimplemented in libMesh::ErrorVector.

Definition at line 131 of file statistics.C.

132 {
133  StatisticsVector<T> sv = (*this);
134 
135  return sv.median();
136 }

◆ minimum()

template<typename T >
T libMesh::StatisticsVector< T >::minimum ( ) const
virtual
Returns
The minimum value in the data set.

Reimplemented in libMesh::ErrorVector.

Definition at line 49 of file statistics.C.

50 {
51  LOG_SCOPE ("minimum()", "StatisticsVector");
52 
53  const T min = *(std::min_element(this->begin(), this->end()));
54 
55  return min;
56 }

◆ normalize()

template<typename T >
void libMesh::StatisticsVector< T >::normalize ( )

Divides all entries by the largest entry and stores the result.

Definition at line 165 of file statistics.C.

166 {
167  const dof_id_type n = cast_int<dof_id_type>(this->size());
168  const Real max = this->maximum();
169 
170  for (dof_id_type i=0; i<n; i++)
171  (*this)[i] = static_cast<T>((*this)[i] / max);
172 }
virtual T maximum() const
Definition: statistics.C:62
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
uint8_t dof_id_type
Definition: id_types.h:67

◆ plot_histogram()

template<typename T >
void libMesh::StatisticsVector< T >::plot_histogram ( const processor_id_type  my_procid,
const std::string &  filename,
unsigned int  n_bins 
)

Generates a Matlab/Octave style file which can be used to make a plot of the histogram having the desired number of bins.

Uses the histogram(...) function in this class WARNING: The histogram(...) function is non-const, and changes the order of the vector.

Definition at line 285 of file statistics.C.

288 {
289  // First generate the histogram with the desired number of bins
290  std::vector<dof_id_type> bin_members;
291  this->histogram(bin_members, n_bins);
292 
293  // The max, min and bin size are used to generate x-axis values.
294  T min = this->minimum();
295  T max = this->maximum();
296  T bin_size = (max - min) / static_cast<T>(n_bins);
297 
298  // On processor 0: Write histogram to file
299  if (my_procid==0)
300  {
301  std::ofstream out_stream (filename.c_str());
302 
303  out_stream << "clear all\n";
304  out_stream << "clf\n";
305  //out_stream << "x=linspace(" << min << "," << max << "," << n_bins+1 << ");\n";
306 
307  // abscissa values are located at the center of each bin.
308  out_stream << "x=[";
309  for (auto i : index_range(bin_members))
310  {
311  out_stream << min + (Real(i)+0.5)*bin_size << " ";
312  }
313  out_stream << "];\n";
314 
315  out_stream << "y=[";
316  for (auto bmi : bin_members)
317  {
318  out_stream << bmi << " ";
319  }
320  out_stream << "];\n";
321  out_stream << "bar(x,y);\n";
322  }
323 }
virtual T maximum() const
Definition: statistics.C:62
virtual void histogram(std::vector< dof_id_type > &bin_members, unsigned int n_bins=10)
Definition: statistics.C:179
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
virtual T minimum() const
Definition: statistics.C:49
auto index_range(const T &sizable)
Helper function that returns an IntRange<std::size_t> representing all the indices of the passed-in v...
Definition: int_range.h:117

◆ stddev() [1/2]

template<typename T>
virtual Real libMesh::StatisticsVector< T >::stddev ( ) const
inlinevirtual
Returns
The standard deviation of the data set, which is simply the square-root of the variance.

Definition at line 154 of file statistics.h.

155  { return std::sqrt(this->variance()); }
virtual Real variance() const
Definition: statistics.h:134

◆ stddev() [2/2]

template<typename T>
virtual Real libMesh::StatisticsVector< T >::stddev ( const Real  known_mean) const
inlinevirtual
Returns
Computes the standard deviation of the data set, which is simply the square-root of the variance.

This method can be used for efficiency when the mean has already been computed.

Definition at line 164 of file statistics.h.

165  { return std::sqrt(this->variance(known_mean)); }
virtual Real variance() const
Definition: statistics.h:134

◆ variance() [1/2]

template<typename T>
virtual Real libMesh::StatisticsVector< T >::variance ( ) const
inlinevirtual
Returns
The variance of the data set.

Uses a recurrence relation to prevent data overflow for large sums.

Note
The variance is equal to the standard deviation squared. Source: GNU Scientific Library.

Reimplemented in libMesh::ErrorVector.

Definition at line 134 of file statistics.h.

Referenced by libMesh::StatisticsVector< ErrorVectorReal >::stddev(), and libMesh::StatisticsVector< ErrorVectorReal >::variance().

135  { return this->variance(this->mean()); }
virtual Real mean() const
Definition: statistics.C:75
virtual Real variance() const
Definition: statistics.h:134

◆ variance() [2/2]

template<typename T >
Real libMesh::StatisticsVector< T >::variance ( const Real  known_mean) const
virtual
Returns
The variance of the data set where the mean is provided.

This is useful for efficiency when you have already calculated the mean. Uses a recurrence relation to prevent data overflow for large sums.

Note
The variance is equal to the standard deviation squared. Source: GNU Scientific Library.

Reimplemented in libMesh::ErrorVector.

Definition at line 142 of file statistics.C.

143 {
144  const dof_id_type n = cast_int<dof_id_type>(this->size());
145 
146  LOG_SCOPE ("variance()", "StatisticsVector");
147 
148  Real the_variance = 0;
149 
150  for (dof_id_type i=0; i<n; i++)
151  {
152  const Real delta = ( static_cast<Real>((*this)[i]) - mean_in );
153  the_variance += (delta * delta - the_variance) /
154  static_cast<Real>(i + 1);
155  }
156 
157  if (n > 1)
158  the_variance *= static_cast<Real>(n) / static_cast<Real>(n - 1);
159 
160  return the_variance;
161 }
DIE A HORRIBLE DEATH HERE typedef LIBMESH_DEFAULT_SCALAR_TYPE Real
uint8_t dof_id_type
Definition: id_types.h:67

The documentation for this class was generated from the following files: