3 ƽh@sdZddlZddlZddlmZddlZddlZddlm Z m Z m Z m Z ddl mZddljZejeZGdddZGdd d eZGd d d eZGd d d ZdS)aa :mod:`~matplotlib.gridspec` contains classes that help to layout multiple `~.axes.Axes` in a grid-like pattern within a figure. The `GridSpec` specifies the overall grid structure. Individual cells within the grid are referenced by `SubplotSpec`\s. See the tutorial :ref:`sphx_glr_tutorials_intermediate_gridspec.py` for a comprehensive usage guide. N)Integral)_pylab_helperscbook tight_layoutrcParams)Bboxc@seZdZdZd%ddZddZeddd d Zed dd d Zd dZ d&ddZ d'ddZ ddZ ddZ ddZddZd(ddZdd Zddd!dd"d#d$ZdS)) GridSpecBasezm A base class of GridSpec that specifies the geometry of the grid that a subplot will be placed. NcCsjt|t s|dkr"td|t|t s6|dkrDtd||||_|_|j||j|dS)a Parameters ---------- nrows, ncols : int The number of rows and columns of the grid. width_ratios : array-like of length *ncols*, optional 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. height_ratios : array-like of length *nrows*, optional Defines the relative heights of the rows. Each column gets a relative height of ``height_ratios[i] / sum(height_ratios)``. If not given, all rows will have the same height. rz/Number of rows must be a positive integer, not z2Number of columns must be a positive integer, not N) isinstancer ValueError_nrows_ncolsset_height_ratiosset_width_ratios)selfnrowsncols height_ratios width_ratiosr9/tmp/pip-build-7iwl8md4/matplotlib/matplotlib/gridspec.py__init__ s   zGridSpecBase.__init__cCsR|jdk rd|jfnd}|jdk r0d|jfnd}dj|jj|j|j||dS)Nz, height_ratios=%rz, width_ratios=%rz&{clsname}({nrows}, {ncols}{optionals}))Zclsnamerr optionals)_row_height_ratios_col_width_ratiosformat __class____name__r r )rZ height_argZ width_argrrr__repr__9szGridSpecBase.__repr__cCs|jS)N)r )rrrrEszGridSpecBase.zThe number of rows in the grid.)doccCs|jS)N)r )rrrrrGsz"The number of columns in the grid.cCs |j|jfS)zW Return a tuple containing the number of rows and columns in the grid. )r r )rrrr get_geometryJszGridSpecBase.get_geometrycCsdS)Nr)rfigurerrrget_subplot_paramsPszGridSpecBase.get_subplot_paramscCs(|\}}|||||||f}|S)a[ Create and return a `.SubplotSpec` instance. Parameters ---------- loc : (int, int) The position of the subplot in the grid as ``(row_index, column_index)``. rowspan, colspan : int, default: 1 The number of rows and columns the subplot should span in the grid. r)rlocrowspancolspanZloc1loc2Z subplotspecrrrnew_subplotspecTs zGridSpecBase.new_subplotspeccCs(|dk rt||jkrtd||_dS)z Set the relative widths of the columns. *width_ratios* must be of length *ncols*. Each column gets a relative width of ``width_ratios[i] / sum(width_ratios)``. NzTExpected the given number of width ratios to match the number of columns of the grid)lenr r r)rrrrrrdszGridSpecBase.set_width_ratioscCs|jS)zo Return the width ratios. This is *None* if no width ratios have been set explicitly. )r)rrrrget_width_ratiospszGridSpecBase.get_width_ratioscCs(|dk rt||jkrtd||_dS)z Set the relative heights of the rows. *height_ratios* must be of length *nrows*. Each row gets a relative height of ``height_ratios[i] / sum(height_ratios)``. NzRExpected the given number of height ratios to match the number of rows of the grid)r*r r r)rrrrrr xszGridSpecBase.set_height_ratioscCs|jS)zq Return the height ratios. This is *None* if no height ratios have been set explicitly. )r)rrrrget_height_ratiosszGridSpecBase.get_height_ratiosFcs|j\}}|r*d}d}d}d}d} d} n.|j|} | j}| j}| j}| j}| j} | j} ||} ||} | || |d}| |}|jdk r||t |jfdd|jD}n |g|}dg|g|d}t j t j ||gj }| || |d}| |}|jdk r:||t |jfdd|jD}n |g|}dg|g|d}t j t j ||gj }||jd j\}}||jd j\}}||||fS)a Return the positions of the grid cells in figure coordinates. Parameters ---------- fig : `~matplotlib.figure.Figure` The figure the grid should be applied to. The subplot parameters (margins and spacing between subplots) are taken from *fig*. raw : bool, default: False If *True*, the subplot parameters of the figure are not taken into account. The grid spans the range [0, 1] in both directions without margins and there is no space between grid cells. This is used for constrained_layout. Returns ------- bottoms, tops, lefts, rights : array The bottom, top, left, right positions of the grid cells in figure coordinates. gg?r$Ncsg|] }|qSrr).0r)normrr sz3GridSpecBase.get_grid_positions..rcsg|] }|qSrr)r-r.)r/rrr0s)r2r1r2)r2r1)r!r#leftrightbottomtopwspacehspacersumnpZcumsumZ column_stackflatrZreshapeT)rZfigrawrrr3r4r5r6r7r8Zsubplot_paramsZ tot_widthZ tot_heightZcell_hZsep_hZ cell_heightsZ sep_heightsZcell_hsZcell_wZsep_wZ cell_widthsZ sep_widthsZcell_wsfig_tops fig_bottoms fig_lefts fig_rightsr)r/rget_grid_positionssH      zGridSpecBase.get_grid_positionsc Cs|j\}}dd}t|try |\}}Wn,tk rV}ztd|WYdd}~XnXtj|||d|||dg||f\}} n||||d\}} t||| S)z,Create and return a `.SubplotSpec` instance.cSs|}t|tr<|j|\}}}||kr2||dfStdnh|dkrL||}d|ko^|knrl||fS|dk rtd|d|d|ntd|d|dS)Nr$z=GridSpec slice would result in no space allocated for subplotrzindex z is out of bounds for axis z with size z) is out of bounds for GridSpec with size )r sliceindices IndexError)keysizeZaxisZorig_keystartstop_rrr _normalizes   z,GridSpecBase.__getitem__.._normalizezUnrecognized subplot specNrr$)r!r tupler r:Zravel_multi_index SubplotSpec) rrFrrrKZk1Zk2errnum1num2rrr __getitem__s   zGridSpecBase.__getitem__T)sharexshareysqueeze subplot_kwc Cs|j}|dkrtdt|tr,|r(dnd}t|trB|r>dnd}t|trVtjdtjddddg||d|dkrzi}|j}t j |j |j ft d }x~t|j D]p}xjt|j D]\}d|d||d f|d |fd } | ||d <| ||d <|j|||ff||||f<qWqW|dkrdx@|ddddfjD]&} | jjdddd| jjjdq:W|dkrx@|ddddfjD]&} | jjdddd| jjjdqW|r|jdkr|jS|jS|SdS)aQ Add all subplots specified by this `GridSpec` to its parent figure. This utility wrapper makes it convenient to create common layouts of subplots in a single call. Parameters ---------- sharex, sharey : bool or {'none', 'all', 'row', 'col'}, default: False Controls sharing of properties among x (*sharex*) or y (*sharey*) axes: - True or 'all': x- or y-axis will be shared among all subplots. - False or 'none': each subplot x- or y-axis will be independent. - 'row': each subplot row will share an x- or y-axis. - 'col': each subplot column will share an x- or y-axis. When subplots have a shared x-axis along a column, only the x tick labels of the bottom subplot are created. Similarly, when subplots have a shared y-axis along a row, only the y tick labels of the first column subplot are created. To later turn other subplots' ticklabels on, use `~matplotlib.axes.Axes.tick_params`. squeeze : bool, optional, default: True - If True, extra dimensions are squeezed out from the returned array of Axes: - if only one subplot is constructed (nrows=ncols=1), the resulting single Axes object is returned as a scalar. - for Nx1 or 1xM subplots, the returned object is a 1D numpy object array of Axes objects. - for NxM, subplots with N>1 and M>1 are returned as a 2D array. - If False, no squeezing at all is done: the returned Axes object is always a 2D array containing Axes instances, even if it ends up being 1x1. subplot_kw : dict, optional Dict with keywords passed to the `~.Figure.add_subplot` call used to create each subplot. Returns ------- ax : `~.axes.Axes` object or array of Axes objects. *ax* can be either a single `~matplotlib.axes.Axes` object or an array of Axes objects if more than one subplot was created. The dimensions of the resulting array can be controlled with the squeeze keyword, see above. See Also -------- .pyplot.subplots .Figure.add_subplot .pyplot.subplot NzIGridSpec.subplots() only works for GridSpecs created with a parent figureallnonez]sharex argument to subplots() was an integer. Did you intend to use subplot() (without 's')?rowcol)rRrS)Zdtyper)rWrVrXrYrRrSr$ZbothF)whichZ labelbottomZlabeltop)rZZ labelleftZ labelright)rr)rYrVr2)rXrV)r"r r boolrr_warn_externalZ_check_in_listcopyr:emptyr r objectrangeZ add_subplotr;ZxaxisZset_tick_paramsZ offsetTextZ set_visibleZyaxisrGitemrT) rrRrSrTrUr"ZaxarrrXrYZ shared_withaxrrrsubplotssJ:        "    zGridSpecBase.subplots)NN)N)r$r$)F)r __module__ __qualname____doc__rrpropertyrrr!r#r)rr+r r,rBrQrcrrrrrs$       C%rc @sVeZdZdZdddZddddd d gZd d Zd dZdddZddZ dddZ dS)GridSpecz A grid layout to place subplots within a figure. The location of the grid cells is determined in a similar way to `~.figure.SubplotParams` using *left*, *right*, *top*, *bottom*, *wspace* and *hspace*. Nc Cs||_||_||_||_||_| |_||_tj|||| | d|jdksT|jj r\d|_ n(|jj t j |jj dt j|d|_ dS)a Parameters ---------- nrows, ncols : int The number of rows and columns of the grid. figure : `~.figure.Figure`, optional Only used for constrained layout to create a proper layoutbox. left, right, top, bottom : float, optional Extent of the subplots as a fraction of figure width or height. Left cannot be larger than right, and bottom cannot be larger than top. If not given, the values will be inferred from a figure or rcParams at draw time. See also `GridSpec.get_subplot_params`. wspace : float, optional The amount of width reserved for space between subplots, expressed as a fraction of the average axis width. If not given, the values will be inferred from a figure or rcParams when necessary. See also `GridSpec.get_subplot_params`. hspace : float, optional The amount of height reserved for space between subplots, expressed as a fraction of the average axis height. If not given, the values will be inferred from a figure or rcParams when necessary. See also `GridSpec.get_subplot_params`. width_ratios : array-like of length *ncols*, optional 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. height_ratios : array-like of length *nrows*, optional Defines the relative heights of the rows. Each column gets a relative height of ``height_ratios[i] / sum(height_ratios)``. If not given, all rows will have the same height. )rrNgridspec)parentnameartist)r3r5r4r6r7r8r"rrZget_constrained_layout _layoutboxZinit_layoutbox layoutbox LayoutBoxseq_id) rrrr"r3r5r4r6r7r8rrrrrrrs"*   zGridSpec.__init__r3r5r4r6r7r8cCs|jddiS)Nrm)__dict__)rrrr __getstate__szGridSpec.__getstate__cKsx:|jD].\}}||jkr*t|||q t|dq WxtjjjD]}x|jj j D]}t |t j j st |jt j j r|jjj|kr|jj|j|jjn:t |jt j j r|jjj|kr|jj|j|jjqZ|jj}|j|krZ|j|j|jqZWqJWdS)a  Update the subplot parameters of the grid. Parameters that are not explicitly given are not changed. Setting a parameter to *None* resets it to :rc:`figure.subplot.*`. Parameters ---------- left, right, top, bottom : float or None, optional Extent of the subplots as a fraction of figure width or height. wspace, hspace : float, optional Spacing between the subplots as a fraction of the average subplot width / height. z is an unknown keywordN)items _AllowedKeyssetattrAttributeErrorrZGcfZfigsvaluesZcanvasr"axesr mplZ SubplotBaseZ_sharexZget_subplotspec get_gridspecZ update_paramsZ _set_positionfigboxZ_shareyget_topmost_subplotspec)rkwargskvZ figmanagerrbssrrrupdates&     zGridSpec.updatecsT|dkr(ddjD}tjjf|}n tj|j}|jffddjD|S)z Return the `~.SubplotParams` for the GridSpec. In order of precedence the values are taken from - non-*None* attributes of the GridSpec - the provided *figure* - :rc:`figure.subplot.*` NcSsi|]}td||qS)zfigure.subplot.)r)r-r~rrr sz/GridSpec.get_subplot_params..csi|]}t||qSr)getattr)r-r~)rrrrs)rtryr" SubplotParamsr] subplotparsr)rr"kwrr)rrr#s  zGridSpec.get_subplot_paramscsfddjDS)z Return a list of the names of the subplot parameters explicitly set in the GridSpec. This is a subset of the attributes of `.SubplotParams`. csg|]}t|r|qSr)r)r-r~)rrrr0sz.)rt)rr)rrlocally_modified_subplot_paramssz(GridSpec.locally_modified_subplot_paramsHzG?c Csdtj|j|d}d|kr"tjd|dkr4tj|}tj||j||||||d}|r`|jf|dS)ay Adjust subplot parameters to give specified padding. Parameters ---------- pad : float Padding between the figure edge and the edges of subplots, as a fraction of the font-size. h_pad, w_pad : float, optional Padding (height/width) between edges of adjacent subplots. Defaults to *pad*. rect : tuple of 4 floats, default: (0, 0, 1, 1), i.e. the whole figure (left, bottom, right, top) rectangle in normalized figure coordinates that the whole subplots area (including labels) will fit into. )Z grid_specNzcThis figure includes Axes that are not compatible with tight_layout, so results might be incorrect.)padh_padw_padrect)rZget_subplotspec_listrxrr\Z get_rendererZget_tight_layout_figurer) rr"ZrendererrrrrZsubplotspec_listr}rrrrs    zGridSpec.tight_layout) NNNNNNNNN)N)NrNNN) rrdrerfrrtrrrr#rrrrrrrhjs ?'  rhc@s,eZdZdZd ddZd ddZddZdS) GridSpecFromSubplotSpeczx GridSpec whose subplot layout parameters are inherited from the location specified by a given SubplotSpec. Nc Csn||_||_||_|jjj|_tj|||||d|j}|dkrJd|_n |j||j dt j |d|_dS)a` The number of rows and number of columns of the grid need to be set. An instance of SubplotSpec is also needed to be set from which the layout parameters will be inherited. The wspace and hspace of the layout can be optionally specified or the default values (from the figure or rcParams) will be used. )rrNz .gridspec)rkrl) _wspace_hspace _subplot_specrzr"rrrmZlayout_from_subplotspecrkrnrp) rrrZ subplot_specr7r8rrZ subspeclbrrrr&s  z GridSpecFromSubplotSpec.__init__c Cs|jdk r|jn|dk r |jjntd}|jdk r8|jn|dk rH|jjntd}|jj|}|j\}}}}t j j ||||||dS)z1Return a dictionary of subplot layout parameters.Nzfigure.subplot.hspacezfigure.subplot.wspace)r3r4r5r6r7r8) rrr8rrr7r get_positionZextentsryr"r) rr"r8r7r{r3r5r4r6rrrr#Cs  z*GridSpecFromSubplotSpec.get_subplot_paramscCs |jjS)zY Return the topmost `.SubplotSpec` instance associated with the subplot. )rr|)rrrrr|Ssz/GridSpecFromSubplotSpec.get_topmost_subplotspec)NNNN)N)rrdrerfrr#r|rrrrr!s   rc@seZdZdZd&ddZddZeddZed d Z e j d d Z d d Z ddZ ddZ ejdddddZeddZeddZd'ddZddZd d!Zd"d#Zd$d%ZdS)(rMaX Specifies the location of a subplot in a `GridSpec`. .. note:: Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you will typically obtain one from a `GridSpec` using item-access. Parameters ---------- gridspec : `~matplotlib.gridspec.GridSpec` The GridSpec, which the subplot is referencing. num1, num2 : int The subplot will occupy the num1-th cell of the given gridspec. If num2 is provided, the subplot will span between num1-th cell and num2-th cell *inclusive*. The index starts from 0. NcCsN||_||_||_|jdk rD|j}tj||jdtj|d|_nd|_dS)Nz.ss)rjrkrl) _gridspecrOrPrmrnrorkrp)rrirOrPZglbrrrrns  zSubplotSpec.__init__c Cs6|jd|jjd|jjd|jjd|jjd S)N[:z, ])rzr&rHrIr')rrrrrszSubplotSpec.__repr__c Csd}t|dkr|\}t|tr$|St|tsDtjd|dt|}yttt|\}}}Wn$t k rt d|dYnXt |||d|dSn2t|dkr|\}}}t|tot|tstjd|dtt||g\}}t |||d}t|t rZt|d krZt d d |DsBtjd|dtt|\}} n|\}} ||d| St|ts|tjd|dt|}|dks|||krt d ||d |||dSnt dt|ddS)z Construct a `.SubplotSpec` from a parent `.Figure` and either - a `.SubplotSpec` -- returned as is; - one or three numbers -- a MATLAB-style subplot specifier. z{Passing non-integers as three-element position specification is deprecated since %(since)s and will be removed %(removal)s.r$z3.3)messagez>Single argument to subplot must be a three-digit integer, not N)r"r1css|]}t|tVqdS)N)r r)r-nrrr sz1SubplotSpec._from_subplot_args..znum must be 1 <= num <= z, not z0subplot() takes 1 or 3 positional arguments but z were given)r*r rMrrwarn_deprecatedstrmapintr rhrLrV TypeError) r"argsrargrowscolsnumZgsijrrr_from_subplot_argssF       zSubplotSpec._from_subplot_argscCs|jdkr|jS|jS)N)_num2rO)rrrrrPszSubplotSpec.num2cCs ||_dS)N)r)rvaluerrrrPscCs|jddiS)Nrm)rq)rrrrrrszSubplotSpec.__getstate__cCs|jS)N)r)rrrrrzszSubplotSpec.get_gridspeccCs |jj\}}|||j|jfS)a Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``. The indices *start* and *stop* define the range of the subplot within the `GridSpec`. *stop* is inclusive (i.e. for a single cell ``start == stop``). )rzr!rOrP)rrrrrrr!szSubplotSpec.get_geometryz3.3zrowspan, colspan) alternativecCsD|j}|j\}}t|j|\}}t|j|\}}||||||fS)z Return the subplot row and column numbers as a tuple ``(n_rows, n_cols, row_start, row_stop, col_start, col_stop)``. )rzr!divmodrOrP)rrirrZ row_startZ col_startZrow_stopZcol_stoprrrget_rows_columnss  zSubplotSpec.get_rows_columnscCs$|jj}t|j||j|dS)z6The rows spanned by this subplot, as a `range` object.r$)rzrr`rOrP)rrrrrr&s zSubplotSpec.rowspancCs4|jj}t|j||j|g\}}t||dS)z9The columns spanned by this subplot, as a `range` object.r$)rzrsortedrOrPr`)rrZc1c2rrrr's zSubplotSpec.colspanFcCs|j}|j\}}tj|j|jg||f\}}|j|\}} } } ||j} | |j} | |j}| |j}t j || || }|r||d|d||fS|SdS)zJ Update the subplot position from ``figure.subplotpars``. rN) rzr!r:Z unravel_indexrOrPrBminmaxrZ from_extents)rr"Z return_allrirrrrr?r>r@rAZ fig_bottomZfig_topZfig_leftZ fig_rightr{rrrrs     zSubplotSpec.get_positioncCs"|j}t|dr|jS|SdS)zX Return the topmost `SubplotSpec` instance associated with the subplot. r|N)rzhasattrr|)rrirrrr|s z#SubplotSpec.get_topmost_subplotspeccCs8|j|j|jft|dtt|dtt|dtfkS)z} Two SubplotSpecs are considered equal if they refer to the same position(s) in the same `GridSpec`. rrOrP)rrOrPrr_)rotherrrr__eq__s  zSubplotSpec.__eq__cCst|j|j|jfS)N)hashrrOrP)rrrr__hash__szSubplotSpec.__hash__cKst|||f|S)a Create a GridSpec within this subplot. The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as a parent. Parameters ---------- nrows : int Number of rows in grid. ncols : int Number or columns in grid. Returns ------- `.GridSpecFromSubplotSpec` Other Parameters ---------------- **kwargs All other parameters are passed to `.GridSpecFromSubplotSpec`. See Also -------- matplotlib.pyplot.subplots Examples -------- Adding three subplots in the space occupied by a single subplot:: fig = plt.figure() gs0 = fig.add_gridspec(3, 1) ax1 = fig.add_subplot(gs0[0]) ax2 = fig.add_subplot(gs0[1]) gssub = gs0[2].subgridspec(1, 3) for i in range(3): fig.add_subplot(gssub[0, i]) )r)rrrr}rrr subgridspecs(zSubplotSpec.subgridspec)N)F)rrdrerfrr staticmethodrrgrPsetterrrrzr!rZ deprecatedrr&r'rr|rrrrrrrrMZs"  7      rM)rfr]loggingnumbersrnumpyr:Z matplotlibryrrrrZmatplotlib.transformsrZmatplotlib._layoutboxrmrn getLoggerr_logrrhrrMrrrr s     R89