1 //=================================================================================================
2 /*!
3 // \file blaze/math/expressions/DMatStdDevExpr.h
4 // \brief Header file for the dense matrix standard deviation expression
5 //
6 // Copyright (C) 2012-2020 Klaus Iglberger - All Rights Reserved
7 //
8 // This file is part of the Blaze library. You can redistribute it and/or modify it under
9 // the terms of the New (Revised) BSD License. Redistribution and use in source and binary
10 // forms, with or without modification, are permitted provided that the following conditions
11 // are met:
12 //
13 // 1. Redistributions of source code must retain the above copyright notice, this list of
14 // conditions and the following disclaimer.
15 // 2. Redistributions in binary form must reproduce the above copyright notice, this list
16 // of conditions and the following disclaimer in the documentation and/or other materials
17 // provided with the distribution.
18 // 3. Neither the names of the Blaze development group nor the names of its contributors
19 // may be used to endorse or promote products derived from this software without specific
20 // prior written permission.
21 //
22 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
23 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
24 // OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
25 // SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
27 // TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
28 // BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
30 // ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
31 // DAMAGE.
32 */
33 //=================================================================================================
34
35 #ifndef _BLAZE_MATH_EXPRESSIONS_DMATSTDDEVEXPR_H_
36 #define _BLAZE_MATH_EXPRESSIONS_DMATSTDDEVEXPR_H_
37
38
39 //*************************************************************************************************
40 // Includes
41 //*************************************************************************************************
42
43 #include <blaze/math/expressions/DenseMatrix.h>
44 #include <blaze/math/expressions/DMatMapExpr.h>
45 #include <blaze/math/expressions/DMatVarExpr.h>
46 #include <blaze/util/FunctionTrace.h>
47
48
49 namespace blaze {
50
51 //=================================================================================================
52 //
53 // GLOBAL FUNCTIONS
54 //
55 //=================================================================================================
56
57 //*************************************************************************************************
58 /*!\brief Computes the standard deviation for the given dense matrix.
59 // \ingroup dense_matrix
60 //
61 // \param dm The given dense matrix for the standard deviation computation.
62 // \return The standard deviation of the given matrix.
63 // \exception std::invalid_argument Invalid input matrix.
64 //
65 // This function computes the
66 // <a href="https://en.wikipedia.org/wiki/Standard_deviation">standard deviation</a> for the given
67 // dense matrix \a dm. Example:
68
69 \code
70 using blaze::DynamicMatrix;
71
72 DynamicMatrix<int> A{ { 1, 3, 2 }
73 , { 2, 6, 4 }
74 , { 9, 6, 3 } };
75
76 const double s = stddev( A ); // Results in sqrt(6.5)
77 \endcode
78
79 // In case the size of the given matrix is smaller than 2, a \a std::invalid_argument is thrown.
80 */
81 template< typename MT // Type of the dense matrix
82 , bool SO > // Storage order
decltype(auto)83 inline decltype(auto) stddev( const DenseMatrix<MT,SO>& dm )
84 {
85 BLAZE_FUNCTION_TRACE;
86
87 return sqrt( var( *dm ) );
88 }
89 //*************************************************************************************************
90
91
92 //*************************************************************************************************
93 /*!\brief Computes the row-/columnwise standard deviation function for the given dense matrix.
94 // \ingroup dense_matrix
95 //
96 // \param dm The given dense matrix for the standard deviation computation.
97 // \return The row-/columnwise standard deviation of the given matrix.
98 // \exception std::invalid_argument Invalid input matrix.
99 //
100 // This function computes the row-/columnwise
101 // <a href="https://en.wikipedia.org/wiki/Standard_deviation">standard deviation</a> for the
102 // given dense matrix \a dm. In case \a RF is set to \a rowwise, the function returns a column
103 // vector containing the standard deviation of each row of \a dm. In case \a RF is set to
104 // \a columnwise, the function returns a row vector containing the standard deviation of each
105 // column of \a dm. Example:
106
107 \code
108 using blaze::DynamicMatrix;
109 using blaze::DynamicVector;
110 using blaze::columnVector;
111 using blaze::rowVector;
112
113 DynamicMatrix<int> A{ { 1, 3, 2 }
114 , { 2, 6, 4 }
115 , { 9, 6, 3 } };
116
117 DynamicVector<double,columnVector> rs;
118 DynamicVector<double,rowVector> cs;
119
120 rs = stddev<rowwise>( A ); // Results in ( 1 2 3 )
121 cs = stddev<columnwise>( A ); // Results in ( sqrt(19) sqrt(3) 1 )
122 \endcode
123
124 // In case \a RF is set to \a rowwise and the number of columns of the given matrix is smaller
125 // than 2 or in case \a RF is set to \a columnwise and the number of rows of the given matrix is
126 // smaller than 2, a \a std::invalid_argument is thrown.
127 */
128 template< ReductionFlag RF // Reduction flag
129 , typename MT // Type of the dense matrix
130 , bool SO > // Storage order
decltype(auto)131 inline decltype(auto) stddev( const DenseMatrix<MT,SO>& dm )
132 {
133 BLAZE_FUNCTION_TRACE;
134
135 return sqrt( var<RF>( *dm ) );
136 }
137 //*************************************************************************************************
138
139 } // namespace blaze
140
141 #endif
142