pystatpower.models.proportion.single.equivalence ¶

Functions:

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

solve_power ¶

solve_power(
    *,
    null_proportion: float,
    proportion: float,
    margin_lower: float,
    margin_upper: float,
    size: int,
    alpha: float = 0.025,
    phat: bool = True,
    continuity_correction: bool = False,
) -> float

Calculate the statistical power for a one-sample proportion equivalence 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_lower`	`float`	Lower equivalence margin (\(\delta_1\)), a negative value must be specified.	required
`margin_upper`	`float`	Upper equivalence margin (\(\delta_2\)), a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alpha`	`float`	One-sided significance level.	`0.025`
`phat`	`bool`	Whether to use the alternative proportion \(p\) to calculate the standard deviation.	`True`
`continuity_correction`	`bool`	Whether to apply Yate's continuity correction.	`False`

Returns:

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

solve_size ¶

solve_size(
    *,
    null_proportion: float,
    proportion: float,
    margin_lower: float,
    margin_upper: float,
    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 equivalence 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_lower`	`float`	Lower equivalence margin (\(\delta_1\)), a negative value must be specified.	required
`margin_upper`	`float`	Upper equivalence margin (\(\delta_2\)), a positive value must be specified.	required
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Whether to use the alternative proportion \(p\) to calculate the standard deviation.	`True`
`continuity_correction`	`bool`	Whether to apply Yate's continuity correction.	`False`

Returns:

Type	Description
`int`	The required sample size.

solve_null_proportion ¶

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

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

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis (\(p\)).	required
`margin_lower`	`float`	Lower equivalence margin (\(\delta_1\)), a negative value must be specified.	required
`margin_upper`	`float`	Upper equivalence margin (\(\delta_2\)), a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Whether to use the alternative proportion \(p\) to calculate the standard deviation.	`True`
`continuity_correction`	`bool`	Whether to apply Yate's continuity correction.	`False`
`search_direction`	`Literal['lower', 'upper']`	The direction to search for the null proportion relative to the maximum power point (\(p_{\text{argmax}}\)), if two valid solutions exist. `'lower'`: Search for \(p_0\) in the interval below \(p_{\text{argmax}}\). `'upper'`: Search for \(p_0\) in the interval above \(p_{\text{argmax}}\). If \(p\) itself satisfies the target power, this parameter is ignored and \(p\) is returned directly.	`'upper'`

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 equivalence margins (\(\delta_1\), \(\delta_2\)) to ensure the alternative hypothesis remains plausible.

When the target power intersects the power curve at two points, the search spaces are partitioned by the maximum power point (\(p_{\text{argmax}}\)):

if search_direction='lower': The interval is \((\operatorname{max}(p-\delta_2, -\delta_1, 0), p_{\text{argmax}})\)
if search_direction='upper': The interval is \((p_{\text{argmax}}, \operatorname{min}(p-\delta_1, 1-\delta_2, 1))\)

where \(p_{\text{argmax}}\) is the specific null proportion that maximizes the power function (or minimizes the negative power function).

solve_proportion ¶

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

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

Parameters:

Name	Type	Description	Default
`null_proportion`	`float`	Proportion under the null hypothesis (\(p_0\)).	required
`margin_lower`	`float`	Lower equivalence margin (\(\delta_1\)), a negative value must be specified.	required
`margin_upper`	`float`	Upper equivalence margin (\(\delta_2\)), a positive value must be specified.	required
`size`	`int`	Sample size.	required
`alpha`	`float`	One-sided significance level.	`0.025`
`power`	`float`	Power of the test.	`0.8`
`phat`	`bool`	Whether to use the alternative proportion \(p\) to calculate the standard deviation.	`True`
`continuity_correction`	`bool`	Whether to apply Yate's continuity correction.	`False`
`search_direction`	`Literal['lower', 'upper']`	The direction to search for the proportion relative to the maximum power point (\(p_{\text{argmax}}\)), if two valid solutions exist. `lower`: Search for \(p\) in the interval below \(p_{\text{argmax}}\). `upper`: Search for \(p\) in the interval above \(p_{\text{argmax}}\). If \(p_0\) itself satisfies the target power, this parameter is ignored and \(p_0\) is returned directly.	`'upper'`

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\)) and the equivalence margins (\(\delta_1\), \(\delta_2\)) to ensure the alternative hypothesis remains plausible.

When the target power intersects the power curve at two points, the search spaces are partitioned by the maximum power point (\(p_{\text{argmax}}\)):

if search_direction='lower': The interval is \((\operatorname{max}(p_0+\delta_1, 0), p_{\text{argmax}})\)
if search_direction='upper': The interval is \((p_{\text{argmax}}, \operatorname{min}(p_0+\delta_2, 1))\)

where \(p_{\text{argmax}}\) is the specific alternative proportion that maximizes the power function (or minimizes the negative power function).