From 8522e9ed4fccdfa741296d75c9303b6d3593b512 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 15:04:00 +0100 Subject: [PATCH 01/16] Do not pass width/height ratios to nested layouts --- lib/matplotlib/figure.py | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 1636e201019b..e7042de249eb 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1838,13 +1838,17 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, Defines the relative widths of the columns. Each column gets a relative width of ``width_ratios[i] / sum(width_ratios)``. If not given, all columns will have the same width. Equivalent - to ``gridspec_kw={'width_ratios': [...]}``. + to ``gridspec_kw={'width_ratios': [...]}``. This argument applies + only to the outer layout and will not be passed to the inner + layout. height_ratios : array-like of length *nrows*, optional Defines the relative heights of the rows. Each row gets a relative height of ``height_ratios[i] / sum(height_ratios)``. If not given, all rows will have the same height. Equivalent - to ``gridspec_kw={'height_ratios': [...]}``. + to ``gridspec_kw={'height_ratios': [...]}``. This argument + applies only to the outer layout and will not be passed to the + inner layout. subplot_kw : dict, optional Dictionary with keywords passed to the `.Figure.add_subplot` call @@ -1852,7 +1856,9 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, gridspec_kw : dict, optional Dictionary with keywords passed to the `.GridSpec` constructor used - to create the grid the subplots are placed on. + to create the grid the subplots are placed on. The 'width_ratios' + and 'height_ratios' keys, if present, will be removed from this + dictionary before it is passed to any inner layouts. empty_sentinel : object, optional Entry in the layout to mean "leave this space empty". Defaults @@ -1999,6 +2005,13 @@ def _do_layout(gs, mosaic, unique_ids, nested): for (j, k), nested_mosaic in nested.items(): this_level[(j, k)] = (None, nested_mosaic, 'nested') + # must remove these two options from the kwargs passed to the + # nested items, otherwise an error occurs if *any* of the inner + # layouts are not compatible with these ratios + nested_gs_kw = dict([(k, v) for k, v in gridspec_kw.items() + if k != "width_ratios" + and k != "height_ratios"]) + # now go through the things in this level and add them # in order left-to-right top-to-bottom for key in sorted(this_level): @@ -2022,7 +2035,7 @@ def _do_layout(gs, mosaic, unique_ids, nested): # recursively add the nested mosaic rows, cols = nested_mosaic.shape nested_output = _do_layout( - gs[j, k].subgridspec(rows, cols, **gridspec_kw), + gs[j, k].subgridspec(rows, cols, **nested_gs_kw), nested_mosaic, *_identify_keys_and_nested(nested_mosaic) ) From 666ab555b670e4ef01fd0ef24f6fbd4b9f87a770 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 15:28:26 +0100 Subject: [PATCH 02/16] Add test case for width_ratios --- lib/matplotlib/tests/test_figure.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py index 48b4a880e089..576aad1fb6b6 100644 --- a/lib/matplotlib/tests/test_figure.py +++ b/lib/matplotlib/tests/test_figure.py @@ -922,6 +922,16 @@ def test_nested_tuple(self, fig_test, fig_ref): fig_ref.subplot_mosaic([["F"], [x]]) fig_test.subplot_mosaic([["F"], [xt]]) + def test_nested_width_ratios(self): + x = [["A", [["B"], + ["C"]]]] + width_ratios = [2, 1] + + fig, axd = plt.subplot_mosaic(x, width_ratios=width_ratios) + + assert axd["A"].get_gridspec().get_width_ratios() == width_ratios + assert axd["B"].get_gridspec().get_width_ratios() != width_ratios + @check_figures_equal(extensions=["png"]) @pytest.mark.parametrize( "x, empty_sentinel", From 57a0a01ef976b14aebb69bd89f4b770d55c05ba7 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 15:30:21 +0100 Subject: [PATCH 03/16] Add test case for height_ratios --- lib/matplotlib/tests/test_figure.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py index 576aad1fb6b6..d15aaa37ae6f 100644 --- a/lib/matplotlib/tests/test_figure.py +++ b/lib/matplotlib/tests/test_figure.py @@ -932,6 +932,16 @@ def test_nested_width_ratios(self): assert axd["A"].get_gridspec().get_width_ratios() == width_ratios assert axd["B"].get_gridspec().get_width_ratios() != width_ratios + def test_nested_height_ratios(self): + x = [["A", [["B"], + ["C"]]], ["D", "D"]] + height_ratios = [1, 2] + + fig, axd = plt.subplot_mosaic(x, height_ratios=height_ratios) + + assert axd["D"].get_gridspec().get_height_ratios() == height_ratios + assert axd["B"].get_gridspec().get_height_ratios() != height_ratios + @check_figures_equal(extensions=["png"]) @pytest.mark.parametrize( "x, empty_sentinel", From e23ebe348e5a27e997daf1d80b3510acf3fe494b Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 15:44:39 +0100 Subject: [PATCH 04/16] Add behaviour change file --- doc/api/next_api_changes/behavior/24188-JB.rst | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 doc/api/next_api_changes/behavior/24188-JB.rst diff --git a/doc/api/next_api_changes/behavior/24188-JB.rst b/doc/api/next_api_changes/behavior/24188-JB.rst new file mode 100644 index 000000000000..982cdccefc47 --- /dev/null +++ b/doc/api/next_api_changes/behavior/24188-JB.rst @@ -0,0 +1,9 @@ +`fig.subplot_mosaic` no longer passes the `width_ratios` or `height_ratios` args to the nested gridspecs. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Previously, the entirety of the `gridspec_kw` dictionary was passed to +the nested gridspecs. This caused an error if the inner layout was +incompatible with one of these ratios. A new dictionary is now made, +`nested_gs_kw`, where the `"width_ratios"` and `"height_ratios"` keys +have been removed, which is passed to any nested gridspecs. This +prevents such errors. From 56b629dd83495cf0d4b67cd5287b919b073d37e0 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 16:11:44 +0100 Subject: [PATCH 05/16] Double backticks in rst --- doc/api/next_api_changes/behavior/24188-JB.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24188-JB.rst b/doc/api/next_api_changes/behavior/24188-JB.rst index 982cdccefc47..c9013392053f 100644 --- a/doc/api/next_api_changes/behavior/24188-JB.rst +++ b/doc/api/next_api_changes/behavior/24188-JB.rst @@ -1,9 +1,9 @@ -`fig.subplot_mosaic` no longer passes the `width_ratios` or `height_ratios` args to the nested gridspecs. +``fig.subplot_mosaic`` no longer passes the ``width_ratios`` or ``height_ratios`` args to the nested gridspecs. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Previously, the entirety of the `gridspec_kw` dictionary was passed to -the nested gridspecs. This caused an error if the inner layout was +Previously, the entirety of the ``gridspec_kw`` dictionary was passed +to the nested gridspecs. This caused an error if the inner layout was incompatible with one of these ratios. A new dictionary is now made, -`nested_gs_kw`, where the `"width_ratios"` and `"height_ratios"` keys -have been removed, which is passed to any nested gridspecs. This +``nested_gs_kw``, where the ``"width_ratios"`` and ``"height_ratios"`` +keys have been removed, which is passed to any nested gridspecs. This prevents such errors. From 779caae1e2850e6ee224a9fa3c5fcf3b6c86ebaf Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 16:18:45 +0100 Subject: [PATCH 06/16] Rename to suit new PR --- doc/api/next_api_changes/behavior/{24188-JB.rst => 24189-JB.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename doc/api/next_api_changes/behavior/{24188-JB.rst => 24189-JB.rst} (100%) diff --git a/doc/api/next_api_changes/behavior/24188-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst similarity index 100% rename from doc/api/next_api_changes/behavior/24188-JB.rst rename to doc/api/next_api_changes/behavior/24189-JB.rst From 26cb4a45976a3f56da8b3099d620442a5582c551 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Sun, 16 Oct 2022 17:09:04 +0100 Subject: [PATCH 07/16] Fix doc build warning (underline too short) --- doc/api/next_api_changes/behavior/24189-JB.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index c9013392053f..d0a229a5d0ab 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -1,5 +1,5 @@ ``fig.subplot_mosaic`` no longer passes the ``width_ratios`` or ``height_ratios`` args to the nested gridspecs. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Previously, the entirety of the ``gridspec_kw`` dictionary was passed to the nested gridspecs. This caused an error if the inner layout was From 36d18ab33b57dc5b64c314102aa37b4c9d34d2b2 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Mon, 17 Oct 2022 17:24:59 +0100 Subject: [PATCH 08/16] Completely disable passing of gridspec_kw to inner layouts --- doc/api/next_api_changes/behavior/24189-JB.rst | 17 +++++++++-------- lib/matplotlib/figure.py | 9 +++++---- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index d0a229a5d0ab..e73cc82954dc 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -1,9 +1,10 @@ -``fig.subplot_mosaic`` no longer passes the ``width_ratios`` or ``height_ratios`` args to the nested gridspecs. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to the nested gridspecs. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Previously, the entirety of the ``gridspec_kw`` dictionary was passed -to the nested gridspecs. This caused an error if the inner layout was -incompatible with one of these ratios. A new dictionary is now made, -``nested_gs_kw``, where the ``"width_ratios"`` and ``"height_ratios"`` -keys have been removed, which is passed to any nested gridspecs. This -prevents such errors. +Previously, the ``gridspec_kw`` dictionary was passed to the nested +gridspecs, as well as the outer gridspec. This caused errors with many +options, such as the ``"width_ratios"`` and ``"height_ratios"`` +options if the inner layout was incompatible with either of these +ratios. This dictionary is no longer passed to the inner layouts, and +users are directed by the docstring to construct the layout manually +if the inner layouts require any of these args. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index e7042de249eb..28cfa465aaec 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1856,9 +1856,10 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, gridspec_kw : dict, optional Dictionary with keywords passed to the `.GridSpec` constructor used - to create the grid the subplots are placed on. The 'width_ratios' - and 'height_ratios' keys, if present, will be removed from this - dictionary before it is passed to any inner layouts. + to create the grid the subplots are placed on. This argument + applies only to the outer layout and will not be passed to the + inner layouts. For more complex layouts, one should use + `.subfigure` and `.subplots` directly. empty_sentinel : object, optional Entry in the layout to mean "leave this space empty". Defaults @@ -2035,7 +2036,7 @@ def _do_layout(gs, mosaic, unique_ids, nested): # recursively add the nested mosaic rows, cols = nested_mosaic.shape nested_output = _do_layout( - gs[j, k].subgridspec(rows, cols, **nested_gs_kw), + gs[j, k].subgridspec(rows, cols), nested_mosaic, *_identify_keys_and_nested(nested_mosaic) ) From e4e83d4c862f1769d8d0732b5e80c0c9b3edad22 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Mon, 17 Oct 2022 17:27:48 +0100 Subject: [PATCH 09/16] Remove the new, now unneeded, nested_gw_kw dict --- lib/matplotlib/figure.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 28cfa465aaec..ca8d68999ba6 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2006,13 +2006,6 @@ def _do_layout(gs, mosaic, unique_ids, nested): for (j, k), nested_mosaic in nested.items(): this_level[(j, k)] = (None, nested_mosaic, 'nested') - # must remove these two options from the kwargs passed to the - # nested items, otherwise an error occurs if *any* of the inner - # layouts are not compatible with these ratios - nested_gs_kw = dict([(k, v) for k, v in gridspec_kw.items() - if k != "width_ratios" - and k != "height_ratios"]) - # now go through the things in this level and add them # in order left-to-right top-to-bottom for key in sorted(this_level): From acf1d2626403952b747e0d5f2def7a7254e5b5de Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Wed, 19 Oct 2022 16:49:53 +0100 Subject: [PATCH 10/16] Apply doc(string) suggestions from code review Co-authored-by: Jody Klymak --- doc/api/next_api_changes/behavior/24189-JB.rst | 2 +- lib/matplotlib/figure.py | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index e73cc82954dc..7c23bdcd619e 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -1,4 +1,4 @@ -``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to the nested gridspecs. +``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to nested gridspecs. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Previously, the ``gridspec_kw`` dictionary was passed to the nested diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index ca8d68999ba6..87d0f32695f6 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1839,16 +1839,14 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, relative width of ``width_ratios[i] / sum(width_ratios)``. If not given, all columns will have the same width. Equivalent to ``gridspec_kw={'width_ratios': [...]}``. This argument applies - only to the outer layout and will not be passed to the inner - layout. + only to the outer layout. height_ratios : array-like of length *nrows*, optional Defines the relative heights of the rows. Each row gets a relative height of ``height_ratios[i] / sum(height_ratios)``. If not given, all rows will have the same height. Equivalent to ``gridspec_kw={'height_ratios': [...]}``. This argument - applies only to the outer layout and will not be passed to the - inner layout. + applies only to the outer layout. subplot_kw : dict, optional Dictionary with keywords passed to the `.Figure.add_subplot` call From e584e8f1de310f2f39986d85e2a665789a1a562e Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Wed, 19 Oct 2022 16:52:29 +0100 Subject: [PATCH 11/16] Shorter api change explanation --- doc/api/next_api_changes/behavior/24189-JB.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index 7c23bdcd619e..b72b51e8bef5 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -1,10 +1,9 @@ ``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to nested gridspecs. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Previously, the ``gridspec_kw`` dictionary was passed to the nested -gridspecs, as well as the outer gridspec. This caused errors with many -options, such as the ``"width_ratios"`` and ``"height_ratios"`` -options if the inner layout was incompatible with either of these -ratios. This dictionary is no longer passed to the inner layouts, and -users are directed by the docstring to construct the layout manually -if the inner layouts require any of these args. +For nested `.Figure.subplot_mosaic` layouts, *gridspec_kw* arguments +are not necessarily compatible between nest levels. This dictionary +is no longer passed to the inner layouts. Users who need to modify +*gridspec_kw* at multiple levels should use `.Figure.subfigure` to get +nesting, and construct the inner layouts with `.Figure.subplots` or +`.Figure.subplot_mosaic`. From 2a3e919ec5e4df523fee93f2294818d77b38acdb Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Wed, 19 Oct 2022 16:54:54 +0100 Subject: [PATCH 12/16] Shorter gridspec_kw docstring --- lib/matplotlib/figure.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 87d0f32695f6..4490551e1c94 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1855,9 +1855,8 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, gridspec_kw : dict, optional Dictionary with keywords passed to the `.GridSpec` constructor used to create the grid the subplots are placed on. This argument - applies only to the outer layout and will not be passed to the - inner layouts. For more complex layouts, one should use - `.subfigure` and `.subplots` directly. + applies only to the outer layout. For more complex layouts, users + should use `.subfigure` to create the nesting. empty_sentinel : object, optional Entry in the layout to mean "leave this space empty". Defaults From a0f8cd9ee4e95092c07f4e21d001f17bf01e971a Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Wed, 19 Oct 2022 21:29:03 +0100 Subject: [PATCH 13/16] Correction of function names in docstrings --- doc/api/next_api_changes/behavior/24189-JB.rst | 2 +- lib/matplotlib/figure.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index b72b51e8bef5..9de395a55f6d 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -4,6 +4,6 @@ For nested `.Figure.subplot_mosaic` layouts, *gridspec_kw* arguments are not necessarily compatible between nest levels. This dictionary is no longer passed to the inner layouts. Users who need to modify -*gridspec_kw* at multiple levels should use `.Figure.subfigure` to get +*gridspec_kw* at multiple levels should use `.Figure.subfigures` to get nesting, and construct the inner layouts with `.Figure.subplots` or `.Figure.subplot_mosaic`. diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 4490551e1c94..e426c53ad98e 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1856,7 +1856,7 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, Dictionary with keywords passed to the `.GridSpec` constructor used to create the grid the subplots are placed on. This argument applies only to the outer layout. For more complex layouts, users - should use `.subfigure` to create the nesting. + should use `.Figure.subfigures` to create the nesting. empty_sentinel : object, optional Entry in the layout to mean "leave this space empty". Defaults From ecf1aefdaa9886d41d4f68fbdfec05efd84ec31e Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Thu, 20 Oct 2022 18:40:17 +0100 Subject: [PATCH 14/16] Modify behaviour msg to clarify the reasoning behind the change --- doc/api/next_api_changes/behavior/24189-JB.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/api/next_api_changes/behavior/24189-JB.rst b/doc/api/next_api_changes/behavior/24189-JB.rst index 9de395a55f6d..378390557f49 100644 --- a/doc/api/next_api_changes/behavior/24189-JB.rst +++ b/doc/api/next_api_changes/behavior/24189-JB.rst @@ -1,9 +1,10 @@ ``fig.subplot_mosaic`` no longer passes the ``gridspec_kw`` args to nested gridspecs. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For nested `.Figure.subplot_mosaic` layouts, *gridspec_kw* arguments -are not necessarily compatible between nest levels. This dictionary -is no longer passed to the inner layouts. Users who need to modify -*gridspec_kw* at multiple levels should use `.Figure.subfigures` to get -nesting, and construct the inner layouts with `.Figure.subplots` or -`.Figure.subplot_mosaic`. +For nested `.Figure.subplot_mosaic` layouts, it is almost always +inappropriate for *gridspec_kw* arguments to be passed to lower nest +levels, and these arguments are incompatible with the lower levels in +many cases. This dictionary is no longer passed to the inner +layouts. Users who need to modify *gridspec_kw* at multiple levels +should use `.Figure.subfigures` to get nesting, and construct the +inner layouts with `.Figure.subplots` or `.Figure.subplot_mosaic`. From cb9b48bf451ac7cc5fecbca7886bcdb248dbb9d5 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Fri, 21 Oct 2022 13:30:30 +0100 Subject: [PATCH 15/16] Clarify context of nested layouts in docstrings Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> --- lib/matplotlib/figure.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index e426c53ad98e..a088dc80aea2 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1838,15 +1838,15 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, Defines the relative widths of the columns. Each column gets a relative width of ``width_ratios[i] / sum(width_ratios)``. If not given, all columns will have the same width. Equivalent - to ``gridspec_kw={'width_ratios': [...]}``. This argument applies - only to the outer layout. + to ``gridspec_kw={'width_ratios': [...]}``. In the case of nested + layouts, this argument applies only to the outer layout. height_ratios : array-like of length *nrows*, optional Defines the relative heights of the rows. Each row gets a relative height of ``height_ratios[i] / sum(height_ratios)``. If not given, all rows will have the same height. Equivalent - to ``gridspec_kw={'height_ratios': [...]}``. This argument - applies only to the outer layout. + to ``gridspec_kw={'height_ratios': [...]}``. In the case of nested + layouts, this argument applies only to the outer layout. subplot_kw : dict, optional Dictionary with keywords passed to the `.Figure.add_subplot` call @@ -1854,9 +1854,10 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, gridspec_kw : dict, optional Dictionary with keywords passed to the `.GridSpec` constructor used - to create the grid the subplots are placed on. This argument - applies only to the outer layout. For more complex layouts, users - should use `.Figure.subfigures` to create the nesting. + to create the grid the subplots are placed on. In the case of + nested layouts, this argument applies only to the outer layout. + For more complex layouts, users should use `.Figure.subfigures` + to create the nesting. empty_sentinel : object, optional Entry in the layout to mean "leave this space empty". Defaults From b4307f7d132d283a0ad518a35c92f05afd177173 Mon Sep 17 00:00:00 2001 From: Joshua Barrass Date: Fri, 21 Oct 2022 14:11:06 +0100 Subject: [PATCH 16/16] Remove trailing whitespace --- lib/matplotlib/figure.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index a088dc80aea2..734dd36c2792 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1855,7 +1855,7 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, gridspec_kw : dict, optional Dictionary with keywords passed to the `.GridSpec` constructor used to create the grid the subplots are placed on. In the case of - nested layouts, this argument applies only to the outer layout. + nested layouts, this argument applies only to the outer layout. For more complex layouts, users should use `.Figure.subfigures` to create the nesting.