1 //=================================================================================================
2 /*!
3 // \file blaze/math/expressions/SMatStdDevExpr.h
4 // \brief Header file for the sparse 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_SMATSTDDEVEXPR_H_
36 #define _BLAZE_MATH_EXPRESSIONS_SMATSTDDEVEXPR_H_
37
38
39 //*************************************************************************************************
40 // Includes
41 //*************************************************************************************************
42
43 #include <blaze/math/expressions/SparseMatrix.h>
44 #include <blaze/math/expressions/SMatMapExpr.h>
45 #include <blaze/math/expressions/SMatVarExpr.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 sparse matrix.
59 // \ingroup sparse_matrix
60 //
61 // \param sm The given sparse 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 // sparse matrix \a sm. Both the non-zero and zero elements of the sparse matrix are taken into
68 // account. Example:
69
70 \code
71 using blaze::CompressedMatrix;
72
73 CompressedMatrix<int> A{ { 1, 3, 2 }
74 , { 2, 6, 4 }
75 , { 9, 6, 3 } };
76
77 const double s = stddev( A ); // Results in sqrt(6.5)
78 \endcode
79
80 // In case the size of the given matrix is smaller than 2, a \a std::invalid_argument is thrown.
81 */
82 template< typename MT // Type of the sparse matrix
83 , bool SO > // Storage order
decltype(auto)84 inline decltype(auto) stddev( const SparseMatrix<MT,SO>& sm )
85 {
86 BLAZE_FUNCTION_TRACE;
87
88 return sqrt( var( *sm ) );
89 }
90 //*************************************************************************************************
91
92
93 //*************************************************************************************************
94 /*!\brief Computes the row-/columnwise standard deviation function for the given sparse matrix.
95 // \ingroup sparse_matrix
96 //
97 // \param sm The given sparse matrix for the standard deviation computation.
98 // \return The row-/columnwise standard deviation of the given matrix.
99 // \exception std::invalid_argument Invalid input matrix.
100 //
101 // This function computes the row-/columnwise
102 // <a href="https://en.wikipedia.org/wiki/Standard_deviation">standard deviation</a> for the
103 // given sparse matrix \a sm. In case \a RF is set to \a rowwise, the function returns a column
104 // vector containing the standard deviation of each row of \a sm. In case \a RF is set to
105 // \a columnwise, the function returns a row vector containing the standard deviation of each
106 // column of \a sm. Both the non-zero and zero elements of the sparse matrix are taken into
107 // account. Example:
108
109 \code
110 using blaze::CompressedMatrix;
111 using blaze::DynamicVector;
112 using blaze::columnVector;
113 using blaze::rowVector;
114
115 CompressedMatrix<int> A{ { 1, 3, 2 }
116 , { 2, 6, 4 }
117 , { 9, 6, 3 } };
118
119 DynamicVector<double,columnVector> rs;
120 DynamicVector<double,rowVector> cs;
121
122 rs = stddev<rowwise>( A ); // Results in ( 1 2 3 )
123 cs = stddev<columnwise>( A ); // Results in ( sqrt(19) sqrt(3) 1 )
124 \endcode
125
126 // In case \a RF is set to \a rowwise and the number of columns of the given matrix is smaller
127 // than 2 or in case \a RF is set to \a columnwise and the number of rows of the given matrix is
128 // smaller than 2, a \a std::invalid_argument is thrown.
129 */
130 template< ReductionFlag RF // Reduction flag
131 , typename MT // Type of the sparse matrix
132 , bool SO > // Storage order
decltype(auto)133 inline decltype(auto) stddev( const SparseMatrix<MT,SO>& sm )
134 {
135 BLAZE_FUNCTION_TRACE;
136
137 return sqrt( var<RF>( *sm ) );
138 }
139 //*************************************************************************************************
140
141 } // namespace blaze
142
143 #endif
144