ó áp7]c@s}dZddlmZmZddlZddlmZmZddl m Z ddl m Z ddl mZdd d „Zdd d „Zdd d „Zd d„Zd„Zdeddddd„Zd„Zdd„Zddd„Zddd„Zddd„Zdddeddd„Zd„Zdded„Zdd„Z dd„Z!d d!„Z"dd dd"„Z#dS(#s„Tests and Confidence Intervals for Binomial Proportions Created on Fri Mar 01 00:23:07 2013 Author: Josef Perktold License: BSD-3 iÿÿÿÿ(tlziptrangeN(tstatstoptimize(t float_info(tAllPairsResults(tHypothesisTestWarninggš™™™™™©?tnormalcsdt|ddƒ}|dk r3t|ƒr3d}ntj|ƒ}tjˆƒ‰|dˆ‰dˆ}|dkrÁtjˆdˆˆƒ}tjjˆdƒ|}ˆ|}ˆ|} n¬|dkrC‡‡‡fd†} |d kr÷d }nt j | t j ˆƒ}|ˆkr$d} qmt j | ˆdt j ƒ} n*|d krútjj||ˆ|dƒ}tjj||dˆ|ƒ} tj|ƒd krÇd |ˆd k= 7``) [3]_ Returns ------- confint : ndarray, 2-D Array of [lower, upper] confidence levels for each category, such that overall coverage is (approximately) `1-alpha`. Raises ------ ValueError If `alpha` is not in `(0, 1)` (bounds excluded), or if the values in `counts` are not all positive or null. NotImplementedError If `method` is not kown. Exception When ``method == 'sison-glaz'``, if for some reason `c` cannot be computed; this signals a bug and should be reported. Notes ----- The `goodman` method [2]_ is based on approximating a statistic based on the multinomial as a chi-squared random variable. The usual recommendation is that this is valid if all the values in `counts` are greater than or equal to 5. There is no condition on the number of categories for this method. The `sison-glaz` method [3]_ approximates the multinomial probabilities, and evaluates that with a maximum-likelihood estimator. The first approximation is an Edgeworth expansion that converges when the number of categories goes to infinity, and the maximum-likelihood estimator converges when the number of observations (``sum(counts)``) goes to infinity. In their paper, Sison & Glaz demo their method with at least 7 categories, so ``len(counts) >= 7`` with all values in `counts` at or above 5 can be used as a rule of thumb for the validity of this method. This method is less conservative than the `goodman` method (i.e. it will yield confidence intervals closer to the desired significance level), but produces confidence intervals of uniform width over all categories (except when the intervals reach 0 or 1, in which case they are truncated), which makes it most useful when proportions are of similar magnitude. Aside from the original sources ([1]_, [2]_, and [3]_), the implementation uses the formulas (though not the code) presented in [4]_ and [5]_. References ---------- .. [1] Levin, Bruce, "A representation for multinomial cumulative distribution functions," The Annals of Statistics, Vol. 9, No. 5, 1981, pp. 1123-1126. .. [2] Goodman, L.A., "On simultaneous confidence intervals for multinomial proportions," Technometrics, Vol. 7, No. 2, 1965, pp. 247-254. .. [3] Sison, Cristina P., and Joseph Glaz, "Simultaneous Confidence Intervals and Sample Size Determination for Multinomial Proportions," Journal of the American Statistical Association, Vol. 90, No. 429, 1995, pp. 366-369. .. [4] May, Warren L., and William D. Johnson, "A SAS® macro for constructing simultaneous confidence intervals for multinomial proportions," Computer methods and programs in Biomedicine, Vol. 53, No. 3, 1997, pp. 153-162. .. [5] May, Warren L., and William D. Johnson, "Constructing two-sided simultaneous confidence intervals for multinomial proportions for small counts in a large number of cells," Journal of Statistical Software, Vol. 5, No. 6, 2000, pp. 1-24. iis(alpha must be in (0, 1), bounds excludedtdtypescounts must be >= 0R8iiitsisoncSsk|\}}tjj||ƒtjj|d|ƒ}|dkrgtj|ƒrgt|ddkƒS|S(sPCompute P(b <= Z <= a) where Z ~ Poisson(p) and `interval = (b, a)`.ii(RtpoissontcdfRtisnantint(R!R tbtatprob((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytpoisson_intervals  ,csa|\}}||dˆ||d|f|ƒˆ|||df|ƒˆ||f|ƒS(sƒCompute mu_r, the r-th factorial moment of a poisson random variable of parameter `p` truncated to `interval = (b, a)`.i((R!trR R?R@(RB(s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt"truncated_poisson_factorial_moments $c s9gtddƒD]C}tjgt|ˆƒD]\}}ˆ|||ƒ^q,ƒ^q\}}}}|}|||d} ||dd||d|dd|d} ||dd||dd|d|d|d|dd|dd|d} | jƒ| jƒd } | jƒd| djƒ| jƒd} ˆ|jƒtj| jƒƒ}tj|d dƒtjdtjƒ}|dd|}|dd|dd}|dd |dd |dd }|d| |d| |d | d|d }|tj| jƒƒS(s¡Compute the Edgeworth expansion term of Sison & Glaz's formula (1) (approximated probability for multinomial proportions in a given box).iiiiiiii gø?ii-iiH(RRtarraytziptsumRtexptpi(t intervalsRCR!R tmu_r1tmu_r2tmu_r3tmu_r4tmutmu2tmu3tmu4tg1tg2txtphitH3tH4tH6tf(tcountstnRD(s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt edgeworthsb2Z,#,&2csytjtjtjgt|ˆƒD]\}}ˆ||ƒ^q"ƒƒtjˆ|ƒƒtjtjjˆˆƒƒƒS(sCompute approximated probability for Multinomial(n, proportions) to be in `intervals` (Sison & Glaz's formula (1)).(RRHRGtlogRFRR;t_pmf(RJR!R (R[R]R\RB(s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt!approximated_multinomial_interval8sScsCˆgˆD]2}tj||dƒtj||ˆƒf^q ƒS(sSCompute interval coverage for a given `c` (Sison & Glaz's formula (7)).i(Rtmaximumtminimum(tcR'(R`R[R\(s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytnuBsgð?sHCouldn't find a value for `c` that solves nu(c) <= 1 - alpha < nu(c + 1)smethod "%s" is not available(t ValueErrorRREtfloattanyRGtlenRtchi2RRtTt ExceptionRaRbR"(R[R R(tkt proportionsRitdeltatregionRdRctnuctnucp1tgtci_lowertci_upper((R`R[R]R\RBRDs;lib/python2.7/site-packages/statsmodels/stats/proportion.pytmultinomial_proportions_confint¡sFT    "&     #  "cCsO|}|dkr?|d||tjj|dƒd}n tdƒ‚|S(sfind sample size to get desired confidence interval length Parameters ---------- proportion : float in (0, 1) proportion or quantile half_length : float in (0, 1) desired half length of the confidence interval alpha : float in (0, 1) significance level, default 0.05, coverage of the two-sided interval is (approximately) ``1 - alpha`` method : string in ['normal'] method to use for confidence interval, currently only normal approximation Returns ------- n : float sample size to get the desired half length of the confidence interval Notes ----- this is mainly to store the formula. possible application: number of replications in bootstrap samples Rig@isonly "normal" is available(RRRR"(t proportiont half_lengthR R(RR\((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytsamplesize_confint_proportion`s  - cCsQ|dkrtdƒ‚ndtjtj|ƒƒtjtj|ƒƒ}|S(s6effect size for a test comparing two proportions for use in power function Parameters ---------- prop1, prop2: float or array_like Returns ------- es : float or ndarray effect size for (transformed) prop1 - prop2 Notes ----- only method='normal' is implemented to match pwr.p2.test see http://www.statmethods.net/stats/power.html Effect size for `normal` is defined as :: 2 * (arcsin(sqrt(prop1)) - arcsin(sqrt(prop2))) I think other conversions to normality can be used, but I need to check. Examples -------- >>> import statsmodels.api as sm >>> sm.stats.proportion_effectsize(0.5, 0.4) 0.20135792079033088 >>> sm.stats.proportion_effectsize([0.3, 0.4, 0.5], 0.4) array([-0.21015893, 0. , 0.20135792]) Rsonly "normal" is implementedi(ReRtarcsinR(tprop1tprop2R(tes((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytproportion_effectsize„s" 2cCstj|d||ƒS(s`standard error for the estimate of a proportion This is just ``np.sqrt(p * (1. - p) / nobs)`` Parameters ---------- prop : array_like proportion nobs : int, array_like number of observations Returns ------- std : array_like standard error for a proportion of nobs independent observations gð?(RR(tpropR ((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytstd_prop¬sRic CsÛt| tƒs| | f} ntjj|ƒ} |tj|ƒ| } |tj|ƒ| }|sp|dkrÔtj| | d| ƒ} tj|| d| ƒ}|dkrÔ| d| } |d| }qÔntj | |kƒrddl }|j dt ƒntj|ƒ}| || dd| |}||| d d| |}|dkr„tjj |ƒtjj |ƒ}nA|dkrÅtjj || |ƒtjj | d | |ƒ}n|| |||ffS( sGeneric statistical power function for normal based equivalence test This includes options to adjust the normal approximation and can use the binomial to evaluate the probability of the rejection region see power_ztost_prob for a description of the options tbinomgà?Rgð?iÿÿÿÿNsno overlap, power is zeroii(t isinstancettupleRRRRRtceilttruncRgtwarningstwarnRR<R€(tmean_lowtvar_lowtmean_upptvar_upptmean_alttvar_altR tdiscreteR,R t continuitytcritval_continuityR/tk_lowtk_uppR…tstd_alttz_lowtz_upptpower((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt _power_ztost¿s.    %  cCsOt||ddd|ƒ}t||ddd|ƒ}tj||ƒ||fS(säexact TOST test for one proportion using binomial distribution Parameters ---------- count : integer or array_like the number of successes in nobs trials. nobs : integer the number of trials or observations. low, upp : floats lower and upper limit of equivalence region Returns ------- pvalue : float p-value of equivalence test pval_low, pval_upp : floats p-values of lower and upper one-sided tests t alternativetlargerR~tsmaller(R RRa(R'R tlowtuppttt1ttt2((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt binom_tostëscCsBtjj|||ƒd}tjj|||ƒd}||fS(sËrejection region for binomial TOST The interval includes the end points, `reject` if and only if `r_low <= x <= r_upp`. The interval might be empty with `r_upp < r_low`. Parameters ---------- low, upp : floats lower and upper limit of equivalence region nobs : integer the number of trials or observations. Returns ------- x_low, x_upp : float lower and upper bound of rejection region i(RR€RR(RšR›R R tx_lowtx_upp((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytbinom_tost_reject_intervalss two-sidedcCs‹|dkrd}|d}n|d krJtjj|||ƒd}nd}|d kr{tjj|||ƒd}n|}||fS( sŠrejection region for binomial test for one sample proportion The interval includes the end points of the rejection region. Parameters ---------- value : float proportion under the Null hypothesis nobs : integer the number of trials or observations. Returns ------- x_low, x_upp : float lower and upper bound of rejection region t2ss two-sidediR™iiR˜(R¢s two-sided(R¢R™(R¢R˜(RR€RR(tvalueR R R—RŸR ((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytbinom_test_reject_intervals    gà?cCsÅtj|dkƒs*tj|dkƒr9tdƒ‚n|dkrctj|d|d|ƒ}n^|dkrŽtjj|d ||ƒ}n3|dkrµtjj|||ƒ}n td ƒ‚|S(s]Perform a test that the probability of success is p. This is an exact, two-sided test of the null hypothesis that the probability of success in a Bernoulli experiment is `p`. Parameters ---------- count : integer or array_like the number of successes in nobs trials. nobs : integer the number of trials or observations. prop : float, optional The probability of success under the null hypothesis, `0 <= prop <= 1`. The default value is `prop = 0.5` alternative : string in ['two-sided', 'smaller', 'larger'] alternative hypothesis, which can be two-sided or either one of the one-sided tests. Returns ------- p-value : float The p-value of the hypothesis test Notes ----- This uses scipy.stats.binom_test for the two-sided alternative. gð?gsp must be in range [0,1]R¢s two-sidedR\R tlR˜itsR™sAalternative not recognized should be two-sided, larger or smaller(R¢s two-sided(R¥R˜(R¦R™(RRgReRR R€tsfR<(R'R R~R—tpval((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyR As*    cCsq|dkrd||}nt|||d|ƒ\}}tjj|||ƒtjj|d||ƒ}|S(Ngà?R i(RR¡RR€R<(RšR›R tp_altR RŸR R•((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytpower_binom_tostns  c CsÎ|} t||ƒd} |} t||ƒd} |}t||ƒd}|d k rqt||ƒd} } nt| | | | ||d|d|d|d|d|d| ƒ}tj|ddƒ|d fS( s¦ Power of proportions equivalence test based on normal distribution Parameters ---------- low, upp : floats lower and upper limit of equivalence region nobs : int number of observations p_alt : float in (0,1) proportion under the alternative alpha : float in (0,1) significance level of the test dist : string in ['norm', 'binom'] This defines the distribution to evalute the power of the test. The critical values of the TOST test are always based on the normal approximation, but the distribution for the power can be either the normal (default) or the binomial (exact) distribution. variance_prop : None or float in (0,1) If this is None, then the variances for the two one sided tests are based on the proportions equal to the equivalence limits. If variance_prop is given, then it is used to calculate the variance for the TOST statistics. If this is based on an sample, then the estimated proportion can be used. discrete : bool If true, then the critical values of the rejection region are converted to integers. If dist is "binom", this is automatically assumed. If discrete is false, then the TOST critical values are used as floating point numbers, and the power is calculated based on the rejection region that is not discretized. continuity : bool or float adjust the rejection region for the normal power probability. This has and effect only if ``dist='norm'`` critval_continuity : bool or float If this is non-zero, then the critical values of the tost rejection region are adjusted before converting to integers. This affects both distributions, ``dist='norm'`` and ``dist='binom'``. Returns ------- power : float statistical power of the equivalence test. (k_low, k_upp, z_low, z_upp) : tuple of floats critical limits in intermediate steps temporary return, will be changed Notes ----- In small samples the power for the ``discrete`` version, has a sawtooth pattern as a function of the number of observations. As a consequence, small changes in the number of observations or in the normal approximation can have a large effect on the power. ``continuity`` and ``critval_continuity`` are added to match some results of PASS, and are mainly to investigate the sensitivity of the ztost power to small changes in the rejection region. From my interpretation of the equations in the SAS manual, both are zero in SAS. works vectorized **verification:** The ``dist='binom'`` results match PASS, The ``dist='norm'`` results look reasonable, but no benchmark is available. References ---------- SAS Manual: Chapter 68: The Power Procedure, Computational Resources PASS Chapter 110: Equivalence Tests for One Proportion. iR RR,R RŽRiiN(RRR–RRa(RšR›R R©R R,t variance_propRRŽRR‡RˆR‰RŠR‹RŒR•((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytpower_ztost_propvsI cCsmtj|||fƒ}|jdƒ|jdƒdd…dfd|jƒ}|jd}|||fS(sºcreate a k by 2 contingency table for proportion helper function for proportions_chisquare Parameters ---------- count : integer or array_like the number of successes in nobs trials. nobs : integer the number of trials or observations. Returns ------- table : ndarray (k, 2) contingency table Notes ----- recent scipy has more elaborate contingency table functions iiNgð?(Rt column_stackRGRtshape(R'R ttabletexpectedtn_rows((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt_table_proportionÍs: cCsctj|ƒ}tj|ƒ}|jdkrC|tj|ƒ}n|d|}tj|ƒ}|d kr|dkr‡tdƒ‚nd}n|dkr©||}n7|dkrÎ|d|d|}nd}t|ƒ‚tj|ƒdtj|ƒ} tjd|ƒ} |r"|} n| d| | } tj| ƒ} ddl m } | || |ƒS( s£ Test for proportions based on normal (z) test Parameters ---------- count : integer or array_like the number of successes in nobs trials. If this is array_like, then the assumption is that this represents the number of successes for each independent sample nobs : integer or array-like the number of trials or observations, with the same length as count. value : float, array_like or None, optional This is the value of the null hypothesis equal to the proportion in the case of a one sample test. In the case of a two-sample test, the null hypothesis is that prop[0] - prop[1] = value, where prop is the proportion in the two samples. If not provided value = 0 and the null is prop[0] = prop[1] alternative : string in ['two-sided', 'smaller', 'larger'] The alternative hypothesis can be either two-sided or one of the one- sided tests, smaller means that the alternative hypothesis is ``prop < value`` and larger means ``prop > value``. In the two sample test, smaller means that the alternative hypothesis is ``p1 < p2`` and larger means ``p1 > p2`` where ``p1`` is the proportion of the first sample and ``p2`` of the second one. prop_var : False or float in (0, 1) If prop_var is false, then the variance of the proportion estimate is calculated based on the sample proportion. Alternatively, a proportion can be specified to calculate this variance. Common use case is to use the proportion under the Null hypothesis to specify the variance of the proportion estimate. Returns ------- zstat : float test statistic for the z-test p-value : float p-value for the z-test Examples -------- >>> count = 5 >>> nobs = 83 >>> value = .05 >>> stat, pval = proportions_ztest(count, nobs, value) >>> print('{0:0.3f}'.format(pval)) 0.695 >>> import numpy as np >>> from statsmodels.stats.proportion import proportions_ztest >>> count = np.array([5, 12]) >>> nobs = np.array([83, 99]) >>> stat, pval = proportions_ztest(count, nobs) >>> print('{0:0.3f}'.format(pval)) 0.159 Notes ----- This uses a simple normal test for proportions. It should be the same as running the mean z-test on the data encoded 1 for event and 0 for no event so that the sum corresponds to the count. In the one and two sample cases with two-sided alternative, this test produces the same p-value as ``proportions_chisquare``, since the chisquare is the distribution of the square of a standard normal distribution. igð?s*value must be provided for a 1-sample testiis-more than two samples are not implemented yetiÿÿÿÿ(t_zstat_generic2N( RRtsizet ones_likeRReR"RGRtstatsmodels.stats.weightstatsR³(R'R R£R—tprop_varR~tk_sampletdifftmsgtp_pooledt nobs_facttvar_tstd_diffR³((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytproportions_ztestés0I         tsamplec CsÔ|dkr|}|}nV|dkr4t}}n=|dkrUd||}}ntj|ƒrq|}}nt||ddd|d|ƒ}t||dd d|d|ƒ}tj|d |d ƒ||fS( s_Equivalence test based on normal distribution Parameters ---------- count : integer or array_like the number of successes in nobs trials. If this is array_like, then the assumption is that this represents the number of successes for each independent sample nobs : integer the number of trials or observations, with the same length as count. low, upp : float equivalence interval low < prop1 - prop2 < upp prop_var : string or float in (0, 1) prop_var determines which proportion is used for the calculation of the standard deviation of the proportion estimate The available options for string are 'sample' (default), 'null' and 'limits'. If prop_var is a float, then it is used directly. Returns ------- pvalue : float pvalue of the non-equivalence test t1, pv1 : tuple of floats test statistic and pvalue for lower threshold test t2, pv2 : tuple of floats test statistic and pvalue for upper threshold test Notes ----- checked only for 1 sample case tlimitsRÀtnullgà?R—R˜R·R£R™i(tFalseRtisrealR¿Ra( R'R RšR›R·t prop_var_lowt prop_var_uppRœR((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytproportions_ztostPs"      c Cs¤tj|ƒ}t||ƒ\}}}|dk ratj|||d|fƒ}|d}n|}tj|jƒ|jƒd|ƒ\}}||||ffS(s†test for proportions based on chisquare test Parameters ---------- count : integer or array_like the number of successes in nobs trials. If this is array_like, then the assumption is that this represents the number of successes for each independent sample nobs : integer the number of trials or observations, with the same length as count. value : None or float or array_like Returns ------- chi2stat : float test statistic for the chisquare test p-value : float p-value for the chisquare test (table, expected) table is a (k, 2) contingency table, ``expected`` is the corresponding table of counts that are expected under independence with given margins Notes ----- Recent version of scipy.stats have a chisquare test for independence in contingency tables. This function provides a similar interface to chisquare tests as ``prop.test`` in R, however without the option for Yates continuity correction. count can be the count for the number of events for a single proportion, or the counts for several independent proportions. If value is given, then all proportions are jointly tested against this value. If value is not given and count and nobs are not scalar, then the null hypothesis is that all samples have the same proportion. itddofN(Rt atleast_1dR²RR­Rt chisquaretravel( R'R R£R¯R°R±RÈtchi2statR¨((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytproportions_chisquare‚s* ! thscCskttjt|ƒdƒŒ}g|D]-}t|t|ƒ|t|ƒƒd^q%}t||d|ƒS(s2chisquare test of proportions for all pairs of k samples Performs a chisquare test for proportions for all pairwise comparisons. The alternative is two-sided Parameters ---------- count : integer or array_like the number of successes in nobs trials. nobs : integer the number of trials or observations. prop : float, optional The probability of success under the null hypothesis, `0 <= prop <= 1`. The default value is `prop = 0.5` multitest_method : string This chooses the method for the multiple testing p-value correction, that is used as default in the results. It can be any method that is available in ``multipletesting``. The default is Holm-Sidak 'hs'. Returns ------- result : AllPairsResults instance The returned results instance has several statistics, such as p-values, attached, and additional methods for using a non-default ``multitest_method``. Notes ----- Yates continuity correction is not available. itmultitest_method(RRt triu_indicesRhRÍtlistR(R'R RÏt all_pairstpairtpvals((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pytproportions_chisquare_allpairs¼s!7c Csœ|dk s|dkr!t‚ngtdt|ƒƒD]}d|f^q7}g|D]-}t|t|ƒ|t|ƒƒd^qV}t||d|ƒS(s­chisquare test of proportions for pairs of k samples compared to control Performs a chisquare test for proportions for pairwise comparisons with a control (Dunnet's test). The control is assumed to be the first element of ``count`` and ``nobs``. The alternative is two-sided, larger or smaller. Parameters ---------- count : integer or array_like the number of successes in nobs trials. nobs : integer the number of trials or observations. prop : float, optional The probability of success under the null hypothesis, `0 <= prop <= 1`. The default value is `prop = 0.5` multitest_method : string This chooses the method for the multiple testing p-value correction, that is used as default in the results. It can be any method that is available in ``multipletesting``. The default is Holm-Sidak 'hs'. alternative : string in ['two-sided', 'smaller', 'larger'] alternative hypothesis, which can be two-sided or either one of the one-sided tests. Returns ------- result : AllPairsResults instance The returned results instance has several statistics, such as p-values, attached, and additional methods for using a non-default ``multitest_method``. Notes ----- Yates continuity correction is not available. ``value`` and ``alternative`` options are not yet implemented. s two-sidedR¢iiRÏN(s two-sidedR¢(RR"RRhRÍRÑR( R'R R£RÏR—RlRÒRÓRÔ((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyt"proportions_chisquare_pairscontrolâs * .7($t__doc__tstatsmodels.compat.pythonRRtnumpyRtscipyRRtsysRtstatsmodels.stats.baseRtstatsmodels.tools.sm_exceptionsRR7RuRxR}RtTrueRR–RžR¡R¤R RªR¬R²RÃR¿RÇRÍRÕRÖ(((s;lib/python2.7/site-packages/statsmodels/stats/proportion.pyts< ¿ # (  *  #-  U  f 2 : &