StatisticsReporter

Compute statistical values of a given VectorPostprocessor objects and vectors.

Description

The StatisticsReporter object computes statistical values for each vector of VectorPostprocessor (VPP) objects or support values from Reporters. The results are output in values with names based on the input data and the desired statistic calculation. Optionally confidence level intervals can be computed.

Statistics

The statistics to compute are indicated by the "compute" parameter, which can contain multiple values as listed below. Note that multiple statistical measures can be computed simultaneously by passing in more than one to the input parameter. The current statistical measures the StatisticsReporter can compute are:

minimum
compute = min
Computes the minimum value for the supplied vectors.
maximum
compute = max
Computes the maximum value for the supplied vectors.
sum
compute = sum
Computes the sum ( $var element = document.getElementById("moose-equation-82da96d2-6abf-4320-acd9-e8cb8d813886");katex.render("\\Sigma", element, {displayMode:false,throwOnError:false});$ ) of the supplied vectors $var element = document.getElementById("moose-equation-e9bb06ff-0149-4da3-8005-067ce9eb94b1");katex.render("\\vec{v}", element, {displayMode:false,throwOnError:false});$ , where $var element = document.getElementById("moose-equation-f9a723e3-3873-478c-bb73-8860f56050e0");katex.render("N", element, {displayMode:false,throwOnError:false});$ is the length of the vector:
$var element = document.getElementById("moose-equation-4e79bdc6-857d-487f-8e95-c6b34e864c8e");katex.render("\\Sigma = \\sum_{i=1}^N{v_i}", element, {displayMode:true,throwOnError:false});$
mean
compute = average
Computes the average ( $var element = document.getElementById("moose-equation-f5bc9aa3-aac8-4aa7-a129-5f47e85212f3");katex.render("\\bar{v}", element, {displayMode:false,throwOnError:false});$ ) of the supplied vectors $var element = document.getElementById("moose-equation-c793cbfc-49d8-4457-9b69-0a35a65ece52");katex.render("\\vec{v}", element, {displayMode:false,throwOnError:false});$ :
$var element = document.getElementById("moose-equation-d3517fdf-6520-45ac-ba51-6a5e6f5858e1");katex.render("\\bar{v} = \\frac{\\sum_{i=1}^{N}{v_i}}{N}", element, {displayMode:true,throwOnError:false});$
standard deviation
compute = stddev
Computes the standard deviation ( $var element = document.getElementById("moose-equation-d2bc078b-c63e-4751-a97d-236442a015a2");katex.render("\\sigma", element, {displayMode:false,throwOnError:false});$ ) of the supplied vectors $var element = document.getElementById("moose-equation-e80ff8f7-6b2e-4bc3-9002-c240ba6524cd");katex.render("\\vec{v}", element, {displayMode:false,throwOnError:false});$ :
$var element = document.getElementById("moose-equation-8de69ba9-a898-4425-b304-0118430fc034");katex.render("\\sigma = \\sqrt{\\frac{\\sum_{i=1}^{N}{(v_i - \\bar{v})^2}}{N-1}}", element, {displayMode:true,throwOnError:false});$
L2-Norm
compute = norm2
Computes the L2-norm, $var element = document.getElementById("moose-equation-898d7df7-e755-4ee9-9065-6c2b0efb2cbe");katex.render("|v|_2", element, {displayMode:false,throwOnError:false});$ of the supplied vectors $var element = document.getElementById("moose-equation-93836be2-15ba-4262-907a-479ab6b4039c");katex.render("\\vec{v}", element, {displayMode:false,throwOnError:false});$ , this is also known as the Euclidean Norm or the "distance":
$var element = document.getElementById("moose-equation-298ee053-a6d2-4294-af95-c1a97ffc0439");katex.render("|v|_2 = \\sqrt{\\sum_{i=1}^{N}{{v_i}^2}}", element, {displayMode:true,throwOnError:false});$
standard error
compute = stderr
Computes the standard error ( $var element = document.getElementById("moose-equation-12fa77ff-93e4-4e7d-a45a-d807dc37b6ff");katex.render("\\sigma_{\\bar{v}}", element, {displayMode:false,throwOnError:false});$ ) of the supplied vectors $var element = document.getElementById("moose-equation-3fec03a2-4305-47d7-acd6-a28f335906cf");katex.render("\\vec{v}", element, {displayMode:false,throwOnError:false});$ :
$var element = document.getElementById("moose-equation-4ad1a418-b833-4201-8ac1-0758be56d919");katex.render("\\sigma_{\\bar{v}} = \\frac{\\sigma}{\\sqrt{N}}", element, {displayMode:true,throwOnError:false});$
ratio
compute = ratio
Computes the ratio of the maximum to the minimu of the supplied data.
median
compute = median
Computes the median of the supplied vectors $var element = document.getElementById("moose-equation-2605717c-00e2-47eb-92c4-a8d2f053325d");katex.render("\\vec{v} = [v_1,...,v_N]", element, {displayMode:false,throwOnError:false});$ :
$var element = document.getElementById("moose-equation-4d9ca557-390a-4535-88d3-a15c210985aa");katex.render("\\mathrm{median}(\\vec{v}) = \\left\\{ \\begin{array}{ll} w_{(N+1)/2}, & \\text{if } N \\text{ is odd} \\\\ \\frac{w_{N/2} + w_{N/2+1}}{2}, & \\text{if } N \\text{ is even} \\\\ \\end{array} \\right .", element, {displayMode:true,throwOnError:false});$
where
$var element = document.getElementById("moose-equation-fc2aa03e-9215-4d9e-9a64-9cc5ca315bda");katex.render("\\vec{w} = \\mathrm{sort}(\\vec{v})", element, {displayMode:true,throwOnError:false});$

Confidence Levels

Bootstrap confidence level intervals, as defined by Tibshirani and Efron (1993), are enabled by specifying the desired levels using the "ci_levels" parameter and setting the method of calculation using the "ci_method". The levels listed should be in the range (0, 1). For example, the levels 0.05, 0.95 result in the computation of the 0.05, 0.95 confidence level intervals.

Enabling the confidence level intervals will compute the intervals for each level and each statistic and the result will appear in the same output vector as the associated statistic calculation.

The available methods include the following:

percentile: Percentile bootstrap method as defined in Ch. 13 of Tibshirani and Efron (1993).

Example 1: Statistics

The following input file snippet demonstrates how to compute various statistics using the StatisticsReporter object.

[Reporters<<<{"href": "../../syntax/Reporters/index.html"}>>>]
  [stats]
    type = StatisticsReporter<<<{"description": "Compute statistical values of a given VectorPostprocessor objects and vectors.", "href": "StatisticsReporter.html"}>>>
    vectorpostprocessors<<<{"description": "List of VectorPostprocessor(s) to utilized for statistic computations."}>>> = 'const'
    compute<<<{"description": "The statistic(s) to compute for each of the supplied vector postprocessors."}>>> = 'min max sum mean stddev norm2'
  []
[]

This block results in the following JSON file output.

{
    "reporters": {
        "stats": {
            "type": "StatisticsReporter",
            "values": {
                "const_value_MAX": {
                    "stat": "MAX",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_MIN": {
                    "stat": "MIN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_NORM2": {
                    "stat": "NORM2",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_STDDEV": {
                    "stat": "STDDEV",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_SUM": {
                    "stat": "SUM",
                    "type": "std::pair<double, std::vector<double> >"
                }
            }
        }
    },
    "time_steps": [
        {
            "stats": {
                "const_value_MAX": [
                    5.0,
                    []
                ],
                "const_value_MEAN": [
                    3.0,
                    []
                ],
                "const_value_MIN": [
                    1.0,
                    []
                ],
                "const_value_NORM2": [
                    7.416198487095663,
                    []
                ],
                "const_value_STDDEV": [
                    1.5811388300841898,
                    []
                ],
                "const_value_SUM": [
                    15.0,
                    []
                ]
            },
            "time": 2.0,
            "time_step": 2
        }
    ]
}

Example 2: Confidence Levels

The following input file snippet demonstrates how to compute various statistics and confidence levels using the StatisticsReporter object.

[Reporters<<<{"href": "../../syntax/Reporters/index.html"}>>>]
  # Reproduce Table 13.1 in Efron and Tibshirani, 1993
  [stats]
    type = StatisticsReporter<<<{"description": "Compute statistical values of a given VectorPostprocessor objects and vectors.", "href": "StatisticsReporter.html"}>>>
    vectorpostprocessors<<<{"description": "List of VectorPostprocessor(s) to utilized for statistic computations."}>>> = 'treatment control'
    compute<<<{"description": "The statistic(s) to compute for each of the supplied vector postprocessors."}>>> = 'mean stderr'
    ci_method<<<{"description": "The method to use for computing confidence level intervals."}>>> = 'percentile'
    ci_levels<<<{"description": "A vector of confidence levels to consider, values must be in (0, 1)."}>>> = '0.025 0.05 0.1 0.16 0.5 0.84 0.9 0.95 0.975'
    ci_replicates<<<{"description": "The number of replicates to use when computing confidence level intervals."}>>> = 1000
    ci_seed<<<{"description": "The random number generator seed used for creating replicates while computing confidence level intervals."}>>> = 1980
  []
[]

This block results in the following JSON file.

{
    "reporters": {
        "stats": {
            "confidence_intervals": {
                "levels": [
                    0.025,
                    0.05,
                    0.1,
                    0.16,
                    0.5,
                    0.84,
                    0.9,
                    0.95,
                    0.975
                ],
                "method": "percentile",
                "replicates": 1000,
                "seed": 1980
            },
            "type": "StatisticsReporter",
            "values": {
                "control_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "control_value_STDERR": {
                    "stat": "STDERR",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "treatment_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "treatment_value_STDERR": {
                    "stat": "STDERR",
                    "type": "std::pair<double, std::vector<double> >"
                }
            }
        }
    },
    "time_steps": [
        {
            "stats": {
                "control_value_MEAN": [
                    56.22222222222222,
                    [
                        33.111111111111114,
                        36.22222222222222,
                        40.55555555555556,
                        43.55555555555556,
                        55.44444444444444,
                        68.77777777777777,
                        72.44444444444444,
                        78.22222222222223,
                        82.55555555555556
                    ]
                ],
                "control_value_STDERR": [
                    14.158603369778957,
                    [
                        4.223318571110451,
                        4.801941479788009,
                        6.780281868935997,
                        8.64491572551373,
                        13.498399539332683,
                        16.668148082310378,
                        17.411770532786715,
                        18.320786952745816,
                        18.990819744495003
                    ]
                ],
                "treatment_value_MEAN": [
                    86.85714285714286,
                    [
                        42.42857142857143,
                        48.285714285714285,
                        55.714285714285715,
                        62.714285714285715,
                        85.57142857142857,
                        109.71428571428571,
                        116.57142857142857,
                        125.42857142857143,
                        132.42857142857142
                    ]
                ],
                "treatment_value_STDERR": [
                    25.235489533052238,
                    [
                        11.389217958854141,
                        13.197093062721141,
                        14.37708872728094,
                        16.51241544855198,
                        23.595658542215265,
                        27.97946282786813,
                        29.364470178151304,
                        30.838067296084283,
                        31.89299712015355
                    ]
                ]
            },
            "time": 2.0,
            "time_step": 2
        }
    ]
}

Input Parameters

computeThe statistic(s) to compute for each of the supplied vector postprocessors.
C++ Type:MultiMooseEnum
Options:min, max, sum, mean, stddev, norm2, ratio, stderr, median, meanabs
Controllable:No
Description:The statistic(s) to compute for each of the supplied vector postprocessors.

Required Parameters

ci_levels0.1 0.9 A vector of confidence levels to consider, values must be in (0, 1).
Default:0.1 0.9
C++ Type:std::vector<double>
Unit:(no unit assumed)
Controllable:No
Description:A vector of confidence levels to consider, values must be in (0, 1).
ci_methodThe method to use for computing confidence level intervals.
C++ Type:MooseEnum
Options:percentile, bca
Controllable:No
Description:The method to use for computing confidence level intervals.
ci_replicates10000The number of replicates to use when computing confidence level intervals.
Default:10000
C++ Type:unsigned int
Controllable:No
Description:The number of replicates to use when computing confidence level intervals.
ci_seed1The random number generator seed used for creating replicates while computing confidence level intervals.
Default:1
C++ Type:unsigned int
Controllable:No
Description:The random number generator seed used for creating replicates while computing confidence level intervals.
reportersList of Reporter values to utilized for statistic computations.
C++ Type:std::vector<ReporterName>
Controllable:No
Description:List of Reporter values to utilized for statistic computations.
vectorpostprocessorsList of VectorPostprocessor(s) to utilized for statistic computations.
C++ Type:std::vector<VectorPostprocessorName>
Unit:(no unit assumed)
Controllable:No
Description:List of VectorPostprocessor(s) to utilized for statistic computations.

Optional Parameters

allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
Default:False
C++ Type:bool
Controllable:No
Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).
execute_onTIMESTEP_ENDThe list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
Default:TIMESTEP_END
C++ Type:ExecFlagEnum
Options:NONE, INITIAL, LINEAR, LINEAR_CONVERGENCE, NONLINEAR, NONLINEAR_CONVERGENCE, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, MULTIAPP_FIXED_POINT_CONVERGENCE, FINAL, CUSTOM
Controllable:No
Description:The list of flag(s) indicating when this object should be executed. For a description of each flag, see https://mooseframework.inl.gov/source/interfaces/SetupInterface.html.
execution_order_group0Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
Default:0
C++ Type:int
Controllable:No
Description:Execution order groups are executed in increasing order (e.g., the lowest number is executed first). Note that negative group numbers may be used to execute groups before the default (0) group. Please refer to the user object documentation for ordering of user object execution within a group.
force_postauxFalseForces the UserObject to be executed in POSTAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in POSTAUX
force_preauxFalseForces the UserObject to be executed in PREAUX
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREAUX
force_preicFalseForces the UserObject to be executed in PREIC during initial setup
Default:False
C++ Type:bool
Controllable:No
Description:Forces the UserObject to be executed in PREIC during initial setup

Execution Scheduling Parameters

control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Controllable:Yes
Description:Set the enabled status of the MooseObject.
outputsVector of output names where you would like to restrict the output of variables(s) associated with this object
C++ Type:std::vector<OutputName>
Controllable:No
Description:Vector of output names where you would like to restrict the output of variables(s) associated with this object
use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.
Default:False
C++ Type:bool
Controllable:No
Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Advanced Parameters

prop_getter_suffixAn optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
C++ Type:MaterialPropertyName
Unit:(no unit assumed)
Controllable:No
Description:An optional suffix parameter that can be appended to any attempt to retrieve/get material properties. The suffix will be prepended with a '_' character.
use_interpolated_stateFalseFor the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.
Default:False
C++ Type:bool
Controllable:No
Description:For the old and older state use projected material properties interpolated at the quadrature points. To set up projection use the ProjectedStatefulMaterialStorageAction.

Material Property Retrieval Parameters

References

Robert J Tibshirani and Bradley Efron. An introduction to the bootstrap. Monographs on statistics and applied probability, 57:1–436, 1993.

@article{tibshirani1993introduction,
    author = "Tibshirani, Robert J and Efron, Bradley",
    title = "An introduction to the bootstrap",
    journal = "Monographs on statistics and applied probability",
    volume = "57",
    pages = "1--436",
    year = "1993",
    publisher = "Chapman and Hall New York"
}

(moose/modules/stochastic_tools/test/tests/reporters/statistics/statistics.i)

[StochasticTools]
[]

[VectorPostprocessors]
  [const]
    type = ConstantVectorPostprocessor
    value = '1 2 3 4 5'
    outputs = none
  []
[]

[Reporters]
  [stats]
    type = StatisticsReporter
    vectorpostprocessors = 'const'
    compute = 'min max sum mean stddev norm2'
  []
[]

[Outputs]
  execute_on = FINAL
  [out]
    type = JSON
  []
[]

(moose/modules/stochastic_tools/test/tests/reporters/statistics/gold/statistics_out.json)

{
    "reporters": {
        "stats": {
            "type": "StatisticsReporter",
            "values": {
                "const_value_MAX": {
                    "stat": "MAX",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_MIN": {
                    "stat": "MIN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_NORM2": {
                    "stat": "NORM2",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_STDDEV": {
                    "stat": "STDDEV",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "const_value_SUM": {
                    "stat": "SUM",
                    "type": "std::pair<double, std::vector<double> >"
                }
            }
        }
    },
    "time_steps": [
        {
            "stats": {
                "const_value_MAX": [
                    5.0,
                    []
                ],
                "const_value_MEAN": [
                    3.0,
                    []
                ],
                "const_value_MIN": [
                    1.0,
                    []
                ],
                "const_value_NORM2": [
                    7.416198487095663,
                    []
                ],
                "const_value_STDDEV": [
                    1.5811388300841898,
                    []
                ],
                "const_value_SUM": [
                    15.0,
                    []
                ]
            },
            "time": 2.0,
            "time_step": 2
        }
    ]
}

(moose/modules/stochastic_tools/test/tests/reporters/bootstrap_statistics/percentile/percentile.i)

[StochasticTools]
[]

[VectorPostprocessors]
  # Table 2.1 in Efron and Tibshirani, 1993
  [treatment]
    type = ConstantVectorPostprocessor
    value = '94 197 16 38 99 141 23'
    outputs = none
  []
  [control]
    type = ConstantVectorPostprocessor
    value = '52 104 146 10 51 30 40 27 46'
    outputs = none
  []
[]

[Reporters]
  # Reproduce Table 13.1 in Efron and Tibshirani, 1993
  [stats]
    type = StatisticsReporter
    vectorpostprocessors = 'treatment control'
    compute = 'mean stderr'
    ci_method = 'percentile'
    ci_levels = '0.025 0.05 0.1 0.16 0.5 0.84 0.9 0.95 0.975'
    ci_replicates = 1000
    ci_seed = 1980
  []
[]

[Outputs]
  execute_on = FINAL
  [out]
    type = JSON
  []
[]

(moose/modules/stochastic_tools/test/tests/reporters/bootstrap_statistics/percentile/gold/percentile_out.json)

{
    "reporters": {
        "stats": {
            "confidence_intervals": {
                "levels": [
                    0.025,
                    0.05,
                    0.1,
                    0.16,
                    0.5,
                    0.84,
                    0.9,
                    0.95,
                    0.975
                ],
                "method": "percentile",
                "replicates": 1000,
                "seed": 1980
            },
            "type": "StatisticsReporter",
            "values": {
                "control_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "control_value_STDERR": {
                    "stat": "STDERR",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "treatment_value_MEAN": {
                    "stat": "MEAN",
                    "type": "std::pair<double, std::vector<double> >"
                },
                "treatment_value_STDERR": {
                    "stat": "STDERR",
                    "type": "std::pair<double, std::vector<double> >"
                }
            }
        }
    },
    "time_steps": [
        {
            "stats": {
                "control_value_MEAN": [
                    56.22222222222222,
                    [
                        33.111111111111114,
                        36.22222222222222,
                        40.55555555555556,
                        43.55555555555556,
                        55.44444444444444,
                        68.77777777777777,
                        72.44444444444444,
                        78.22222222222223,
                        82.55555555555556
                    ]
                ],
                "control_value_STDERR": [
                    14.158603369778957,
                    [
                        4.223318571110451,
                        4.801941479788009,
                        6.780281868935997,
                        8.64491572551373,
                        13.498399539332683,
                        16.668148082310378,
                        17.411770532786715,
                        18.320786952745816,
                        18.990819744495003
                    ]
                ],
                "treatment_value_MEAN": [
                    86.85714285714286,
                    [
                        42.42857142857143,
                        48.285714285714285,
                        55.714285714285715,
                        62.714285714285715,
                        85.57142857142857,
                        109.71428571428571,
                        116.57142857142857,
                        125.42857142857143,
                        132.42857142857142
                    ]
                ],
                "treatment_value_STDERR": [
                    25.235489533052238,
                    [
                        11.389217958854141,
                        13.197093062721141,
                        14.37708872728094,
                        16.51241544855198,
                        23.595658542215265,
                        27.97946282786813,
                        29.364470178151304,
                        30.838067296084283,
                        31.89299712015355
                    ]
                ]
            },
            "time": 2.0,
            "time_step": 2
        }
    ]
}

Description
Statistics
Confidence Levels
Example 1 : Statistics
Example 2 : Confidence Levels
Input Parameters
References