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 (Σ\Sigma) of the supplied vectors v\vec{v}, where NN is the length of the vector:

    Σ=i=1Nvi\Sigma = \sum_{i=1}^N{v_i}

  • mean

    compute = average
    Computes the average (vˉ\bar{v}) of the supplied vectors v\vec{v}:

    vˉ=i=1NviN\bar{v} = \frac{\sum_{i=1}^{N}{v_i}}{N}

  • standard deviation

    compute = stddev
    Computes the standard deviation (σ\sigma) of the supplied vectors v\vec{v}:

    σ=i=1N(vivˉ)2N1\sigma = \sqrt{\frac{\sum_{i=1}^{N}{(v_i - \bar{v})^2}}{N-1}}

  • L2-Norm

    compute = norm2
    Computes the L2-norm, v2|v|_2 of the supplied vectors v\vec{v}, this is also known as the Euclidean Norm or the "distance":

    v2=i=1Nvi2|v|_2 = \sqrt{\sum_{i=1}^{N}{{v_i}^2}}

  • standard error

    compute = stderr
    Computes the standard error (σvˉ\sigma_{\bar{v}}) of the supplied vectors v\vec{v}:

    σvˉ=σN\sigma_{\bar{v}} = \frac{\sigma}{\sqrt{N}}

  • 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 v=[v1,...,vN]\vec{v} = [v_1,...,v_N]:

    median(v)={w(N+1)/2,if N is oddwN/2+wN/2+12,if N is even\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 .

    where

    w=sort(v)\vec{w} = \mathrm{sort}(\vec{v})

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:

Example 1: Statistics

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

[Reporters]
  [stats]
    type = StatisticsReporter
    vectorpostprocessors = 'const'
    compute = 'min max sum mean stddev norm2'
  []
[]
(contrib/moose/modules/stochastic_tools/test/tests/reporters/statistics/statistics.i)

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
        }
    ]
}
(contrib/moose/modules/stochastic_tools/test/tests/reporters/statistics/gold/statistics_out.json)

Example 2: Confidence Levels

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

[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
  []
[]
(contrib/moose/modules/stochastic_tools/test/tests/reporters/bootstrap_statistics/percentile/percentile.i)

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
        }
    ]
}
(contrib/moose/modules/stochastic_tools/test/tests/reporters/bootstrap_statistics/percentile/gold/percentile_out.json)

Input Parameters

  • computeThe statistic(s) to compute for each of the supplied vector postprocessors.

    C++ Type:MultiMooseEnum

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    Controllable:No

    Description:The random number generator seed used for creating replicates while computing confidence level intervals.

  • 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

    Unit:(no unit assumed)

    Options:NONE, INITIAL, LINEAR, NONLINEAR_CONVERGENCE, NONLINEAR, POSTCHECK, TIMESTEP_END, TIMESTEP_BEGIN, MULTIAPP_FIXED_POINT_END, MULTIAPP_FIXED_POINT_BEGIN, 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.

  • 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.

  • reportersList of Reporter values to utilized for statistic computations.

    C++ Type:std::vector<ReporterName>

    Unit:(no unit assumed)

    Controllable:No

    Description:List of Reporter values to utilized for statistic computations.

  • 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

    Unit:(no unit assumed)

    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.

  • 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

    Unit:(no unit assumed)

    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).

  • control_tagsAdds user-defined labels for accessing object parameters via control logic.

    C++ Type:std::vector<std::string>

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    Controllable:Yes

    Description:Set the enabled status of the MooseObject.

  • 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

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    Controllable:No

    Description:Forces the UserObject to be executed in PREIC during initial setup

  • outputsVector of output names where you would like to restrict the output of variables(s) associated with this object

    C++ Type:std::vector<OutputName>

    Unit:(no unit assumed)

    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

    Unit:(no unit assumed)

    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

References

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