.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "auto_data_analysis/statistical_tests/plot_fitted_copula_ranking.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_auto_data_analysis_statistical_tests_plot_fitted_copula_ranking.py: Select fitted copulas ===================== .. GENERATED FROM PYTHON SOURCE LINES 7-20 In this example we select the copula which best fits a sample. It mirrors :doc:`plot_fitted_distribution_ranking`, which deals with the marginal distributions, but focuses here on the dependence structure. Two complementary tools are combined: - ranking by BIC values with :meth:`~openturns.FittingTest.BestModelBIC`, - ranking by the p-values of the copula goodness-of-fit tests (:meth:`~openturns.FittingTest.CopulaCramerVonMises` and :meth:`~openturns.FittingTest.CopulaKolmogorov`, see :ref:`copula_test`). The normalization step required before computing a BIC on a copula is described in detail below. .. GENERATED FROM PYTHON SOURCE LINES 22-27 .. code-block:: Python import openturns as ot import openturns.viewer as otv ot.RandomGenerator.SetSeed(1) .. GENERATED FROM PYTHON SOURCE LINES 28-33 Create data with a known dependence structure --------------------------------------------- We sample a joint distribution with non-uniform marginals and a Gumbel copula, as is typical of real observations: the sample does not live in :math:`[0, 1]^d`. .. GENERATED FROM PYTHON SOURCE LINES 35-42 .. code-block:: Python true_copula = ot.GumbelCopula(4.0) marginals = [ot.Normal(), ot.Exponential()] distribution = ot.JointDistribution(marginals, true_copula) size = 500 sample = distribution.getSample(size) print("sample min/max=", sample.getMin(), sample.getMax()) .. rst-class:: sphx-glr-script-out .. code-block:: none sample min/max= [-3.4174,0.000155593] [2.8932,6.37817] .. GENERATED FROM PYTHON SOURCE LINES 43-50 **1. Rank copulas by BIC** A copula is a distribution on :math:`[0, 1]^d`: its probability density function is zero outside the unit hypercube. The BIC evaluates the log-likelihood of the sample under each candidate, so it must be computed on points inside :math:`[0, 1]^d`. Applied to the raw observations, it saturates to infinity: .. GENERATED FROM PYTHON SOURCE LINES 52-63 .. code-block:: Python copula_factories = [ ot.GumbelCopulaFactory(), ot.ClaytonCopulaFactory(), ot.NormalCopulaFactory(), ot.FrankCopulaFactory(), ot.IndependentCopulaFactory(), ] for factory in copula_factories: _, bic = ot.FittingTest.BIC(sample, factory) print(f"{factory.getClassName():25s} BIC={bic:.3f}") .. rst-class:: sphx-glr-script-out .. code-block:: none GumbelCopulaFactory BIC=inf ClaytonCopulaFactory BIC=inf NormalCopulaFactory BIC=inf FrankCopulaFactory BIC=inf IndependentCopulaFactory BIC=inf .. GENERATED FROM PYTHON SOURCE LINES 64-71 Note that a simple min/max rescaling to :math:`[0, 1]^d` is not sufficient: the boundary points then sit exactly on the border of the support, where the log-PDF of most copulas is still degenerated, and the rescaled margins are not uniform anyway. The sample must instead be mapped to uniform margins while preserving the dependence structure. The standard rank-based mapping uses the pseudo-observations :math:`(R_{i,j} + 1) / (n + 1)`, where :math:`R_{i,j}` is the rank of :math:`X_{i,j}` within its margin: .. GENERATED FROM PYTHON SOURCE LINES 73-76 .. code-block:: Python pseudo_sample = (sample.rank() + 1.0) / (size + 1.0) print("pseudo min/max=", pseudo_sample.getMin(), pseudo_sample.getMax()) .. rst-class:: sphx-glr-script-out .. code-block:: none pseudo min/max= [0.00199601,0.00199601] [0.998004,0.998004] .. GENERATED FROM PYTHON SOURCE LINES 77-80 An alternative, used in :doc:`/auto_data_analysis/distribution_fitting/plot_estimate_multivariate_distribution`, maps each margin through its fitted cumulative distribution function. Both mappings coincide asymptotically; ranks need no marginal estimation. .. GENERATED FROM PYTHON SOURCE LINES 82-83 The BIC ranking is then meaningful and selects the true family: .. GENERATED FROM PYTHON SOURCE LINES 85-92 .. code-block:: Python for factory in copula_factories: _, bic = ot.FittingTest.BIC(pseudo_sample, factory) print(f"{factory.getClassName():25s} BIC={bic:.3f}") best_copula, best_bic = ot.FittingTest.BestModelBIC(pseudo_sample, copula_factories) print("best copula:", best_copula) print("best BIC:", best_bic) .. rst-class:: sphx-glr-script-out .. code-block:: none GumbelCopulaFactory BIC=-2.106 ClaytonCopulaFactory BIC=-1.148 NormalCopulaFactory BIC=-2.041 FrankCopulaFactory BIC=-1.848 IndependentCopulaFactory BIC=0.000 best copula: GumbelCopula(theta = 4.31452) best BIC: -2.10610538747555 .. GENERATED FROM PYTHON SOURCE LINES 93-94 The same holds with fully specified copulas instead of factories: .. GENERATED FROM PYTHON SOURCE LINES 96-101 .. code-block:: Python candidates = [ot.GumbelCopula(4.0), ot.ClaytonCopula(6.0), ot.FrankCopula(5.0)] for copula in candidates: bic = ot.FittingTest.BIC(pseudo_sample, copula) print(f"{copula.getClassName():15s} BIC={bic:.3f}") .. rst-class:: sphx-glr-script-out .. code-block:: none GumbelCopula BIC=-2.109 ClaytonCopula BIC=-1.281 FrankCopula BIC=-1.166 .. GENERATED FROM PYTHON SOURCE LINES 102-109 **2. Rank copulas by goodness-of-fit tests** Unlike the BIC, the copula Cramer-von Mises and Kolmogorov tests of :ref:`copula_test` are rank-based: the pseudo-observations are computed internally, so the tests apply directly to the raw observations. With a factory, the copula parameters are estimated from the sample and the p-value is computed by parametric bootstrap: .. GENERATED FROM PYTHON SOURCE LINES 111-113 Reduce the bootstrap cost for the documentation; use the default ResourceMap keys for real studies. .. GENERATED FROM PYTHON SOURCE LINES 113-124 .. code-block:: Python ot.ResourceMap.SetAsUnsignedInteger("FittingTest-CopulaMinimumSamplingSize", 10) ot.ResourceMap.SetAsUnsignedInteger("FittingTest-CopulaMaximumSamplingSize", 100) for factory in [ot.GumbelCopulaFactory(), ot.ClaytonCopulaFactory()]: estimated, result = ot.FittingTest.CopulaCramerVonMises(sample, factory) print( f"{factory.getClassName():25s} p-value={result.getPValue():.3f} " f"statistic={result.getStatistic():.4f} " f"accept={result.getBinaryQualityMeasure()} estimated={estimated}" ) ot.ResourceMap.Reset() .. rst-class:: sphx-glr-script-out .. code-block:: none GumbelCopulaFactory p-value=0.260 statistic=0.0131 accept=True estimated=GumbelCopula(theta = 4.31452) ClaytonCopulaFactory p-value=0.000 statistic=0.1702 accept=False estimated=ClaytonCopula(theta = 6.62904) .. GENERATED FROM PYTHON SOURCE LINES 125-126 The Kolmogorov variant behaves similarly; here on the best BIC candidate: .. GENERATED FROM PYTHON SOURCE LINES 128-134 .. code-block:: Python ot.ResourceMap.SetAsUnsignedInteger("FittingTest-CopulaMaximumSamplingSize", 100) estimated, result = ot.FittingTest.CopulaKolmogorov(sample, ot.GumbelCopulaFactory()) print("estimated:", estimated) print(result) ot.ResourceMap.Reset() .. rst-class:: sphx-glr-script-out .. code-block:: none estimated: GumbelCopula(theta = 4.31452) class=TestResult name=Unnamed type=CopulaKolmogorov GumbelCopula binaryQualityMeasure=true p-value threshold=0.05 p-value=0.27 statistic=0.0169293 description=[GumbelCopula(theta = 4.31452) vs sample JointDistribution] .. GENERATED FROM PYTHON SOURCE LINES 135-140 Graphical validation in the rank space -------------------------------------- We plot the pseudo-observations with the iso-curves of the selected copula, as in :doc:`plot_test_copula`: .. GENERATED FROM PYTHON SOURCE LINES 142-156 .. code-block:: Python cloud = ot.Cloud(pseudo_sample, "blue", "plus", "pseudo-observations") graph = ot.Graph("Best copula vs pseudo-observations", "U1", "U2") graph.add(cloud) pdf_graph = best_copula.drawPDF([0.0] * 2, [1.0] * 2, [201] * 2) contour = pdf_graph.getDrawable(0) contour.setDrawLabels(False) nlev = 21 contour.setLevels([0.25 * nlev / (nlev - i) for i in range(nlev)]) contour.setLegend(str(best_copula.getClassName())) contour.setColor("red") graph.add(contour) graph.setLegendPosition("upper left") view = otv.View(graph) otv.View.ShowAll() .. image-sg:: /auto_data_analysis/statistical_tests/images/sphx_glr_plot_fitted_copula_ranking_001.svg :alt: Best copula vs pseudo-observations :srcset: /auto_data_analysis/statistical_tests/images/sphx_glr_plot_fitted_copula_ranking_001.svg :class: sphx-glr-single-img .. _sphx_glr_download_auto_data_analysis_statistical_tests_plot_fitted_copula_ranking.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: plot_fitted_copula_ranking.ipynb ` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: plot_fitted_copula_ranking.py ` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: plot_fitted_copula_ranking.zip `