easyvvuq.analysis.results

  1"""
  2Represents the results obtained during the analysis stage.
  3All the analysis classes should implement this in a way that makes
  4most sense. Provides a more unified interface for accessing the results
  5in a variety of formats (e.g. NumPy arrays or pandas DataFrames). This module
  6also provides a variety of ways to display results as well as a way to access
  7surrogate functionality.
  8"""
  9
 10import pandas as pd
 11import numpy as np
 12import itertools
 13
 14
 15class AnalysisResults:
 16    """Contains the analysis results.
 17
 18    Parameters
 19    ----------
 20    raw_data: obj
 21        An arbitrary object that contains raw analysis data.
 22
 23    samples: pandas DataFrame
 24        Collated samples.
 25
 26    qois: list of str
 27        List of qoi names used during the analysis.
 28
 29    inputs: list of str
 30        List of input names used during the analysis.
 31    """
 32
 33    def __init__(self, raw_data=None, samples=None, qois=None, inputs=None):
 34        self.raw_data = raw_data
 35        self.samples = samples
 36        self.qois = qois
 37        self.inputs = inputs
 38
 39    def supported_stats(self):
 40        """Returns a list of descriptive statistics that the method reports.
 41
 42        Examples
 43        --------
 44        >>> results.supported_stats()
 45        ['min', 'max', '10%', '90%', '1%', '99%', 'median', 'mean', 'var', 'std']
 46
 47        Returns
 48        -------
 49        list of str
 50            A list of statistics that can then be passed to the `describe` method.
 51        """
 52        raise NotImplementedError('descriptive statistics not available in this method')
 53
 54    def _get_derivatives_first(self, qoi, input_):
 55        """Returns the first order derivative-based index for a given qoi wrt input variable.
 56
 57        Parameters
 58        ----------
 59        qoi : str
 60           Quantity of interest
 61        input_ : str
 62           Input variable
 63
 64        Returns
 65        -------
 66        float
 67            First order derivative-based index.
 68        """
 69        raise NotImplementedError
 70
 71
 72    def _get_sobols_first(self, qoi, input_):
 73        """Returns first order Sobol indices.
 74
 75        Parameters
 76        ----------
 77        qoi - str or tuple
 78            Quantity of interest or if a tuple quantity of interest plus
 79            coordinate index (for cases where qoi is vector valued).
 80        input_ - str
 81            Input variable name.
 82
 83        Returns
 84        -------
 85        np.array
 86            An array with first order sobol indices. If the `qoi` is not vector valued the
 87            array will have one element.
 88        """
 89        raise NotImplementedError
 90
 91    def _get_sobols_second(self, qoi, input_):
 92        """Returns second order Sobol indices.
 93
 94        Parameters
 95        ----------
 96        qoi - str or tuple
 97           Quantity of interest or if a tuple quantity of interest plus
 98           coordinate index (for cases where qoi is vector valued).
 99        input_ - str
100           Input variable name.
101
102        Returns
103        -------
104        np.array
105            An array with first order sobol indices. If the `qoi` is not vector valued the
106            array will have one element.
107        """
108        raise NotImplementedError
109
110    def _get_sobols_total(self, qoi, input_):
111        """Returns total order Sobol indices.
112
113        Parameters
114        ----------
115        qoi - str or tuple
116           Quantity of interest or if a tuple quantity of interest plus
117           coordinate index (for cases where qoi is vector valued).
118        input_ - str
119           Input variable name.
120
121        Returns
122        -------
123        np.array
124            An array with total order sobol indices. If the `qoi` is not vector valued the
125            array will have one element.
126        """
127        raise NotImplementedError
128
129    def _get_sobols_first_conf(self, qoi, input_):
130        """Returns confidence intervals for first order Sobol indices.
131
132        Attributes
133        ----------
134        qoi : str
135            Name of the qoi for which the first order sensitivity index
136            confidence interval is requested.
137        input_ : str
138            Name of the input for which the first order sensitivy index
139            confidence interval is requested.
140
141        Returns
142        -------
143        list
144            A list of two floats - lower and upper confidence interval bounds.
145        """
146        raise NotImplementedError
147
148    def _get_sobols_total_conf(self, qoi, input_):
149        """Returns confidence intervals for total order Sobol indices.
150
151        Attributes
152        ----------
153        qoi : str
154            Name of the qoi for which the first order sensitivity index
155            confidence interval is requested.
156        input_ : str
157            Name of the input for which the first order sensitivy index
158            confidence interval is requested.
159
160        Returns
161        -------
162        list
163            A list of two floats - lower and upper confidence interval bounds.
164        """
165        raise NotImplementedError
166
167    def _get_sobols_general(self, getter, qoi=None, input_=None):
168        """A generic method for getting sobol indices.
169
170        Parameters
171        ----------
172        getter: function
173             Method that takes a AnalysisResults instance and returns
174             a Sobol index of some kind. For example _get_bonols_first.
175
176        qoi: str or tuple
177            The name of the quantity of interest or None.
178            Use a tuple of the form (qoi, index) where index is integer
179            that means the coordinate index of a vector qoi.
180
181        input_: str
182            The name of the input parameter or None.
183
184        Returns
185        -------
186        dict or array
187        """
188        assert (not ((qoi is None) and (input_ is not None)))
189        if (qoi is not None) and (qoi not in self.qois):
190            raise RuntimeError('no such qoi in this analysis')
191        if (input_ is not None) and (input_ not in self.inputs):
192            raise RuntimeError('no such input variable in this analysis')
193        try:
194            if input_ is None:
195                if qoi is None:
196                    return dict([(qoi_, dict([(in_, getter(qoi_, in_))
197                                              for in_ in self.inputs]))
198                                 for qoi_ in self.qois])
199                else:
200                    return dict([(in_, getter(qoi, in_))
201                                 for in_ in self.inputs])
202            else:
203                return getter(qoi, input_)
204        except NotImplementedError:
205            raise RuntimeError(
206                'this kind of sobol index reporting not implemented in this analysis method')
207
208    def derivatives_first(self, qoi=None, input_=None):
209        """Return first order derivative-based sensitivity indices.
210
211        Parameters
212        ----------
213        qoi: str or tuple
214            The name of the quantity of interest or None.
215            Use a tuple of the form (qoi, index) where index is integer
216            that means the coordinate index of a vector qoi.
217
218        input_: str
219            The name of the input parameter or None.
220
221        Examples
222        --------
223        >>> results.derivatives_first()
224        {'f': {'x1': array([0.610242]), 'x2': array([0.26096511])}}
225        >>> results.derivatives_first('f')
226        {'x1': array([0.610242]), 'x2': array([0.26096511])}
227        >>> results.derivatives_first('f', 'x1')
228        array([0.610242])
229        >>> results_vectors.derivatives_first(('g', 2))
230        {'x1': array([0.5]), 'x2': array([0.5])}
231
232        Returns
233        -------
234        dict or array
235           If both qoi and input_ are specified will return a dictionary,
236           otherwise will return an array.
237        """
238        return self._get_sobols_general(self._get_derivatives_first, qoi, input_)
239
240    def sobols_first(self, qoi=None, input_=None):
241        """Return first order sensitivity indices.
242
243        Parameters
244        ----------
245        qoi: str or tuple
246            The name of the quantity of interest or None.
247            Use a tuple of the form (qoi, index) where index is integer
248            that means the coordinate index of a vector qoi.
249
250        input_: str
251            The name of the input parameter or None.
252
253        Examples
254        --------
255        >>> results.sobols_first()
256        {'f': {'x1': array([0.610242]), 'x2': array([0.26096511])}}
257        >>> results.sobols_first('f')
258        {'x1': array([0.610242]), 'x2': array([0.26096511])}
259        >>> results.sobols_first('f', 'x1')
260        array([0.610242])
261        >>> results_vectors.sobols_first(('g', 2))
262        {'x1': array([0.5]), 'x2': array([0.5])}
263
264        Returns
265        -------
266        dict or array
267           If both qoi and input_ are specified will return a dictionary,
268           otherwise will return an array.
269        """
270        return self._get_sobols_general(self._get_sobols_first, qoi, input_)
271
272    def sobols_second(self, qoi=None, input_=None):
273        """Return second order sensitivity indices.
274
275        Parameters
276        ----------
277        qoi: str or tuple
278            The name of the quantity of interest or None.
279            Use a tuple of the form (qoi, index) where index is integer
280            that means the coordinate index of a vector qoi.
281
282        input_: str
283            The name of the input parameter or None.
284
285        Examples
286        --------
287        >>> results.sobols_second('a')
288        {'F': {'L': array([0.000121]),
289        'a': array([0.00695338]),
290        'D': array([0.00141272])},
291        'L': {'F': array([0.000121]),
292        'a': array([0.00012737]),
293        'D': array([0.00012716])},
294        'a': {'F': array([0.00695338]),
295        'L': array([0.00012737]),
296        'D': array([0.00730415])},
297        'D': {'F': array([0.00141272]),
298        'L': array([0.00012716]),
299        'a': array([0.00730415])}}
300        >>> results.sobols_second('g1', 'L')
301        {'F': array([0.000121]), 'a': array([0.00012737]), 'D': array([0.00012716])}
302        Returns
303        -------
304        dict
305           Will always return a dictionary unlike first order sobol indices. Because
306           the index is specified by a pair of inputs. The dictionary will include
307           all inputs but `input_`.
308        """
309        return self._get_sobols_general(self._get_sobols_second, qoi, input_)
310
311    def sobols_total(self, qoi=None, input_=None):
312        """Returns total order sensitivity indices.
313
314        Parameters
315        ----------
316        qoi: str or tuple
317            The name of the quantity of interest or None.
318            Use a tuple of the form (qoi, index) where index is integer
319            that means the coordinate index of a vector qoi.
320        input_: str
321            The name of the input parameter or None.
322
323
324        Examples
325        --------
326        >>> results.sobols_total('g1')
327        {'F': array([0.14299044]),
328        'L': array([0.01247877]),
329        'a': array([0.7105291]),
330        'D': array([0.15018883])}
331        >>> results.sobols_total('g1', 'F')
332        array([0.14299044])
333
334        Returns
335        -------
336        dict or array
337           If both qoi and input_ are specified will return a dictionary,
338           otherwise will return an array.
339        """
340        return self._get_sobols_general(self._get_sobols_total, qoi, input_)
341
342    def surrogate(self):
343        """Returns the surrogate model as a function from parameter dictionary
344        to output dictionary. This only needs to be implemented if the analysis
345        method in question provides surrogate models.
346
347
348        Returns
349        -------
350        function
351            Returns a function that takes a dictionary and returns a dictionary.
352            These dictionaries use the same format as Encoder and Decoder used
353            to construct the surrogate.
354        """
355        raise NotImplementedError
356
357    def describe(self, qoi=None, statistic=None):
358        """Returns descriptive statistics.
359
360        Examples
361        --------
362        >>> results.describe()
363                     g                             h
364                     0         1         2         0         1
365        mean  0.500000  0.500000  1.000000  0.250000  0.693787
366        var   0.083333  0.083333  0.166667  0.048611  0.068236
367        std   0.288675  0.288675  0.408248  0.220479  0.261220
368        10%   0.100897  0.099462  0.441589  0.019049  0.276504
369        90%   0.896960  0.899417  1.544624  0.584600  0.974707
370        min   0.000041  0.000005  0.016687  0.000016 -0.008642
371        max   0.999998  0.999873  1.993517  0.985350  1.024599
372
373        >>> result.describe('h')
374                     h
375                     0         1
376        mean  0.250000  0.693787
377        var   0.048611  0.068236
378        std   0.220479  0.261220
379        10%   0.019049  0.276504
380        90%   0.584600  0.974707
381        min   0.000016 -0.008642
382        max   0.985350  1.024599
383
384        >>> results.describe('h', 'var')
385        array([0.04861111, 0.06823568])
386
387        Parameters
388        ----------
389        qoi: str or None
390            if not None it is the name of the quantity of interest
391        statistic: str or None
392            if not None it is the name of the statistic, currently supported ones
393            are: ['mean', 'var', 'std', '10%', '90%', 'min', 'max', 'median']
394
395        Returns
396        -------
397        DataFrame or array
398            If both quantity of interest and the statistic are specified will return
399            an array with the values for that statistic. Otherwise will return a DataFrame
400            with more data.
401        """
402        assert (not ((qoi is None) and (statistic is not None)))
403        statistics = ['mean', 'var', 'std', '1%', '10%', '90%', '99%', 'min', 'max', 'median']
404        qois = self.qois
405        if qoi is not None:
406            qois = [qoi]
407        if statistic is not None:
408            statistics = [statistic]
409        result = {}
410        for qoi in qois:
411            for statistic_ in statistics:
412                try:
413                    value = self._describe(qoi, statistic_)
414                    assert (isinstance(value, np.ndarray))
415                    for i, x in enumerate(value):
416                        try:
417                            result[(qoi, i)][statistic_] = x
418                        except KeyError:
419                            result[(qoi, i)] = {statistic_: x}
420                except NotImplementedError:
421                    if statistic is not None:
422                        raise RuntimeError(
423                            "this statistic ({}) is not reported by this analysis class".format(statistic))
424        if qois is not None and statistic is not None:
425            return pd.DataFrame(result)[qoi].loc[statistic].values
426        else:
427            return pd.DataFrame(result)
428
429    def plot_sobols_treemap(self, qoi, figsize=(10, 10), ax=None, filename=None, dpi=None):
430        """Plot sobols first and second order indices in a hierarchical treemap format.
431
432        Parameters
433        ----------
434        qoi: str
435           Name of the quantity of interest.
436        figsize: tuple
437           A tuple with two integers representing figure size in inches.
438        ax: matplotlib
439           Matplotlib axis to plot on.
440        filename: str
441           Filename to write the plot to. If left None will display to screen.
442        dpi: int
443           Dots per inches. Only used when writing to file.
444        """
445        if qoi not in self.qois:
446            raise RuntimeError("no such qoi - {}".format(qoi))
447        import matplotlib.pyplot as plt
448        import matplotlib._color_data as mcd
449        import squarify
450        sobols_first = self.sobols_first(qoi)
451        keys = list(sobols_first.keys())
452        values = [value[0] for value in list(sobols_first.values())]
453        keys = ["{}\n{:.5f}".format(key, value) for key, value in zip(keys, values)]
454        if sum(values) < 1.0:
455            keys.append("higher orders\n{:.5f}".format(1.0 - sum(values)))
456            values.append(1.0 - sum(values))
457        colors = mcd.XKCD_COLORS
458        if ax is None:
459            fig, ax = plt.subplots()
460        else:
461            fig = ax.get_figure()
462        fig.set_size_inches(figsize)
463        ax.set_title("Decomposition of {} variance".format(qoi))
464        squarify.plot(sizes=values, label=keys, color=colors, ax=ax, pad=True)
465        ax.axis('off')
466        if filename is None:
467            fig.show()
468        else:
469            fig.savefig(filename, dpi=dpi)
470
471    def plot_sobols_first(self, qoi, inputs=None, withdots=False,
472                          ylabel=None, xlabel=None, xvalues=None,
473                          filename=None, dpi=None, ax=None):
474        """Plot first order sobol indices.
475
476        Parameters
477        ----------
478        qoi: str
479            a vector quantity of interest for which sobol indices will be plotted
480        inputs: list of str or None
481            list of inputs to plot if None will use all input variables
482        withdots: bool
483            if True will add shapes on top of the lines in the plot for visual clarity
484        ylabel: str or None
485            if None will use "First Order Sobol Index"
486        xlabel: str or None
487            if None will use the name of the qoi
488        xvalues: array or None
489           x-axis coordiante if None will use range(len(qoi_values))
490        filename: str or None
491            if None will try to open a plotting window on-screen, otherwise will write the plot to this file, with the type determined by the extension specified
492        dpi: int
493            dots per inch, quality of the image if a raster format was chosen
494        ax: matplotlib axes object, default None
495            if None, plots to a new axes, otherwise plot to existing axes ax
496
497        Returns
498        -------
499        matplotlib axes object
500            the actual axes plotted to
501        """
502        if qoi not in self.qois:
503            raise RuntimeError("no such qoi - {}".format(qoi))
504        if inputs is None:
505            inputs = self.inputs
506        for input_ in inputs:
507            if input_ not in self.inputs:
508                raise RuntimeError("no such input variable - {}".format(input_))
509        import matplotlib.pyplot as plt
510        if withdots:
511            styles = itertools.cycle(['-o', '-v', '-^', '-<', '->', '-8', '-s',
512                                      '-p', '-*', '-h', '-H', '-D', '-d', '-P', '-X'])
513        else:
514            styles = itertools.cycle(['-'])
515        points = None
516        for input_ in inputs:
517            if points is None:
518                indices = self.sobols_first(qoi, input_)
519                if len(indices) < 2:
520                    raise RuntimeError('this method is only implemented for vector qois')
521                points = [indices]
522            else:
523                points.append(self.sobols_first(qoi, input_))
524        if xvalues is None:
525            xvalues = np.arange(len(points[0]))
526        if ax is None:
527            fig, ax = plt.subplots()
528        else:
529            fig = ax.get_figure()
530        higher = np.array([1.0] * len(points[0]))
531        for p, label in zip(points, inputs):
532            higher -= p
533            ax.plot(xvalues, p, next(styles), label=label)
534        ax.plot(xvalues, higher, next(styles), label='higher orders')
535        ax.grid(True)
536        if ylabel is None:
537            ax.set_ylabel('First Order Sobol Index')
538        else:
539            ax.set_ylabel(ylabel)
540        if xlabel is None:
541            ax.set_xlabel('x-axis')
542        else:
543            ax.set_xlabel(xlabel)
544        ax.legend()
545        if filename is not None:
546            fig.savefig(filename, dpi=dpi)
547        return ax
548
549    def plot_moments(
550            self,
551            qoi,
552            ylabel=None,
553            xlabel=None,
554            xvalues=None,
555            alpha=0.2,
556            filename=None,
557            dpi=None,
558            ax=None):
559        """Plot statistical moments for this analysis.
560
561        Parameters
562        ----------
563        qoi: str
564            a vector quantity of interest for which sobol indices will be plotted
565        ylabel: str or None
566            if None will use "Values"
567        xlabel: str or None
568            if None will use the name of the qoi
569        xvalues: array or None
570            x-axis coordiante if None will use range(len(qoi_values)))
571        alpha: float
572            transparency amount
573        filename: str or None
574            if None will try to open a plotting window on-screen, otherwise will
575            write the plot to this file, with the type determined by the extension specified
576        dpi: int
577            dots per inch, quality of the image if a raster format was chosen
578        ax: matplotlib axes object, default None
579            if None, plots to a new axes, otherwise plot to existing axes ax
580
581        Returns
582        -------
583        matplotlib axes object
584            the actual axes plotted to
585        """
586        if qoi not in self.qois:
587            raise RuntimeError("no such qoi - {}".format(qoi))
588        import matplotlib.pyplot as plt
589        if ax is None:
590            fig, ax = plt.subplots()
591        else:
592            fig = ax.get_figure()
593        if xvalues is None:
594            xvalues = np.arange(len(self.describe(qoi, 'mean')))
595        ax.fill_between(xvalues, self.describe(qoi, 'mean') -
596                        self.describe(qoi, 'std'), self.describe(qoi, 'mean') +
597                        self.describe(qoi, 'std'), label='std', alpha=alpha)
598        ax.plot(xvalues, self.describe(qoi, 'mean'), label='mean')
599        if all(v in self.supported_stats() for v in ['1%', '99%']):
600            ax.plot(xvalues, self.describe(qoi, '1%'), '--', label='1%', color='black')
601            ax.plot(xvalues, self.describe(qoi, '99%'), '--', label='99%', color='black')
602        ax.grid(True)
603        if ylabel is None:
604            ax.set_ylabel(qoi)
605        else:
606            ax.set_ylabel(ylabel)
607        if xlabel is None:
608            ax.set_xlabel('x-axis')
609        else:
610            ax.set_xlabel(xlabel)
611        ax.legend()
612        if filename is not None:
613            fig.savefig(filename, dpi=dpi)
614        return ax
615
616    def get_distribution(self, qoi):
617        """Returns a distribution for the given qoi.
618
619        Parameters
620        ----------
621        qoi: str
622            QoI name
623
624        Returns
625        -------
626        A ChaosPy distribution
627        """
628        raise NotImplementedError
629
630    @staticmethod
631    def _keys_to_tuples(dictionary):
632        """Convert the keys in the dictionary to tuples.
633
634        Parameters
635        ----------
636        dictionary : dict
637            A dictionary with either strings or tuples as keys.
638
639        Examples
640        --------
641        >>> AnalysisResults._keys_to_tuples({'a': 1, 'b': 2})
642        {('a', 0): 1, ('b', 0): 2})
643
644        >>> AnalysisResults._keys_to_tuples({('a', 0): 1, ('b', 0): 2})
645        {('a', 0): 1, ('b', 0): 2})
646
647        >>> AnalysisResults._keys_to_tuples({('a', 0): 1, 'b': 2})
648        {('a', 0): 1, ('b', 0): 2})
649
650        Returns
651        -------
652        A dictionary with tuples as keys.
653        """
654        new_dict = {}
655        for key in dictionary.keys():
656            new_dict[AnalysisResults._to_tuple(key)] = dictionary[key]
657        return new_dict
658
659    @staticmethod
660    def _to_tuple(key):
661        """Convert key to tuple if it is string, otherwise leave as is.
662
663        Parameters
664        ----------
665        key: str or tuple
666
667        Examples
668        --------
669        >>> AnalysisResults._to_tuple('a')
670        ('a', 0)
671
672        >>> AnalysisResults._to_tuple(('a', 0))
673        ('a', 0)
674
675        Returns
676        -------
677        Tuple if key is string, key if key is tuple.
678        """
679        if isinstance(key, tuple):
680            return key
681        elif isinstance(key, str):
682            return (key, 0)
683        else:
684            raise RuntimeError("this method expects either a string or tuple")