pystatpower.models.proportion.independent.superiority ¶

Functions:

Name	Description
`solve_power`	Calculate the power for a superiority test of two independent proportions.
`solve_size`	Estimate the sample size required for a superiority test of two independent proportions.
`solve_treatment_proportion`	Estimate the proportion required in the treatment group for a superiority test of two independent proportions.
`solve_reference_proportion`	Estimate the proportion required in the reference group for a superiority test of two independent proportions.
`solve_margin`	Estimate the superiority margin required for a superiority test of two independent proportions.

solve_power ¶

solve_power(treatment_proportion: float, reference_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, pooled: bool = False, continuity_correction: bool = False) -> float

Calculate the power for a superiority test of two independent proportions.

Parameters:

Name	Type	Description	Default
`treatment_proportion`	`float`	Actual proportion in the treatment group (\(p_1\)). Must be between 0 and 1.	required
`reference_proportion`	`float`	Actual proportion in the reference group (\(p_2\)). Must be between 0 and 1.	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher proportion is better (e.g., 0.10 for a 10% superiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., -0.05 for a -5% superiority margin in mortality rates)	required
`treatment_size`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level. Defaults to 0.05.	`0.05`
`pooled`	`bool`	If True, use the pooled variance estimator. Defaults to False.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction. Defaults to False.	`False`

Returns:

Name	Type	Description
`float`	`float`	Power of the test.

solve_size ¶

solve_size(treatment_proportion: float, reference_proportion: float, margin: float, ratio: float = 1, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> tuple[int, int]

Estimate the sample size required for a superiority test of two independent proportions.

Parameters:

Name	Type	Description	Default
`treatment_proportion`	`float`	Expected proportion in the treatment group (\(p_1\)). Must be between 0 and 1.	required
`reference_proportion`	`float`	Expected proportion in the reference group (\(p_2\)). Must be between 0 and 1.	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher proportion is better (e.g., 0.10 for a 10% superiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., -0.05 for a -5% superiority margin in mortality rates)	required
`ratio`	`float`	Ratio of treatment sample size to reference sample size (\(k = n_1 / n_2\)). Defaults to 1.	`1`
`alpha`	`float`	One-sided significance level. Defaults to 0.05.	`0.05`
`power`	`float`	Desired statistical power. Defaults to 0.80.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator. Defaults to False.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction. Defaults to False.	`False`

Returns:

Type	Description
`tuple[int, int]`	tuple[int, int]: The required sample sizes for the treatment and reference groups, respectively.

Notes

If continuity_correction is enabled, the power function may not be monotonic at very small sample sizes. The function identifies a safe lower bound to ensure convergence of the root-finding algorithm (Brent's method).

solve_treatment_proportion ¶

solve_treatment_proportion(reference_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> float

Estimate the proportion required in the treatment group for a superiority test of two independent proportions.

Parameters:

Name	Type	Description	Default
`reference_proportion`	`float`	Expected proportion in the reference group (\(p_2\)). Must be between 0 and 1.	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher proportion is better (e.g., 0.10 for a 10% superiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., -0.05 for a -5% superiority margin in mortality rates)	required
`treatment_size`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level. Defaults to 0.05.	`0.05`
`power`	`float`	Desired statistical power. Defaults to 0.80.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator. Defaults to False.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction. Defaults to False.	`False`

Returns:

Name	Type	Description
`float`	`float`	The required proportion in the treatment group.

Notes

The search interval for treatment proportion (\(p_1\)) is constrained by the reference proportion (\(p_2\)) and the margin (\(\delta\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} \left(0, \ p_2+\delta\right), & \text{if } \delta < 0 \\ \left(p_2, \ 1\right), & \text{if } \delta = 0 \\ \left(p_2+\delta, \ 1\right), & \text{if } \delta > 0 \end{cases} \]

solve_reference_proportion ¶

solve_reference_proportion(treatment_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> float

Estimate the proportion required in the reference group for a superiority test of two independent proportions.

Parameters:

Name	Type	Description	Default
`treatment_proportion`	`float`	Expected proportion in the treatment group (\(p_1\)). Must be between 0 and 1.	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher proportion is better (e.g., 0.10 for a 10% superiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., -0.05 for a -5% superiority margin in mortality rates)	required
`treatment_size`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level. Defaults to 0.05.	`0.05`
`power`	`float`	Desired statistical power. Defaults to 0.80.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator. Defaults to False.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction. Defaults to False.	`False`

Returns:

Name	Type	Description
`float`	`float`	The required proportion in the reference group.

Notes

The search interval for reference proportion (\(p_2\)) is constrained by the treatment proportion (\(p_1\)) and the margin (\(\delta\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} \left(p_1-\delta, \ 1\right), & \text{if } \delta < 0 \\ \left(0, \ p_1\right), & \text{if } \delta = 0 \\ \left(0, \ p_1-\delta\right), & \text{if } \delta > 0 \end{cases} \]

solve_margin ¶

solve_margin(treatment_proportion: float, reference_proportion: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> float

Estimate the superiority margin required for a superiority test of two independent proportions.

Parameters:

Name	Type	Description	Default
`treatment_proportion`	`float`	Expected proportion in the treatment group (\(p_1\)). Must be between 0 and 1.	required
`reference_proportion`	`float`	Expected proportion in the reference group (\(p_2\)). Must be between 0 and 1.	required
`treatment_size`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level. Defaults to 0.05.	`0.05`
`power`	`float`	Desired statistical power. Defaults to 0.80.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator. Defaults to False.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction. Defaults to False.	`False`

Returns:

Name	Type	Description
`margin`	`float`	The required non-inferiority margin.

Notes

The search interval for superiority margin (\(\delta\)) is constrained by the treatment proportion (\(p_1\)) and the reference proportion (\(p_2\)) to ensure the alternative hypothesis remains plausible:

\[ \text{Search Interval} = \begin{cases} \left(p_1-p_2, \ 0\right), & \text{if } p_1 < p_2 \\ \left[0, \ p_1-p_2\right), & \text{if } p_1 > p_2 \\ \end{cases} \]