3 hZj$@s<dZddlmZddlmZddlZddlZddlZddl Z ddl Z ddl jZddljZddlmZddlmZddlmZdd lmZdd lmZmZmZdd lm Z m!Z!dd l"m#Z#m$Z$m%Z%m&Z&m'Z'dd l(m)Z)ddl*m+Z+ddl,m-Z-ddl.m/Z/m0Z0ddddddgZ1e2dddddddZ3e/j4e0de/e!e/e3e/j5ej6e/j5ej6e/j5ej6dZ7Gd d!d!eZ8Gd"d#d#e8Z9dHddddd$d%dddd&d'd'd(d)d'dd&dddddd&dddddddd'dd* d+dZ:d,j;e7e0d-e0d.d/e:_e-dIddd&ddd0d1dd'd&dd&ddddddddd(d'd&d2d3d4ddddddd'd5!d6dZdZ>d?j;e7e0d-e0d.d/e>_dLddddddd@d&ddd'ddddddddAdddBdCdZ?dDj;e7e0d-e0d.d/e?_dEdFZ@dMdGdZAdS)Nz1Plotting functions for visualizing distributions.)Number)partialN)to_rgba)LineCollection)stats) VectorPlotter)KDE HistogramECDF) FacetGrid _facet_docs) remove_na _kde_support_normalize_kwargs_check_argument_assign_default_kwargs) color_palette)husl)_deprecate_positional_args)DocstringComponents _core_docsdisplothistplotkdeplotecdfplotrugplotdistplotz multiple : {{"layer", "stack", "fill"}} Method for drawing multiple elements when semantic mapping creates subsets. Only relevant with univariate data. ao log_scale : bool or number, or pair of bools or numbers Set axis scale(s) to log. A single value sets the data axis for univariate distributions and both axes for bivariate distributions. A pair of values sets each axis independently. Numeric values are interpreted as the desired base (default 10). If `False`, defer to the existing Axes scale. zM legend : bool If False, suppress the legend for semantic variables. z cbar : bool If True, add a colorbar to annotate the color mapping in a bivariate plot. Note: Does not currently support plots with a ``hue`` variable well. zU cbar_ax : :class:`matplotlib.axes.Axes` Pre-existing axes for the colorbar. zd cbar_kws : dict Additional parameters passed to :meth:`matplotlib.figure.Figure.colorbar`. )multiple log_scalelegendcbarcbar_axcbar_kwsparams)corefacetsdistkdehistecdfcseZdZd.ZdddZddiZdiffd d Zed d Zed dZ eddZ ddZ ddZ ddZ ddZddZddZd/ddZd d!Zd"d#Zd$d%Zd&d'Zd(d)Zd*d+Zd,d-ZZS)0_DistributionPlotterxyhueweightsz@valuesz@columns)r,r.Ncstj||ddS)N)data variables)super__init__)selfr0r1) __class__8/tmp/pip-build-riy7u7_k/seaborn/seaborn/distributions.pyr3isz_DistributionPlotter.__init__cCstddht|jS)z$Return True if only x or y are used.r,r-)boolsetr1)r4r6r6r7 univariateqsz_DistributionPlotter.univariatecCs"|jstdddhj|jjS)z3Return the variable with data for univariate plots.zThis is not a univariate plotr,r-)r:AttributeError intersectionr1pop)r4r6r6r7 data_variablezsz"_DistributionPlotter.data_variablecCstddht|j@S)z.Return True at least one of x or y is defined.r,r-)r8r9r1)r4r6r6r7 has_xy_datasz _DistributionPlotter.has_xy_datac  Csg} g} xD|jjD]8} |j| } | j|f|j||||| || j| qWt|tjjr||j| | fd|j di|n2t t | | } |j | f|j d|j dd|dS)zDAdd artists that reflect semantic mappings and put then in a legend.titler.)r@Z label_orderN)_hue_maplevelsappend _artist_kws isinstancemplaxesZAxesr r1dictzipZ add_legend var_levels)r4ax_objartistfillelementralpha artist_kwsZ legend_kwsZhandleslabelslevelcolorZ legend_datar6r6r7 _add_legends    z _DistributionPlotter._add_legendcCs|j}|rV|jdt|||d ks.|dkrB|jdtjdq|jdt|dn.|dkrvd|d<t|||d<nt|||d <|S) zsz9_DistributionPlotter._cmap_from_color..r^gffffffr@)rgrhr^) rrZ rgb_to_huslr_linspaceintzeroscosr\rFcolorsZListedColormap) r4rSrgb_hsxxZramprrr6r6r7_cmap_from_colors z%_DistributionPlotter._cmap_from_colorcCs@|jr|j|jdk}n$|jddk}|jddk}||f}|S)zHFind default values for discrete hist estimation based on variable type.Z categoricalr,r-)r: var_typesr>)r4discreteZ discrete_xZ discrete_yr6r6r7_default_discretes z&_DistributionPlotter._default_discretecCsdd|jD}d|jkr$||fS|dkrdtj|jdddddf}i}xRttt|jj D]:\}}|j dd|j d df}|j |g||j |qfW|j }x|jD]}|jdd|fjd d } |jdd|fjd d |jdd|f<|dkr0|jdd|fj| d d |jdd|f<|jdd|fjddd jd |jdd|f<qW|dkr|jd} t| } xn|D]f} t| d} || jdd}|d| <|d| j| |d7<|jddgd|| <qW||fS)z?Modify the density data structure to handle multiple densities.cSsi|]\}}tj||qSr6)r_Z zeros_like)rlkvr6r6r7 sz:_DistributionPlotter._resolve_multiple..r.rVrMNrcolrowcolumns)axisindexrdodgeheights)namewidthsedges)rVrMr^)itemsr1pd DataFrameiloc enumeratemaprHrtolistgetrZrCrYrdrcrbdivshiftZfillnarJlen reset_indexrZ set_index)r4Zcurvesr baselinesZ column_groupsiZkeydZ facet_keycolsZ norm_constantZ hue_levelsnkeyrRr)r6r6r7_resolve_multiples@   (        z&_DistributionPlotter._resolve_multipleTcCstf|}|jj}t|jddhrD|rH|jj} |j| |nd}i} x|jdddD]\} } | j} | |} | j}t j |dst j |rd}|r\t j|tq\d |jkr| d }nd}|| |d \}}|rt jd |}|r|t| t|9}t| j}tj||d | |<q\W| S) Nr,r-Fr.T)from_comp_datarzfDataset has 0 variance; skipping density estimate. Pass `warn_singular=False` to disable this warning.r/)r/ )r)r plot_datadropnar9r1 comp_dataZdefine_support iter_datavarmathiscloser_isnanwarningswarn UserWarningpowerrtuplerrSeries)r4r> common_norm common_grid estimate_kwsr warn_singular estimatorall_dataall_observations densitiessub_varssub_data observationsZobservation_variancemsgr/densitysupportrr6r6r7_compute_univariate_densitys8        z0_DistributionPlotter._compute_univariate_densityc M Ks |dkr in|j}| dkr in| j} | dkr4in| j} tdddddg|tdddd g|| d rz|dkrztd d |jko| d dko| ddko| d  }|rd}tj|td| d <| ddkrd}tf| }i}t|jddhr&|j j }|r*||j }|j ||j d ddnd}|rl|jdd| d|d<|j|j }|j|j ||||dd}xP|jdddD]<\}}t|j}|j }||j }d |jkr|d }nd}|||d\}}|r||kr||}|jr|j}n|tj|j}|||9<|j|j r6tjd|}tj|}||} |dd=d|d |}tjjtj|d!d"tj| d#d"g}!tj||!d$d%}"|r|"t|t|9}"|"||<q~W|j ||\}}#|r|j ||dkrdn|\}}$|dkrd>ndtj!f}%|dkrP|j"j#}&|&d!}|&d#} |j$|j| j%|j&f}'ng}'d|jkr>|j'dkr| dkrzd&n| }(n|r|j(|j d'krd})| j)d(| }(|(dkrd&}(n|)j5|rd|jkrn|dkrn|dkrhd*nd+}+n|rzd*}+nd,}+nd}+| j)d-|+},g}-xx|jddd.D]d\}}$t|j}||j6d$j7}"tj8|#|}.|j9|}/d|jkr|j:|d} n|(} |j;| |||| |,}0|dkr|j dkr6|/jj?dd<|%|3j>j@dd<n |%|3j>j?dd<|'|3j>j@dd<qlW|-jA|2nv|dkrF|"jBd?}4tjC|"d!|4d!|4d#}5tjC|"d$|4d$}6tjC|.|.d@}7|j dkrj?dd<|%|*j>j@dd<n\|r|/jD|5|7|6fd|8i|0}*n|/j3|6|5fd4|9i|0\}*|%|*j>j?dd<|'|*j>j@dd<|-jC|*|ry ||}WntEk rtwYnX|j"}:d|jkr|:|f};ddtj!f}<}=n||:f};dtj!fd}<}=tF| d| d)<|/j3|;| \}>|j>j?dd<|=dk r|=|>j>j@dd<qW|dk rJd5| k rJtjGd6d7|jDj7dd8}?|?d#jH}@|?j%|@d#f}A|?j%|@d!f}BtIj!}Cx|jD]|\}}$|j9|}/|/jJd9|/jKjLtM|/jNjO|B|Agd |/jNjO|Bgd \}D}E|j dkr|D}Fn|E}Ft$d:|F|C}Cq|WxL|-D]D}3|3jP}G| s|Gd;9}Gt$|C|G}H| s:d*}It|H|I}H|3jQ|H qW|j'dk r\|j'n |jRjSjTd}/d<}J}K|j dk r|jUjV}K|j dk r|jUjV}J|jW|/|J|Kd|jk r| r| s|dk rtXt*j+jY}*ntXt*j1j2gg}*|j'dk r|j'n|jR}L|jZ|L|*||||,| idS)ANrlayerrVrMrrNrWsteppolyr|z0`element` must be 'bars' when `discrete` is Truer/binsautobinwidthzb`bins` cannot be 'auto' when using weights. Setting `bins=10`, but you will likely want to adjust.rstatcountFr,r-)r/cutr cumulative)rr.T)rrrkr)rrr)rrC0datetimerUrSg?g?g?rO)reverseZalignZedgepostz steps-postz steps-pre drawstyle linewidthcSsg|]\}}|jjqSr6)rto_frame)rlrvrwr6r6r7rmszB_DistributionPlotter.plot_univariate_histogram..)ZdropHg?g?r^)rrr^r^)[rYr ValueErrorr1rrrr r9rrr>define_bin_paramsrrZ _log_scaledrrrrrmaxr_ZdiffrcrrZ MultiIndexZ from_arraysIndexrrrinfrrminlocZidxmaxaxr{r=rFpatchesZ Rectangler fill_between get_facecolorsqueezelinesLine2Dplot get_colorremoverenamerr` _get_axesrArDbarZbarh sticky_edgesr,r-extendrrC fill_betweenxKeyErrorrconcatZidxminrautoscale_viewfigureZdpiabs transData transformZ get_linewidthZ set_linewidthr&rGflatr capitalize_add_axis_labelsrPatchrT)Mr4rrNrMr common_binsshrinkr(kde_kwsrSr line_kwsrplot_kwsZauto_bins_with_weightsrrZ histogramsrrrrrrrrr/rrrZ hist_normZ orig_widthsrrr)rrvZ sticky_statZbin_valsZ sticky_data default_colorscoutrL default_alpharOZ hist_artistsZbottomrrPZ plot_funcZartistsrfinalr,r-rurrrZ line_argsZsticky_xZsticky_ylineZ hist_metadataZ thin_bar_idxrZ left_edgeZdefault_linewidthZpts_xZpts_yZbinwidth_pointsZ max_linewidthrZ min_linewidth default_x default_yrKr6r6r7plot_univariate_histogramYs                                                             z._DistributionPlotter.plot_univariate_histogramc ! Ks| dkr in| j} tf| } t|jddhr^|jj}|rb| j|d|d|jddnd}g}xJ|jddD]:\}}|j}| |d|d|jdd\}}|j |qtWt|jddh p|}|dk r|r|j ||}| j dd|r&|dk r |j ||}n| j d t ttj |}nd}|dkr8d }xB|jd ddD].\}}|j}|jrhqJ| |d|d|jddd \}\}}|jdrtjd |}|jdrtjd |}| jdkr|r|t|t|9}| j}d |jkr|j|d }|j|}||d<nB|j dd}t|tr@t|dd}n|dkrT|j|}||d<| rz|dk rz|j ||}|dk r||d <| r|r|j ||}|dk rtjj||}|j|}tdd|jjD}tdd|j jD}|j!|||j"f|}|dk r6g|j#j$dd<g|j#j%dd<|rP|j&j'|| |f| |rd|j(ddd|rJ|j(dddqJW|j)dk r|j)n |j*j+j,d}|j-|d |jkr|ri}t.t/j0j1}|j)dk r|j)n|j*} |j2| |dddd|idS)Nr,r-r/FT)rZvminrvmaxrr.)r/rrcmap)as_cmapcSsg|] }|jqSr6) get_visible)rllr6r6r7rmNszA_DistributionPlotter.plot_bivariate_histogram..cSsg|] }|jqSr6)r)rlrr6r6r7rmOs)rrr)3rYr r9r1rrrrrrCrfrZr=rrr_emptyrrrrrArzrEstrrmaZmasked_less_equalranyZxaxisZ get_gridlinesZyaxisZ pcolormeshTrr,r-rcolorbarZgridrr&rGrrrrFrrrT)!r4rrthreshpthreshpmaxrSr r!r"r#rrrrZ full_heightsrvrZ sub_heightsZcommon_color_normrrrZx_edgesZy_edgesrPrrZx_gridZy_gridZmeshrLrKr6r6r7plot_bivariate_histograms                            z-_DistributionPlotter.plot_bivariate_histogramc Ks|dkr|dk}|rtjj} ntjj} t|| }tddddg|tt|j ddh} | rh|dkrhd}|j |j } |j |j |||| |} |j | |\} } |dkrdndtjf}|dkr| jj| jjf}ng}d |j kr|jdkr |jd d}|dkrd n|}n|rz|j|j d krJd}|jd |jdd}|dkrld }n"|jjggf|}t|jj}|jd dn|jjggf|\}|j}|dk r|j|jd d|r|dkrd}nd}nd }|jd|}xD|jd ddD]0\}}t|j}y | |}Wntk r.wYnX|j}| |}|j |}d |j krd|j!|d }n|}|j"||d|||}d|j kr|r|j|||f|} n|j||f|\} || j#j$dd<|| j#j%dd<nL|r|j&|||f|} n|j||f|\} || j#j$dd<|| j#j%dd<qW|jdk r:|jn |j'j(j)d}d}}|j dkr`d}|j dkrpd}|j*|||d |j kr|r|rt+tj,j-} nt+tjjgg} |jdk r|jn|j'}|j.|| |d|||idS)NrVrMrrr,r-Trrr.rSrrrUg?g?rO)rFrZDensity)rVrM)rVrM)rr)/rF collectionsZPolyCollectionrrrrr8r9r1rr>rrr_rrrrrr=r{rrrrrrrrrrrrArDrr,r-rr&rGrrrrrrT) r4rrrrrMr rrrLZsubsetsrrrZsticky_densityZsticky_supportrSrrrrOrrvrrrZ fill_fromrrPrrrKr6r6r7plot_univariate_density}s                      z,_DistributionPlotter.plot_univariate_densityc * s| j} tf| } tjddhs(d}jj}ii}}x$jdddD]\}}|j}|ddg}djkr|d}nd}|ddgj}tdd |Ds|j jrd }|rNt j |t qN|d|df}| |d|i\}}|\}}j dr tjd |}j dr"tjd |}||f}|rD|t|t|9}t|j}|||<|||<qNW|dkrrd }ttrtj|d n$td kstd krtd|rjt|jfdd|D}nfdd|jD}jdkr|dkrdn|}n"jjg|d\}|j}|jdjkrxdD]0}|| krL|d}t j |t | j |qLWnt| ddh@} |r| rj!|}!|!| d<| r| r|g| d<| j dd}!t|!t"rt#|!dd}!|!dk r|!| d<x jdD]\}}"d|krPj$|d}|rFj!|| d<n |g| d<j%|}#|rh|#j&}$n|#j'}$t|j}||krq||}||\}}| j dd}%|$|||fd||i| }&djkr|&j(d j)|%|r| dkrin| } |#j*j+|&| |#f| qWjdk r$jn j,j-j.d }#j/|#djkr|ri}'|rft0t1j2j3}(nt0t1j4j5gg}(jdk rjnj,})j6|)|(|ddd |'idS)Nr,r-Fr.T)rr/css|]}tj|dVqdS)rN)rr)rlr,r6r6r7 Lsz>_DistributionPlotter.plot_bivariate_density..zfDataset has 0 variance; skipping density estimate. Pass `warn_singular=False` to disable this warning.rrrzlevels must be in [0, 1]csi|] }|qSr6r6)rlr~) common_levelsr6r7rwsz?_DistributionPlotter.plot_bivariate_density..csi|]\}}j||qSr6)rf)rlr~d)rBr4r6r7rysr)rSrrrz* parameter ignored when using hue mapping.)rlabelrBr)rrr)7rYr r9r1rrrrrZisnarrrrr_rrrrrErrnrrrrflistrdrrrrr=rzrrrArZcontourfZcontourrZ set_labelrr r&rGrrrrFrrrrrT)*r4rrMrBr rSr r!rr"r#rZ contour_kwsrrrZsupportsrrrr/ZvariancerrrryyyrZ draw_levelsrrparamZcoloring_givenrrvrZ contour_funcrZcsetrPrLrKr6)rrBr4r7plot_bivariate_density"s                                        z+_DistributionPlotter.plot_bivariate_densityc Kstf|}tddd}||j|d<x |jddddD]\}}|j}|jrPq8||j}|jdd} ||| d \} } |j} d|jkr|j |d| d <|j |jrt j d | } t j | d <|jd kr| | f} d}n | | f} d }|jdkrt|}nd}|j|}|j| | \}t|j|}d |f|dd<q8W|jdk rD|jn |jjjd }|jj} d}}|jd krt| }|jdkr| }|j|||d|jkr|rttjjgg}|jdd}|jdk r|jn|j}|j||ddd||idS)Nz steps-postz steps-pre)r,r-rr.T)rrr/)r/rSrrr,r-rrrrOF)r rHr>rrrrrYr1rArr_rrrrrrgetattrrrr&rGrrrrrFrrrT)r4rr rrZ drawstylesrrrr/rvalsrPZ plot_argsZ stat_variableZtop_edgerrLrrrrOrKr6r6r7plot_univariate_ecdfsV                  z)_DistributionPlotter.plot_univariate_ecdfc Kszt|tjj}|jdkr*|jdd|d<n0|jjggf|\}|jd|j|d<|jx|j ddD]\}}|j |}|j dd|r|j \} } d|j kr| |d7} d |j kr| |d7} |j | | d d |j kr|jd d|jddd|j kr|j|d|||d |j kr2|j|d ||||j|d |j krj|rjttjjgg} |j|| d d ddiiqjWdS)NrSrT)rrrr,rkr-)r,r-r.cF)rrFrrrr=rrrrrrZZmarginsr1_plot_single_rugrrrT) r4heightexpand_marginsr r[rrrrZxmargZymargZ legend_artistr6r6r7plot_rug%s8              z_DistributionPlotter.plot_rugc Cs||}t|}|j|r&tjd|}d|jkr@|j|d}nd}|dkr~tj|j|j } tj tj |dtj d|g|g} |dkrtj|j |j} tj tj d|g|tj |dg} | j |ddg} |jt| f| |d||j|dk|dkd dS) z*Draw a rugplot along one axis of the plot.rr.Nr,rkrr-)rrr)ZscalexZscaley)rrr_rr1rAtxZblended_transform_factoryrZ transAxesZ column_stackrepeatZtileZreshapeZadd_collectionrr) r4rrrrr[ZvectorrrrZtransZxy_pairsZ line_segsr6r6r7rPs&   z%_DistributionPlotter._plot_single_rug)r,r-r.r/)T)__name__ __module__ __qualname__ semanticsZwide_structureZflat_structurer3propertyr:r>r?rTrDrfrzr}rrrr rrrrr __classcell__r6r6)r5r7r+bs8     H ;!&>F+r+c@seZdZejdZdS)_DistributionFacetPlotterrrN)rr)r"r#r$r+r%r6r6r6r7r(xsr(rrFTrrW) r,r-r.r/rrrbinranger|rrrrrNrMrr(rrr r r r!r"r#palette hue_orderhue_normrSrr rc $Kst|tjtd}"|"j|||d| dkr4tj} |"js>| S|"j| |d| dkr\|"j} t ||||| | d}#|"j r|"j f| |||| | |||||#|d |!n(|"j f| | |||||||||#d |!| S)N)r0r1)r*ordernorm)r)rrrr)r|r) rrNrMrrrr(rrSr rr) rrr r r rSr r!r"r#r) r+ get_semanticslocalsmap_huepltgcar?_attachr}rHr:rr )$r0r,r-r.r/rrrr)r|rrrrrNrMrr(rrr r r r!r"r#r*r+r,rSrr rkwargsprr6r6r7rs^ aMPlot univariate or bivariate histograms to show distributions of datasets. A histogram is a classic visualization tool that represents the distribution of one or more variables by counting the number of observations that fall within disrete bins. This function can normalize the statistic computed within each bin to estimate frequency, density or probability mass, and it can add a smooth curve obtained using a kernel density estimate, similar to :func:`kdeplot`. More information is provided in the :ref:`user guide `. Parameters ---------- {params.core.data} {params.core.xy} {params.core.hue} weights : vector or key in ``data`` If provided, weight the contribution of the corresponding data points towards the count in each bin by these factors. {params.hist.stat} {params.hist.bins} {params.hist.binwidth} {params.hist.binrange} discrete : bool If True, default to ``binwidth=1`` and draw the bars so that they are centered on their corresponding data points. This avoids "gaps" that may otherwise appear when using discrete (integer) data. cumulative : bool If True, plot the cumulative counts as bins increase. common_bins : bool If True, use the same bins when semantic variables produce multiple plots. If using a reference rule to determine the bins, it will be computed with the full dataset. common_norm : bool If True and using a normalized statistic, the normalization will apply over the full dataset. Otherwise, normalize each histogram independently. multiple : {{"layer", "dodge", "stack", "fill"}} Approach to resolving multiple elements when semantic mapping creates subsets. Only relevant with univariate data. element : {{"bars", "step", "poly"}} Visual representation of the histogram statistic. Only relevant with univariate data. fill : bool If True, fill in the space under the histogram. Only relevant with univariate data. shrink : number Scale the width of each bar relative to the binwidth by this factor. Only relevant with univariate data. kde : bool If True, compute a kernel density estimate to smooth the distribution and show on the plot as (one or more) line(s). Only relevant with univariate data. kde_kws : dict Parameters that control the KDE computation, as in :func:`kdeplot`. line_kws : dict Parameters that control the KDE visualization, passed to :meth:`matplotlib.axes.Axes.plot`. thresh : number or None Cells with a statistic less than or equal to this value will be transparent. Only relevant with bivariate data. pthresh : number or None Like ``thresh``, but a value in [0, 1] such that cells with aggregate counts (or other statistics, when used) up to this proportion of the total will be transparent. pmax : number or None A value in [0, 1] that sets that saturation point for the colormap at a value such that cells below is constistute this proportion of the total count (or other statistic, when used). {params.dist.cbar} {params.dist.cbar_ax} {params.dist.cbar_kws} {params.core.palette} {params.core.hue_order} {params.core.hue_norm} {params.core.color} {params.dist.log_scale} {params.dist.legend} {params.core.ax} kwargs Other keyword arguments are passed to one of the following matplotlib functions: - :meth:`matplotlib.axes.Axes.bar` (univariate, element="bars") - :meth:`matplotlib.axes.Axes.fill_between` (univariate, other element, fill=True) - :meth:`matplotlib.axes.Axes.plot` (univariate, other element, fill=False) - :meth:`matplotlib.axes.Axes.pcolormesh` (bivariate) Returns ------- {returns.ax} See Also -------- {seealso.displot} {seealso.kdeplot} {seealso.rugplot} {seealso.ecdfplot} {seealso.jointplot} Notes ----- The choice of bins for computing and plotting a histogram can exert substantial influence on the insights that one is able to draw from the visualization. If the bins are too large, they may erase important features. On the other hand, bins that are too small may be dominated by random variability, obscuring the shape of the true underlying distribution. The default bin size is determined using a reference rule that depends on the sample size and variance. This works well in many cases, (i.e., with "well-behaved" data) but it fails in others. It is always a good to try different bin sizes to be sure that you are not missing something important. This function allows you to specify bins in several different ways, such as by setting the total number of bins to use, the width of each bin, or the specific locations where the bins should break. Examples -------- .. include:: ../docstrings/histplot.rst returnsseealso)r$r7r8rhrg?Zscott)!r-shadeverticalkernelbwgridsizerr\r r shade_lowestr!r"r#rr/r.r*r+r,rrrrBr  bw_method bw_adjustrrSrMr0data2rc!(Ks| dk rH| }|dko(|dk o(tj|dk}#|#r8d}$|}nd}$tj|$t|rfd}$tj|$t||}}|dk rd|d}$tj|$t|}|dk rd}$tj|$t| dk r| rd}d |d }$tj|$t|"jd |}|dk r|}t|tjt d }%|%j |||d |dkrt j }|%j s$|St|||||| d}&|%j|ddg|d|%jr|"j}'|dk rn||'d<|%jf||||| |!|&d|'n(|%jf||||| ||!| | ||&d |"|S)Nrz/Use `x` and `y` rather than `data` `and `data2`z;The `data2` param is now named `y`; please update your codez|The `vertical` parameter is deprecated and will be removed in a future version. Assign the data to the `y` variable instead.zPThe `bw` parameter is deprecated in favor of `bw_method` and `bw_adjust`. Using zV for `bw_method`, but please see the docs for the new parameters and update your code.zFSupport for alternate kernels has been removed. Using Gaussian kernel.rzG`shade_lowest` is now deprecated in favor of `thresh`. Setting `thresh=z`, but please update your code.Zn_levels)r0r1)r*r-r.)r@rAr>rr\rnumericr) allowed_typesrrS)rrrrMr rr) rrMrBr r rSrr!r"r#r)r_ndimrr FutureWarningrr=r+r/r0r1r2r3r?rHr4r:rYrr)(r,r-r:r;r<r=r>rr\r rr?r!r"r#rr/r.r*r+r,rrrrBr r@rArrSrMr0rBrr5Zx_passed_as_datarr6rrr6r6r7r[s!            a^Plot univariate or bivariate distributions using kernel density estimation. A kernel density estimate (KDE) plot is a method for visualizing the distribution of observations in a dataset, analagous to a histogram. KDE represents the data using a continuous probability density curve in one or more dimensions. The approach is explained further in the :ref:`user guide `. Relative to a histogram, KDE can produce a plot that is less cluttered and more interpretable, especially when drawing multiple distributions. But it has the potential to introduce distortions if the underlying distribution is bounded or not smooth. Like a histogram, the quality of the representation also depends on the selection of good smoothing parameters. Parameters ---------- {params.core.xy} shade : bool Alias for ``fill``. Using ``fill`` is recommended. vertical : bool Orientation parameter. .. deprecated:: 0.11.0 specify orientation by assigning the ``x`` or ``y`` variables. kernel : str Function that defines the kernel. .. deprecated:: 0.11.0 support for non-Gaussian kernels has been removed. bw : str, number, or callable Smoothing parameter. .. deprecated:: 0.11.0 see ``bw_method`` and ``bw_adjust``. gridsize : int Number of points on each dimension of the evaluation grid. {params.kde.cut} {params.kde.clip} {params.dist.legend} {params.kde.cumulative} shade_lowest : bool If False, the area below the lowest contour will be transparent .. deprecated:: 0.11.0 see ``thresh``. {params.dist.cbar} {params.dist.cbar_ax} {params.dist.cbar_kws} {params.core.ax} weights : vector or key in ``data`` If provided, weight the kernel density estimation using these values. {params.core.hue} {params.core.palette} {params.core.hue_order} {params.core.hue_norm} {params.dist.multiple} common_norm : bool If True, scale each conditional density by the number of observations such that the total area under all densities sums to 1. Otherwise, normalize each density independently. common_grid : bool If True, use the same evaluation grid for each kernel density estimate. Only relevant with univariate data. levels : int or vector Number of contour levels or values to draw contours at. A vector argument must have increasing values in [0, 1]. Levels correspond to iso-proportions of the density: e.g., 20% of the probability mass will lie below the contour drawn for 0.2. Only relevant with bivariate data. thresh : number in [0, 1] Lowest iso-proportion level at which to draw a contour line. Ignored when ``levels`` is a vector. Only relevant with bivariate data. {params.kde.bw_method} {params.kde.bw_adjust} {params.dist.log_scale} {params.core.color} fill : bool or None If True, fill in the area under univariate density curves or between bivariate contours. If None, the default depends on ``multiple``. {params.core.data} warn_singular : bool If True, issue a warning when trying to estimate the density of data with zero variance. kwargs Other keyword arguments are passed to one of the following matplotlib functions: - :meth:`matplotlib.axes.Axes.plot` (univariate, ``fill=False``), - :meth:`matplotlib.axes.Axes.fill_between` (univariate, ``fill=True``), - :meth:`matplotlib.axes.Axes.contour` (bivariate, ``fill=False``), - :meth:`matplotlib.axes.contourf` (bivariate, ``fill=True``). Returns ------- {returns.ax} See Also -------- {seealso.displot} {seealso.histplot} {seealso.ecdfplot} {seealso.jointplot} {seealso.violinplot} Notes ----- The *bandwidth*, or standard deviation of the smoothing kernel, is an important parameter. Misspecification of the bandwidth can produce a distorted representation of the data. Much like the choice of bin width in a histogram, an over-smoothed curve can erase true features of a distribution, while an under-smoothed curve can create false features out of random variability. The rule-of-thumb that sets the default bandwidth works best when the true distribution is smooth, unimodal, and roughly bell-shaped. It is always a good idea to check the default behavior by using ``bw_adjust`` to increase or decrease the amount of smoothing. Because the smoothing algorithm uses a Gaussian kernel, the estimated density curve can extend to values that do not make sense for a particular dataset. For example, the curve may be drawn over negative values when smoothing data that are naturally positive. The ``cut`` and ``clip`` parameters can be used to control the extent of the curve, but datasets that have many observations close to a natural boundary may be better served by a different visualization method. Similar considerations apply when a dataset is naturally discrete or "spiky" (containing many repeated observations of the same value). Kernel density estimation will always produce a smooth curve, which would be misleading in these situations. The units on the density axis are a common source of confusion. While kernel density estimation produces a probability distribution, the height of the curve at each point gives a density, not a probability. A probability can be obtained only by integrating the density across a range. The curve is normalized so that the integral over all possible values is 1, meaning that the scale of the density axis depends on the data values. Examples -------- .. include:: ../docstrings/kdeplot.rst Z proportion) r,r-r.r/r complementaryr*r+r,rr rc Ksvt|tjtd}|j||| d| dkr4tj} |jsBtd|j| | dt ||d}|j f|| d| | S)N)r0r1)r*r-r.z(Bivariate ECDF plots are not implemented)r)rrG)rr ) r+r/r0r1r2r3r:NotImplementedErrorr4rHr)r0r,r-r.r/rrGr*r+r,rr rr5r6rr6r6r7rs"arPlot empirical cumulative distribution functions. An ECDF represents the proportion or count of observations falling below each unique value in a dataset. Compared to a histogram or density plot, it has the advantage that each observation is visualized directly, meaning that there are no binning or smoothing parameters that need to be adjusted. It also aids direct comparisons between multiple distributions. A downside is that the relationship between the appearance of the plot and the basic properties of the distribution (such as its central tendency, variance, and the presence of any bimodality) may not be as intuitive. More information is provided in the :ref:`user guide `. Parameters ---------- {params.core.data} {params.core.xy} {params.core.hue} weights : vector or key in ``data`` If provided, weight the contribution of the corresponding data points towards the cumulative distribution using these values. {params.ecdf.stat} {params.ecdf.complementary} {params.core.palette} {params.core.hue_order} {params.core.hue_norm} {params.dist.log_scale} {params.dist.legend} {params.core.ax} kwargs Other keyword arguments are passed to :meth:`matplotlib.axes.Axes.plot`. Returns ------- {returns.ax} See Also -------- {seealso.displot} {seealso.histplot} {seealso.kdeplot} {seealso.rugplot} Examples -------- .. include:: ../docstrings/ecdfplot.rst g?) rrrr0r-r.r*r+r,rr ac Ks| dk rd}tj|t| }~ |dk r6d}tj|t| jd|dkr`d|}}d}tj|td}t|tjtd}|j||| d|dkrtj }|j ||j || | f| |S)Nz=The `a` parameter is now called `x`. Please update your code.zlThe `axis` variable is no longer used and will be removed. Instead, assign variables directly to `x` or `y`.r;r-zwUsing `vertical=True` to control the orientation of the plot is deprecated. Instead, assign the data directly to `y`. )r0r1)r*r-r.) rrrFr=r+r/r0r1r2r3r4r)r,rrrr0r-r.r*r+r,rr rIr5rr/r6r6r6r7rs,     aPlot marginal distributions by drawing ticks along the x and y axes. This function is intended to complement other plots by showing the location of individual observations in an unobstrusive way. Parameters ---------- {params.core.xy} height : number Proportion of axes extent covered by each rug element. axis : {{"x", "y"}} Axis to draw the rug on. .. deprecated:: 0.11.0 specify axis by assigning the ``x`` or ``y`` variables. {params.core.ax} {params.core.data} {params.core.hue} {params.core.palette} {params.core.hue_order} {params.core.hue_norm} expand_margins : bool If True, increase the axes margins by the height of the rug to avoid overlap with other elements. legend : bool If False, do not add a legend for semantic variables. kwargs Other keyword arguments are passed to :meth:`matplotlib.collections.LineCollection` Returns ------- {returns.ax} Examples -------- .. include:: ../docstrings/rugplot.rst r))r,r-r.rrr/kindrugrug_kwsrr r*r+r,rScol_wrap row_order col_orderraspect facet_kwsc' KsHt|tjtd}|j| | |dtddddg|d|kr^dj|}tj|t|j dx6dD].}||j krd|j |dkrdd |d |j |<qdW|j j |j d }|j dd|jjf}|j jd d}|j jd d}|dkri}tf||||||||d |}|dkrddg}nd}|j||| d|js<|S| |d<|dkr|j}i} t| tjti}!x&| jD]\}"}#|j |"|#|!|"<qvW|!ddkr|j|!d<|!|d<|jd||jrt||jt|jf|nt||jt|jf|n,|dkr|j}$i} t| tjt i}!x&| jD]\}"}#|$j |"|#|!|"<q6W|!|$d<||$d<|jrt|$|j!t |j!f|$nt|$|j"t |j"f|$n|dkr0|j}%i}!i} t| t#jt$x&| jD]\}"}#|%j |"|#|!|"<qW|!|%d<||%d<|jr(t|%|j%t$|j%f|%nt&d|rx| dkrDi} t| |j't(d| d<|dk rl|| d<|j'f| |j)|j jd|j*j+dj,|j jd|j*j+dj-d|j.|j/|dk r |dk s|dk r t0|t1j2st1j2|}t1j3||j4|j4jj5|jddd|_4n$dd|j jD}&|j j |&d |_4|S) N)r0r1)r*r-r.rKr)r(r*rzf`displot` is a figure-level function and does not accept the ax= paramter. You may wish to try {}plot.rrrv)r)r0rrrNrOrPrrQrCr)rDrr r|rrSz(Bivariate ECDF plots are not implementedFr,rr-)Zx_varZy_varT)Z left_indexZ right_indexcSs*i|]"\}}|dkr d|dn||qS)Nrvr6)rlr~rr6r6r7r7 szdisplot..)rr)6r(r/r0r1rformatrrrr=r1rrrrZ duplicatedrr r4r?rYrr r3rrr}rZr:rr r rrrr rrrHrrZset_axis_labelsrGrZ get_xlabelZ get_ylabelZ set_titlesZ tight_layoutrErrmerger0 difference)'r0r,r-r.rrr/rKrLrMrr r*r+r,rSrNrOrPrrQrRr5r6rrZ grid_dataZcol_nameZrow_namertrDhist_kwsZestimate_defaultsrrZ default_valrZecdf_kwsZ wide_colsr6r6r7rs               a/ Figure-level interface for drawing distribution plots onto a FacetGrid. This function provides access to several approaches for visualizing the univariate or bivariate distribution of data, including subsets of data defined by semantic mapping and faceting across multiple subplots. The ``kind`` parameter selects the approach to use: - :func:`histplot` (with ``kind="hist"``; the default) - :func:`kdeplot` (with ``kind="kde"``) - :func:`ecdfplot` (with ``kind="ecdf"``; univariate-only) Additionally, a :func:`rugplot` can be added to any kind of plot to show individual observations. Extra keyword arguments are passed to the underlying function, so you should refer to the documentation for each to understand the complete set of options for making plots with this interface. See the :doc:`distribution plots tutorial <../tutorial/distributions>` for a more in-depth discussion of the relative strengths and weaknesses of each approach. The distinction between figure-level and axes-level functions is explained further in the :doc:`user guide <../tutorial/function_overview>`. Parameters ---------- {params.core.data} {params.core.xy} {params.core.hue} {params.facets.rowcol} kind : {{"hist", "kde", "ecdf"}} Approach for visualizing the data. Selects the underlying plotting function and determines the additional set of valid parameters. rug : bool If True, show each observation with marginal ticks (as in :func:`rugplot`). rug_kws : dict Parameters to control the appearance of the rug plot. {params.dist.log_scale} {params.dist.legend} {params.core.palette} {params.core.hue_order} {params.core.hue_norm} {params.core.color} {params.facets.col_wrap} {params.facets.rowcol_order} {params.facets.height} {params.facets.aspect} {params.facets.facet_kws} kwargs Other keyword arguments are documented with the relevant axes-level function: - :func:`histplot` (with ``kind="hist"``) - :func:`kdeplot` (with ``kind="kde"``) - :func:`ecdfplot` (with ``kind="ecdf"``) Returns ------- {returns.facetgrid} See Also -------- {seealso.histplot} {seealso.kdeplot} {seealso.rugplot} {seealso.ecdfplot} {seealso.jointplot} Examples -------- See the API documentation for the axes-level functions for more details about the breadth of options available for each plot kind. .. include:: ../docstrings/displot.rst cCsntj|}t|dkrdSdtj|t|d}|dkrLttj|jSttj|j |j |SdS)z;Calculate number of hist bins using Freedman-Diaconis rule.rkrrhrNgUUUUUU?) r_r`rrZiqrrosqrtsizeceilrr)rIrwr6r6r7_freedman_diaconis_bins s  rZc!st|r| rd}nd}d|}tj|t|dkr8tj}t| }| dkrdt|drd|j} | dk rdd}|dk rp|}tj |t }|j dkr|j }t |}| p|pdk } |dkrin|j}|dkrin|j}|dkrin|j}| dkrin| j} | dkr<| r|jd|j\}n|j|jd\}|j} |j|dk r|rV||d <n.|rf||d <n|rv||d <nr|| d <|r|dkrtt|d }|jd d |jd | | rdnd}|jd| }|j||f||d||| kr||d<|r<|jd| }t|f| ||d||| kr<||d<|r|jd| }| rXdnd}t|f|||d||| kr||d<dk rNfdd}| jdd}| jdd}| jdd}| jdtj tjf}tj|j|jdd}t|||||}j |||} | r$| |}} |j|| fd|i| |dkrN|| d<|rp| rf|j!| n |j"| |S)aDEPRECATED: Flexibly plot a univariate distribution of observations. .. warning:: This function is deprecated and will be removed in a future version. Please adapt your code to use one of two new functions: - :func:`displot`, a figure-level function with a similar flexibility over the kind of plot to draw - :func:`histplot`, an axes-level function for plotting histograms, including with kernel density smoothing This function combines the matplotlib ``hist`` function (with automatic calculation of a good default bin size) with the seaborn :func:`kdeplot` and :func:`rugplot` functions. It can also fit ``scipy.stats`` distributions and plot the estimated PDF over the data. Parameters ---------- a : Series, 1d-array, or list. Observed data. If this is a Series object with a ``name`` attribute, the name will be used to label the data axis. bins : argument for matplotlib hist(), or None, optional Specification of hist bins. If unspecified, as reference rule is used that tries to find a useful default. hist : bool, optional Whether to plot a (normed) histogram. kde : bool, optional Whether to plot a gaussian kernel density estimate. rug : bool, optional Whether to draw a rugplot on the support axis. fit : random variable object, optional An object with `fit` method, returning a tuple that can be passed to a `pdf` method a positional arguments following a grid of values to evaluate the pdf on. hist_kws : dict, optional Keyword arguments for :meth:`matplotlib.axes.Axes.hist`. kde_kws : dict, optional Keyword arguments for :func:`kdeplot`. rug_kws : dict, optional Keyword arguments for :func:`rugplot`. color : matplotlib color, optional Color to plot everything but the fitted curve in. vertical : bool, optional If True, observed values are on y-axis. norm_hist : bool, optional If True, the histogram height shows a density rather than a count. This is implied if a KDE or fitted density is plotted. axlabel : string, False, or None, optional Name for the support axis label. If None, will try to get it from a.name if False, do not set a label. label : string, optional Legend label for the relevant component of the plot. ax : matplotlib axis, optional If provided, plot on this axis. Returns ------- ax : matplotlib Axes Returns the Axes object with the plot for further tweaking. See Also -------- kdeplot : Show a univariate or bivariate distribution with a kernel density estimate. rugplot : Draw small vertical lines to show each observation in a distribution. Examples -------- Show a default plot with a kernel density estimate and histogram with bin size determined automatically with a reference rule: .. plot:: :context: close-figs >>> import seaborn as sns, numpy as np >>> sns.set_theme(); np.random.seed(0) >>> x = np.random.randn(100) >>> ax = sns.distplot(x) Use Pandas objects to get an informative axis label: .. plot:: :context: close-figs >>> import pandas as pd >>> x = pd.Series(x, name="x variable") >>> ax = sns.distplot(x) Plot the distribution with a kernel density estimate and rug plot: .. plot:: :context: close-figs >>> ax = sns.distplot(x, rug=True, hist=False) Plot the distribution with a histogram and maximum likelihood gaussian distribution fit: .. plot:: :context: close-figs >>> from scipy.stats import norm >>> ax = sns.distplot(x, fit=norm, kde=False) Plot the distribution on the vertical axis: .. plot:: :context: close-figs >>> ax = sns.distplot(x, vertical=True) Change the color of all the plot elements: .. plot:: :context: close-figs >>> sns.set_color_codes() >>> ax = sns.distplot(x, color="y") Pass specific parameters to the underlying plot functions: .. plot:: :context: close-figs >>> ax = sns.distplot(x, rug=True, rug_kws={"color": "g"}, ... kde_kws={"color": "k", "lw": 3, "label": "KDE"}, ... hist_kws={"histtype": "step", "linewidth": 3, ... "alpha": 1, "color": "g"}) z<`kdeplot` (an axes-level function for kernel density plots).z3`histplot` (an axes-level function for histograms).z`distplot` is a deprecated function and will be removed in a future version. Please adapt your code to use either `displot` (a figure-level function with similar flexibility) or NrTrrr2rOg?rZ horizontalr;rS) orientationrS)r;rrSr-r,)rrrScsj|fS)N)pdf)r,)fitr$r6r7r] szdistplot..pdfz#282828r>r9rrhr\)Zddof)#rrrFr2r3r8hasattrrr_r`floatrErrrYrZmeanrrrrZrZr=r)rrrrZ gaussian_kdeZ scotts_factorZstdrr^Z set_ylabelZ set_xlabel)!rIrr)r(rLr^rVrrMZfit_kwsrSr;Z norm_histZaxlabelrrr,Zaxes_level_suggestionrZlabel_axrr\Z hist_colorZ kde_colorZ rug_colorrr]Z fit_colorr>rr\r=r-r6)r^r$r7r s                            )N)N)N)N)N)NNTTFNNNNNNFFNNNN)B__doc__Znumbersr functoolsrrrZnumpyr_ZpandasrZ matplotlibrFZmatplotlib.pyplotZpyplotr2Zmatplotlib.transformsZ transformsr Zmatplotlib.colorsrZmatplotlib.collectionsrZscipyrZ_corerZ _statisticsr r r Zaxisgridr r utilsrrrrrZpalettesrZexternalrZ _decoratorsrZ _docstringsrr__all__rHZ _dist_paramsZfrom_nested_componentsZfrom_function_paramsr3Z _param_docsr+r(rrSrrrrrZrr6r6r6r7s                 D([b  }