pystatpower.models.proportion.single.superiority ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for a one-sample proportion superiority test.
`solve_size`	Estimate the required sample size for a one-sample proportion superiority test.
`solve_null_proportion`	Estimate the required proportion under the null hypothesis (\(p_0\)) for a one-sample proportion superiority test.
`solve_proportion`	Estimate the required proportion under the alternative hypothesis (\(p\)) for a one-sample proportion superiority test.
`solve_margin`	Estimate the required margin (\(\delta\)) for a one-sample proportion superiority test.

solve_power ¶

solve_power(
    *,
    null_proportion: float,
    proportion: float,
    margin: float,
    size: int,
    alternative: Literal["lower", "upper"] = "upper",
    alpha: float = 0.025,
    phat: bool = True,
    continuity_correction: bool = False,
) -> float

Calculate the statistical power for a one-sample proportion superiority test.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis (\(p_0\)).	required
`proportion`	`float`	Proportion under the alternative hypothesis (\(p\)).	required
`margin`	`float`	superiority margin (\(\delta\)). If `alternative` is `lower`, a negative value must be specified. If `alternative` is `upper`, a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['lower', 'upper']`	Type of the alternative hypothesis: `'lower'`: Lower one-tailed test (\(p - p_0 < \delta\)), usually used when higher proportions are worse. `'upper'`: Upper one-tailed test (\(p - p_0 > \delta\)), usually used when higher proportions are better.	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`phat`	`bool`	Specify whether to use the value of \(p\) to calculate the standard deviation or not.	`True`
`continuity_correction`	`bool`	Specify whether to apply Yate's continuity correction or not.	`False`

Returns:

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

solve_size ¶

solve_size(
    *,
    null_proportion: float,
    proportion: float,
    margin: float,
    alternative: Literal["lower", "upper"] = "upper",
    alpha: float = 0.025,
    power: float = 0.8,
    phat: bool = True,
    continuity_correction: bool = False,
) -> int

Estimate the required sample size for a one-sample proportion superiority test.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis (\(p_0\)).	required
`proportion`	`float`	Proportion under the alternative hypothesis (\(p\)).	required
`margin`	`float`	superiority margin (\(\delta\)). If `alternative` is `lower`, a negative value must be specified. If `alternative` is `upper`, a positive value must be specified.	required
`alternative`	`Literal['lower', 'upper']`	Type of the alternative hypothesis: `'lower'`: Lower one-tailed test (\(p - p_0 < \delta\)), usually used when higher proportions are worse. `'upper'`: Upper one-tailed test (\(p - p_0 > \delta\)), usually used when higher proportions are better.	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Specify whether to use the value of \(p\) to calculate the standard deviation or not.	`True`
`continuity_correction`	`bool`	Specify whether to apply Yate's continuity correction or not.	`False`

Returns:

Type	Description
`int`	The required sample size.

solve_null_proportion ¶

solve_null_proportion(
    *,
    proportion: float,
    margin: float,
    size: int,
    alternative: Literal["lower", "upper"] = "upper",
    alpha: float = 0.025,
    power: float = 0.8,
    phat: bool = True,
    continuity_correction: bool = False,
) -> float

Estimate the required proportion under the null hypothesis (\(p_0\)) for a one-sample proportion superiority test.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis (\(p\)).	required
`margin`	`float`	superiority margin (\(\delta\)). If `alternative` is `lower`, a negative value must be specified. If `alternative` is `upper`, a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['lower', 'upper']`	Type of the alternative hypothesis: `'lower'`: Lower one-tailed test (\(p - p_0 < \delta\)), usually used when higher proportions are worse. `'upper'`: Upper one-tailed test (\(p - p_0 > \delta\)), usually used when higher proportions are better.	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Specify whether to use the value of \(p\) to calculate the standard deviation or not.	`True`
`continuity_correction`	`bool`	Specify whether to apply Yate's continuity correction or not.	`False`

Returns:

Type	Description
`float`	The required proportion under the null hypothesis (\(p_0\)).

Notes

The search interval for the null proportion (\(p_0\)) is constrained by the alternative proportion (\(p\)) and the margin (\(\delta\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} (\operatorname{max}(p-\delta, -\delta), 1) &, \text{if lower one-tailed test} \\ (0, \operatorname{min}(p-\delta, 1-\delta)) &, \text{if upper one-tailed test} \end{cases} \]

solve_proportion ¶

solve_proportion(
    *,
    null_proportion: float,
    margin: float,
    size: int,
    alternative: Literal["lower", "upper"] = "upper",
    alpha: float = 0.025,
    power: float = 0.8,
    phat: bool = True,
    continuity_correction: bool = False,
) -> float

Estimate the required proportion under the alternative hypothesis (\(p\)) for a one-sample proportion superiority test.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis (\(p_0\)).	required
`margin`	`float`	superiority margin (\(\delta\)). If `alternative` is `lower`, a negative value must be specified. If `alternative` is `upper`, a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['lower', 'upper']`	Type of the alternative hypothesis: `'lower'`: Lower one-tailed test (\(p - p_0 < \delta\)), usually used when higher proportions are worse. `'upper'`: Upper one-tailed test (\(p - p_0 > \delta\)), usually used when higher proportions are better.	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Specify whether to use the value of \(p\) to calculate the standard deviation or not.	`True`
`continuity_correction`	`bool`	Specify whether to apply Yate's continuity correction or not.	`False`

Returns:

Type	Description
`float`	The required proportion under the alternative hypothesis (\(p\)).

Notes

The search interval for the alternative proportion (\(p\)) is constrained by the null proportion (\(p_0\)) and the margin (\(\delta\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} (0, p_0+\delta) &, \text{if lower one-tailed test} \\ (p_0+\delta, 1) &, \text{if upper one-tailed test} \end{cases} \]

solve_margin ¶

solve_margin(
    *,
    null_proportion: float,
    proportion: float,
    size: int,
    alternative: Literal["lower", "upper"] = "upper",
    alpha: float = 0.025,
    power: float = 0.8,
    phat: bool = True,
    continuity_correction: bool = False,
) -> float

Estimate the required margin (\(\delta\)) for a one-sample proportion superiority test.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis (\(p_0\)).	required
`proportion`	`float`	Proportion under the alternative hypothesis (\(p\)).	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['lower', 'upper']`	Type of the alternative hypothesis: `'lower'`: Lower one-tailed test (\(p - p_0 < \delta\)), usually used when higher proportions are worse. `'upper'`: Upper one-tailed test (\(p - p_0 > \delta\)), usually used when higher proportions are better.	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Specify whether to use the value of \(p\) to calculate the standard deviation or not.	`True`
`continuity_correction`	`bool`	Specify whether to apply Yate's continuity correction or not.	`False`

Returns:

Type	Description
`float`	The required margin (\(\delta\)).

Notes

The search interval for the margin (\(\delta\)) is constrained by the null proportion (\(p_0\)) and the alternative proportion (\(p\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} (p-p_0, 0] &, \text{if lower one-tailed test} \\ [0, p-p_0) &, \text{if upper one-tailed test} \end{cases} \]