pystatpower.models.proportion.independent.noninferiority ¶

Functions:

Name	Description
`solve_power`	Calculate the power for a non-inferiority test of two independent proportions.
`solve_size`	Estimate the sample size required for a non-inferiority test of two independent proportions.
`solve_treatment_proportion`	Estimate the proportion required in the treatment group for a non-inferiority test of two independent proportions.
`solve_reference_proportion`	Estimate the proportion required in the reference group for a non-inferiority test of two independent proportions.
`solve_margin`	Estimate the non-inferiority margin required for a non-inferiority 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., 0.05 for a 5% non-inferiority 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, applies Yates' 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., 0.05 for a 5% non-inferiority 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, applies Yates' 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., 0.05 for a 5% non-inferiority 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, applies Yates' 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(\max\left(p_2+\delta, \ 0\right), 1\right) & , \text{if } \delta < 0 \\ \left(0, \ \min\left(p_2+\delta, \ 1\right)\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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) Use a negative value if a lower proportion is better (e.g., 0.05 for a 5% non-inferiority 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, applies Yates' 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} (-\delta, \ p_1) \cup \left(\max\left(p_1, \ -\delta\right), \min\left(p_1-\delta, \ 1\right)\right) & , \text{if } \delta < 0 \\ (p_1, \ 1-\delta) \cup \left(\max\left(p_1-\delta, \ 0\right), \ \min\left(p_1, \ 1-\delta\right)\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, margin_selection: Literal['positive', 'negative'] = 'negative') -> float

Estimate the non-inferiority margin required for a non-inferiority 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`
`margin_selection`	`Literal['positive', 'negative']`	Selection criterion when two mathematically valid solutions exist (one for "higher is better", one for "worse") "positive": Returns the positive margin (typically for mortality). "negative": Returns the negative margin (typically for cure rates). Defaults to "negative". Note: If only one solution exists, this parameter is ignored.	`'negative'`

Returns:

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

Notes

The non-inferiority margin should be negative when higher is better, otherwise positive.

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

If higher proportion is better:

\[ \text{Search Interval} = \begin{cases} (-p_2, \ 0) & , \text{if } p_1 \ge p_2 \\ (-p_2, \ p_1-p_2) & , \text{if } p_1 \lt p_2 \end{cases} \]

If higher proportion is worse:

\[ \text{Search Interval} = \begin{cases} (p_1-p_2, \ 1-p_2) & , \text{if } p_1 \gt p_2 \\ (0, \ 1-p_2) & , \text{if } p_1 \le p_2 \end{cases} \]