easyvvuq.analysis.basic_stats

  1"""Provides analysis element for basic statistical analysis.
  2
  3The analysis is based on `pandas.DataFrame.describe()` function.
  4"""
  5from easyvvuq import OutputType
  6from .base import BaseAnalysisElement
  7
  8__copyright__ = """
  9
 10    Copyright 2018 Robin A. Richardson, David W. Wright
 11
 12    This file is part of EasyVVUQ
 13
 14    EasyVVUQ is free software: you can redistribute it and/or modify
 15    it under the terms of the Lesser GNU General Public License as published by
 16    the Free Software Foundation, either version 3 of the License, or
 17    (at your option) any later version.
 18
 19    EasyVVUQ is distributed in the hope that it will be useful,
 20    but WITHOUT ANY WARRANTY; without even the implied warranty of
 21    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 22    Lesser GNU General Public License for more details.
 23
 24    You should have received a copy of the Lesser GNU General Public License
 25    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 26
 27"""
 28__license__ = "LGPL"
 29
 30
 31class BasicStats(BaseAnalysisElement):
 32
 33    def __init__(self, groupby=None, qoi_cols=None):
 34        """Element to calculate basic stats for `qoi_cols` values.
 35
 36        This results in values for: count, mean, std, min, max and 25%, 50% &
 37        75% percentiles for each value in the analysis.
 38
 39        Parameters
 40        ----------
 41        groupby : list or None
 42            Columns to use to group the data in `analyse` method before
 43            calculating stats.
 44        qoi_cols : list or None
 45            Columns of quantities of interest (for which stats will be
 46            calculated).
 47        """
 48        self.groupby = groupby
 49        if qoi_cols is not None:
 50            self.qoi_cols = qoi_cols
 51        else:
 52            self.qoi_cols = []
 53        self.output_type = OutputType.SUMMARY
 54
 55    def element_name(self):
 56        """Name for this element for logging purposes"""
 57        return "basic_stats"
 58
 59    def element_version(self):
 60        """Version of this element for logging purposes"""
 61        return "0.1"
 62
 63    def analyse(self, data_frame=None):
 64        """Perform the basis stats analysis on the input `data_frame`.
 65
 66        Analysis is based on `pandas.Dataframe.describe` and results in
 67        values for: count, mean, std, min, max and 25%, 50% & 75% percentiles
 68        for each value in the analysis.
 69
 70        The data_frame is grouped according to `self.groupby` if specified and
 71        analysis is performed on the columns selected in `self.qoi_cols` if set.
 72
 73        Parameters
 74        ----------
 75        data_frame : :obj:`pandas.DataFrame`
 76            Summary data produced through collation of simulation output.
 77
 78        Returns
 79        -------
 80        :obj:`pandas.DataFrame`
 81            Basic statistic for selected columns and groupings of data.
 82        """
 83
 84        qoi_cols = self.qoi_cols
 85
 86        if data_frame is None:
 87            raise RuntimeError("Analysis element needs a data frame to "
 88                               "analyse")
 89        elif data_frame.empty:
 90            raise RuntimeError(
 91                "No data in data frame passed to analyse element")
 92
 93        # Get summary statistics
 94        if self.groupby:
 95            grouped_data = data_frame.groupby(self.groupby)
 96            results = grouped_data.describe()
 97            if qoi_cols:
 98                results = results[qoi_cols]
 99
100        else:
101            if qoi_cols:
102                results = data_frame[qoi_cols].describe()
103            else:
104                results = data_frame.describe()
105
106        return results