pystatpower.models.proportion.independent.noninferiority ¶

Functions:

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

solve_power ¶

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

Calculate the statistical 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\)) provide a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) provide a positive value if a higher proportion is worse (e.g., 0.05 for a 5% non-inferiority margin in mortality rates)	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level.	`0.05`
`pooled`	`bool`	If True, use the pooled variance estimator.	`False`
`continuity_correction`	`bool`	If True, applies Yates' continuity correction.	`False`

Returns:

Type	Description
`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 required sample size 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\)) provide a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) provide a positive value if a higher proportion is worse (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\)).	`1`
`alpha`	`float`	One-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator.	`False`
`continuity_correction`	`bool`	If True, applies Yates' continuity correction.	`False`

Returns:

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

solve_treatment_proportion ¶

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

Estimate the required proportion 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\)) provide a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) provide a positive value if a higher proportion is worse (e.g., 0.05 for a 5% non-inferiority margin in mortality rates)	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator.	`False`
`continuity_correction`	`bool`	If True, applies Yates' continuity correction.	`False`

Returns:

Type	Description
`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: int,
    reference_size: int,
    alpha: float = 0.05,
    power: float = 0.8,
    pooled: bool = False,
    continuity_correction: bool = False,
) -> float

Estimate the required proportion 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\)) provide a negative value if a higher proportion is better (e.g., -0.10 for a -10% non-inferiority margin in cure rates) provide a positive value if a higher proportion is worse (e.g., 0.05 for a 5% non-inferiority margin in mortality rates)	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator.	`False`
`continuity_correction`	`bool`	If True, applies Yates' continuity correction.	`False`

Returns:

Type	Description
`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: int,
    reference_size: int,
    alpha: float = 0.05,
    power: float = 0.8,
    pooled: bool = False,
    continuity_correction: bool = False,
    margin_selection: Literal[
        "positive", "negative"
    ] = "negative",
) -> float

Estimate the required margin 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`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alpha`	`float`	One-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`pooled`	`bool`	If True, use the pooled variance estimator.	`False`
`continuity_correction`	`bool`	If True, applied continuity correction.	`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). Note: If only one solution exists, this parameter is ignored.	`'negative'`

Returns:

Type	Description
`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 \geqslant 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 \leqslant p_2 \end{cases} \]