pystatpower.proportion.single.inequality ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for an inequality test of one proportion.
`solve_size`	Estimate the required sample size for an inequality test of one proportion.
`solve_proportion`	Estimate the required proportion under the alternative hypothesis for an inequality test of one proportion.
`solve_null_proportion`	Estimate the required proportion under the null hypothesis for an inequality test of one proportion.

solve_power ¶

solve_power(
    *,
    proportion: float,
    null_proportion: float,
    size: int,
    alternative: Literal[
        "two-sided", "greater", "less"
    ] = "two-sided",
    alpha: float = 0.05,
    method: Literal["z-p0", "z-phat"] = "z-phat",
    continuity_correction: bool = False,
) -> float

Calculate the statistical power for an inequality test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`null_proportion`	`float`	Proportion under the null hypothesis.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['two-sided', 'greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'two-sided'`, the alternative hypothesis is \(p ≠ p_0\) If `alternative` is `'greater'`, the alternative hypothesis is \(p > p_0\) If `alternative` is `'less'`, the alternative hypothesis is \(p < p_0\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, `alpha` represents the two-sided significance level. If `alternative` is `'greater'` or `'less'`, `alpha` represents the one-sided significance level.	`0.05`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	`'z-phat'`
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

Name	Type	Description
`float`	`float`	The statistical power of the test.

solve_size ¶

solve_size(
    *,
    proportion: float,
    null_proportion: float,
    alternative: Literal[
        "two-sided", "greater", "less"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"] = "z-phat",
    continuity_correction: bool = False,
) -> int

Estimate the required sample size for an inequality test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`null_proportion`	`float`	Proportion under the null hypothesis.	required
`alternative`	`Literal['two-sided', 'greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'two-sided'`, the alternative hypothesis is \(p ≠ p_0\) If `alternative` is `'greater'`, the alternative hypothesis is \(p > p_0\) If `alternative` is `'less'`, the alternative hypothesis is \(p < p_0\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, `alpha` represents the two-sided significance level. If `alternative` is `'greater'` or `'less'`, `alpha` represents the one-sided significance level.	`0.05`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	`'z-phat'`
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

Name	Type	Description
`int`	`int`	The required sample size.

solve_proportion ¶

solve_proportion(
    *,
    null_proportion: float,
    size: int,
    alternative: Literal[
        "two-sided", "greater", "less"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"] = "z-phat",
    continuity_correction: bool = False,
    direction: Literal["greater", "less"] | None = None,
) -> float

Estimate the required proportion under the alternative hypothesis for an inequality test of one proportion.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['two-sided', 'greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'two-sided'`, the alternative hypothesis is \(p ≠ p_0\) If `alternative` is `'greater'`, the alternative hypothesis is \(p > p_0\) If `alternative` is `'less'`, the alternative hypothesis is \(p < p_0\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, `alpha` represents the two-sided significance level. If `alternative` is `'greater'` or `'less'`, `alpha` represents the one-sided significance level.	`0.05`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	`'z-phat'`
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`
`direction`	`Literal['greater', 'less'] \| None`	The direction for the proportion under the alternative hypothesis relative to the proportion under the null hypothesis. `'greater'`: Search for the alternative proportion greater than the null proportion. `'less'`: Search for the alternative proportion less than the null proportion. Note If `alternative` is `'two-sided'`, this parameter is required. If `alternative` is `'greater'`, the search direction is automatically inferred to be `'greater'`, and this parameter is ignored. If `alternative` is `'less'`, the search direction is automatically inferred to be `'less'`, and this parameter is ignored.	`None`

Returns:

Name	Type	Description
`float`	`float`	The required proportion under the alternative hypothesis.

Raises:

Type	Description
`ValueError`	If `alternative` is `'two-sided'` but `direction` is not specified.

solve_null_proportion ¶

solve_null_proportion(
    *,
    proportion: float,
    size: int,
    alternative: Literal[
        "two-sided", "greater", "less"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"] = "z-phat",
    continuity_correction: bool = False,
    direction: Literal["greater", "less"] | None = None,
) -> float

Estimate the required proportion under the null hypothesis for an inequality test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['two-sided', 'greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'two-sided'`, the alternative hypothesis is \(p ≠ p_0\) If `alternative` is `'greater'`, the alternative hypothesis is \(p > p_0\) If `alternative` is `'less'`, the alternative hypothesis is \(p < p_0\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, `alpha` represents the two-sided significance level. If `alternative` is `'greater'` or `'less'`, `alpha` represents the one-sided significance level.	`0.05`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	`'z-phat'`
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`
`direction`	`Literal['greater', 'less'] \| None`	The direction for the proportion under the null hypothesis relative to the proportion under the alternative hypothesis. `'greater'`: Search for the null proportion greater than the alternative proportion. `'less'`: Search for the null proportion less than the alternative proportion. Note If `alternative` is `'two-sided'`, this parameter is required. If `alternative` is `'greater'`, the search direction is automatically inferred to be `'less'`, and this parameter is ignored. If `alternative` is `'less'`, the search direction is automatically inferred to be `'greater'`, and this parameter is ignored.	`None`

Returns:

Name	Type	Description
`float`	`float`	The required proportion under the null hypothesis.

Raises:

Type	Description
`ValueError`	If `alternative` is `'two-sided'` but `direction` is not specified.