pystatpower.proportion.independent.noninferiority ¶

FUNCTION	DESCRIPTION
`solve_power`	Calculate the statistical power.
`solve_size`	Estimate the required sample size.
`solve_treatment_proportion`	Estimate the required proportion in the treatment group.
`solve_reference_proportion`	Estimate the required proportion in the reference group.
`solve_margin`	Estimate the required non-inferiority margin.

solve_power ¶

solve_power(
    *,
    treatment_proportion: float,
    reference_proportion: float,
    margin: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    method: Literal["z-pooled", "z-unpooled"] = "z-unpooled",
    continuity_correction: bool = False,
) -> float

Calculate the statistical power.

PARAMETER	DESCRIPTION
`treatment_proportion`	Proportion in the treatment group. TYPE: `float`
`reference_proportion`	Proportion in the reference group. TYPE: `float`
`margin`	The non-inferiority margin. Tip Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter as either positive or negative, as you prefer. Internally, the value of `margin` is converted before actual calculation takes place. If `alternative` is `'greater'`, the internally used margin is `-abs(margin)`. If `alternative` is `'less'`, the internally used margin is `abs(margin)`. TYPE: `float`
`treatment_size`	Sample size in the treatment group. TYPE: `int`
`reference_size`	Sample size in the reference group. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(p_1 - p_2 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p_1 - p_2 < \delta \ (\delta > 0)\). TYPE: `Literal['greater', 'less']`
`alpha`	Significance level. The non-inferiority test is a one-sided test, with a significance level of 0.025 being commonly used. TYPE: `float` DEFAULT: `0.025`
`method`	The method used to construct the test statistic. `'z-pooled'`: Z-test using pooled variance. `'z-unpooled'`: Z-test using unpooled variance. TYPE: `Literal['z-pooled', 'z-unpooled']` DEFAULT: `'z-unpooled'`
`continuity_correction`	Wether to apply Yates' continuity correction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`float`	The statistical power of the test.

solve_size ¶

solve_size(
    *,
    treatment_proportion: float,
    reference_proportion: float,
    margin: float,
    alternative: Literal["greater", "less"],
    ratio: float = 1,
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-pooled", "z-unpooled"] = "z-unpooled",
    continuity_correction: bool = False,
) -> tuple[int, int]

Estimate the required sample size.

PARAMETER	DESCRIPTION
`treatment_proportion`	Proportion in the treatment group. TYPE: `float`
`reference_proportion`	Proportion in the reference group. TYPE: `float`
`margin`	The non-inferiority margin. Tip Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter as either positive or negative, as you prefer. Internally, the value of `margin` is converted before actual calculation takes place. If `alternative` is `'greater'`, the internally used margin is `-abs(margin)`. If `alternative` is `'less'`, the internally used margin is `abs(margin)`. TYPE: `float`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(p_1 - p_2 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p_1 - p_2 < \delta \ (\delta > 0)\). TYPE: `Literal['greater', 'less']`
`ratio`	Ratio of sample sizes in the treatment and reference groups. TYPE: `float` DEFAULT: `1`
`alpha`	Significance level. The non-inferiority test is a one-sided test, with a significance level of 0.025 being commonly used. TYPE: `float` DEFAULT: `0.025`
`power`	Expected statistical power. 0.8 is a commonly used value for statistical power. TYPE: `float` DEFAULT: `0.8`
`method`	The method used to construct the test statistic. `'z-pooled'`: Z-test using pooled variance. `'z-unpooled'`: Z-test using unpooled variance. TYPE: `Literal['z-pooled', 'z-unpooled']` DEFAULT: `'z-unpooled'`
`continuity_correction`	Wether to apply Yates' continuity correction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`tuple[int, int]`	The required sample sizes in the treatment and reference groups, respectively.

solve_treatment_proportion ¶

solve_treatment_proportion(
    *,
    reference_proportion: float,
    margin: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-pooled", "z-unpooled"] = "z-unpooled",
    continuity_correction: bool = False,
) -> float

Estimate the required proportion in the treatment group.

PARAMETER	DESCRIPTION
`reference_proportion`	Proportion in the reference group. TYPE: `float`
`margin`	The non-inferiority margin. Tip Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter as either positive or negative, as you prefer. Internally, the value of `margin` is converted before actual calculation takes place. If `alternative` is `'greater'`, the internally used margin is `-abs(margin)`. If `alternative` is `'less'`, the internally used margin is `abs(margin)`. TYPE: `float`
`treatment_size`	Sample size in the treatment group. TYPE: `int`
`reference_size`	Sample size in the reference group. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(p_1 - p_2 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p_1 - p_2 < \delta \ (\delta > 0)\). TYPE: `Literal['greater', 'less']`
`alpha`	Significance level. The non-inferiority test is a one-sided test, with a significance level of 0.025 being commonly used. TYPE: `float` DEFAULT: `0.025`
`power`	Expected statistical power. 0.8 is a commonly used value for statistical power. TYPE: `float` DEFAULT: `0.8`
`method`	The method used to construct the test statistic. `'z-pooled'`: Z-test using pooled variance. `'z-unpooled'`: Z-test using unpooled variance. TYPE: `Literal['z-pooled', 'z-unpooled']` DEFAULT: `'z-unpooled'`
`continuity_correction`	Wether to apply Yates' continuity correction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`float`	The required proportion in the treatment group.

Notes

The value range of the treatment proportion \(p_1\) is determined by the reference proportion \(p_2\) and the non-inferiority margin \(\delta\).

If alternative is 'greater', that is, higher proportions are better, we have:

\[ \begin{cases} p_1 > p_0 + \delta \\ 0 < p_1 < 1 \\ \delta < 0 \end{cases} \ \Rightarrow \operatorname{max}(p_2 + \delta, 0) < p_1 < 1 \]

If alternative is 'less', that is, higher proportions are worse, we have:

\[ \begin{cases} p_1 < p_2 + \delta \\ 0 < p_1 < 1 \\ \delta > 0 \end{cases} \ \Rightarrow 0 < p_1 < \operatorname{min}(p_2 + \delta, 1) \]

solve_reference_proportion ¶

solve_reference_proportion(
    *,
    treatment_proportion: float,
    margin: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-pooled", "z-unpooled"] = "z-unpooled",
    continuity_correction: bool = False,
) -> float

Estimate the required proportion in the reference group.

PARAMETER	DESCRIPTION
`treatment_proportion`	Proportion in the treatment group. TYPE: `float`
`margin`	The non-inferiority margin. Tip Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter as either positive or negative, as you prefer. Internally, the value of `margin` is converted before actual calculation takes place. If `alternative` is `'greater'`, the internally used margin is `-abs(margin)`. If `alternative` is `'less'`, the internally used margin is `abs(margin)`. TYPE: `float`
`treatment_size`	Sample size in the treatment group. TYPE: `int`
`reference_size`	Sample size in the reference group. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(p_1 - p_2 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p_1 - p_2 < \delta \ (\delta > 0)\). TYPE: `Literal['greater', 'less']`
`alpha`	Significance level. The non-inferiority test is a one-sided test, with a significance level of 0.025 being commonly used. TYPE: `float` DEFAULT: `0.025`
`power`	Expected statistical power. 0.8 is a commonly used value for statistical power. TYPE: `float` DEFAULT: `0.8`
`method`	The method used to construct the test statistic. `'z-pooled'`: Z-test using pooled variance. `'z-unpooled'`: Z-test using unpooled variance. TYPE: `Literal['z-pooled', 'z-unpooled']` DEFAULT: `'z-unpooled'`
`continuity_correction`	Wether to apply Yates' continuity correction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`float`	The required proportion in the reference group.

Notes

The value range of the reference proportion \(p_2\) is determined by the treatment proportion \(p_1\) and the non-inferiority margin \(\delta\).

If alternative is 'greater', that is, higher proportions are better, we have:

\[ \begin{cases} p_2 < p_1 - \delta \\ 0 < p_2 < 1 \\ \delta < 0 \end{cases} \ \Rightarrow 0 < p_2 < \operatorname{min}(p_1 - \delta, 1) \]

If alternative is 'less', that is, higher proportions are worse, we have:

\[ \begin{cases} p_2 > p_1 - \delta \\ 0 < p_2 < 1 \\ \delta > 0 \end{cases} \ \Rightarrow \operatorname{max}(p_1 - \delta, 0) < p_2 < 1 \]

solve_margin ¶

solve_margin(
    *,
    treatment_proportion: float,
    reference_proportion: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-pooled", "z-unpooled"] = "z-unpooled",
    continuity_correction: bool = False,
) -> float

Estimate the required non-inferiority margin.

PARAMETER	DESCRIPTION
`treatment_proportion`	Proportion in the treatment group. TYPE: `float`
`reference_proportion`	Proportion in the reference group. TYPE: `float`
`treatment_size`	Sample size in the treatment group. TYPE: `int`
`reference_size`	Sample size in the reference group. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(p_1 - p_2 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p_1 - p_2 < \delta \ (\delta > 0)\). TYPE: `Literal['greater', 'less']`
`alpha`	Significance level. The non-inferiority test is a one-sided test, with a significance level of 0.025 being commonly used. TYPE: `float` DEFAULT: `0.025`
`power`	Expected statistical power. 0.8 is a commonly used value for statistical power. TYPE: `float` DEFAULT: `0.8`
`method`	The method used to construct the test statistic. `'z-pooled'`: Z-test using pooled variance. `'z-unpooled'`: Z-test using unpooled variance. TYPE: `Literal['z-pooled', 'z-unpooled']` DEFAULT: `'z-unpooled'`
`continuity_correction`	Wether to apply Yates' continuity correction. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`float`	The required non-inferiority margin.

Notes

The value range of the non-inferiority margin \(\delta\) is determined by the treatment proportion \(p_1\) and the reference proportion \(p_2\).

If alternative is 'greater', that is, higher proportions are better, we have:

\[ \begin{cases} \delta < p_1 - p_2 \\ \delta < 0 \end{cases} \ \Rightarrow -1 < \delta < \operatorname{min}(p_1 - p_2, 0) \]

If alternative is 'less', that is, higher proportions are worse, we have:

\[ \begin{cases} \delta > p_1 - p_2 \\ \delta > 0 \end{cases} \ \Rightarrow \operatorname{max}(p_1 - \delta, 0) < \delta < 1 \]