pystatpower.proportion.single.noninferiority ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for a non-inferiority test of one proportion.
`solve_size`	Estimate the required sample size for a non-inferiority test of one proportion.
`solve_proportion`	Estimate the required proportion under the alternative hypothesis for a non-inferiority test of one proportion.
`solve_null_proportion`	Estimate the required proportion under the null hypothesis for a non-inferiority test of one proportion.
`solve_noninferiority_proportion`	Estimate the required non-inferiority proportion for a non-inferiority test of one proportion.
`solve_margin`	Estimate the required margin for a non-inferiority test of one proportion.

solve_power ¶

solve_power(
    *,
    proportion: float,
    null_proportion: float | None = None,
    margin: float | None = None,
    noninferiority_proportion: float | None = None,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool,
) -> float

Calculate the statistical power for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`null_proportion`	`float \| None`	Proportion under the null hypothesis. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `margin`.	`None`
`margin`	`float \| None`	The non-inferiority margin. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `null_proportion`. Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter to be positive or negative as you prefer. Internally, the value of `margin` will be converted before actual calculation. If `alternative` is `'greater'`, the actual margin used internally is `-abs(margin)`. If `alternative` is `'less'`, the actual margin used internally is `abs(margin)`.	`None`
`noninferiority_proportion`	`float \| None`	The non-inferiority proportion. Required if either `null_proportion` or `margin` is omitted.	`None`
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	required

Returns:

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

Raises:

Type	Description
`ValueError`	If `noninferiority_proportion` is omitted, and either `null_proportion` or `margin` is missing.

solve_size ¶

solve_size(
    *,
    proportion: float,
    null_proportion: float | None = None,
    margin: float | None = None,
    noninferiority_proportion: float | None = None,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool = False,
) -> int

Estimate the required sample size for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`null_proportion`	`float \| None`	Proportion under the null hypothesis. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `margin`.	`None`
`margin`	`float \| None`	The non-inferiority margin. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `null_proportion`. Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter to be positive or negative as you prefer. Internally, the value of `margin` will be converted before actual calculation. If `alternative` is `'greater'`, the actual margin used internally is `-abs(margin)`. If `alternative` is `'less'`, the actual margin used internally is `abs(margin)`.	`None`
`noninferiority_proportion`	`float \| None`	The non-inferiority proportion. Required if either `null_proportion` or `margin` is omitted.	`None`
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

Name	Type	Description
`int`	`int`	The required sample size.

Raises:

Type	Description
`ValueError`	If `noninferiority_proportion` is omitted, and either `null_proportion` or `margin` is missing.

solve_proportion ¶

solve_proportion(
    *,
    null_proportion: float | None = None,
    margin: float | None = None,
    noninferiority_proportion: float | None = None,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool = False,
) -> float

Estimate the required proportion under the alternative hypothesis for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`null_proportion`	`float \| None`	Proportion under the null hypothesis. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `margin`.	`None`
`margin`	`float \| None`	The non-inferiority margin. Ignored if `noninferiority_proportion` is specified; otherwise, required alongside `margin`. Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can always specify this parameter to be positive or negative as you prefer. Internally, the value of `margin` will be converted before actual calculation. If `alternative` is `'greater'`, the actual margin used internally is `-abs(margin)`. If `alternative` is `'less'`, the actual margin used internally is `abs(margin)`.	`None`
`noninferiority_proportion`	`float \| None`	The non-inferiority proportion. Required if either `null_proportion` or `margin` is omitted.	`None`
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

Name	Type	Description
`float`	`float`	The required proportion under the alternative hypothesis.

Raises:

Type	Description
`ValueError`	If `noninferiority_proportion` is omitted, and either `null_proportion` or `margin` is missing.

Notes

The value range of the alternative hypothesis proportion \(p\) is determined by the null hypothesis proportion \(p_0\) and the non-inferiority margin \(\delta\).

If \(\delta < 0\), we have:

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

If \(\delta > 0\), we have:

\[ \begin{cases} p < p_0 + \delta \\ 0 < p < 1 \end{cases} \Rightarrow 0 < p_0 < \operatorname{min}(p_0 + \delta, 1) \]

solve_null_proportion ¶

solve_null_proportion(
    *,
    proportion: float,
    margin: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool = False,
) -> float

Estimate the required proportion under the null hypothesis for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`margin`	`float`	The non-inferiority margin. Regardless of whether `alternative` is specified as `'greater'` or `'less'`, you can alwanys specify this parameter to be positive or negative as you prefer. Internally, the value of `margin` will be converted before actual calculation. If `alternative` is `'greater'`, the actual margin used internally is `-abs(margin)`. If `alternative` is `'less'`, the actual margin used internally is `abs(margin)`.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

Name	Type	Description
`float`	`float`	The required proportion under the null hypothesis.

Notes

The value range of the null hypothesis proportion \(p_0\) is determined by the alternative hypothesis proportion \(p\) and the non-inferiority margin \(\delta\).

If \(\delta < 0\), we have:

\[ \begin{cases} p_0 < p - \delta \\ 0 < p_0 < 1 \\ 0 < p_0 + \delta < 1 \end{cases} \Rightarrow -\delta < p_0 < \operatorname{min}(p - \delta, 1) \]

If \(\delta > 0\), we have:

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

solve_noninferiority_proportion ¶

solve_noninferiority_proportion(
    *,
    proportion: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool = False,
) -> float

Estimate the required non-inferiority proportion for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

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

Notes

The value range of the non-inferiority hypothesis proportion \(p_{\text{noninf}}\) is determined by the alternative hypothesis proportion \(p\).

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

\[ \begin{cases} p_{\text{noninf}} < p \\ 0 < p_{\text{noninf}} < 1 \\ \end{cases} \ \Rightarrow 0 < p_{\text{noninf}} < p \]

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

\[ \begin{cases} p_{\text{noninf}} > p \\ 0 < p_{\text{noninf}} < 1 \\ \end{cases} \ \Rightarrow p < p_{\text{noninf}} < 1 \]

solve_margin ¶

solve_margin(
    *,
    proportion: float,
    null_proportion: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    method: Literal["z-p0", "z-phat"],
    continuity_correction: bool = False,
) -> float

Estimate the required margin for a non-inferiority test of one proportion.

Parameters:

Name	Type	Description	Default
`proportion`	`float`	Proportion under the alternative hypothesis.	required
`null_proportion`	`float`	Proportion under the null hypothesis.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis: If `alternative` is `'greater'`, the alternative hypothesis is \(p - p_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(p - p_0 < \delta \ (\delta > 0)\)	required
`alpha`	`float`	Significance level. The non-inferiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`power`	`float`	Expected statistical power. 0.8 is a commonly used statistical power.	`0.8`
`method`	`Literal['z-p0', 'z-phat']`	The method used to construct the test statistic. `'z-p0'`: Standard normal distribution (large sample approximation), using p0 to calculate the variance. `'z-phat'`: Standard normal distribution (large sample approximation), using phat to calculate the variance.	required
`continuity_correction`	`bool`	Whether to apply the continuity correction.	`False`

Returns:

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

Notes

The value range of the non-inferiority margin \(\delta\) is determined by the alternative hypothesis proportion \(p\) and the null hypothesis proportion \(p_0\).

If \(\delta < 0\), we have:

\[ \begin{cases} \delta < p - p_0 \\ 0 < p_0 + \delta < 1 \\ \delta < 0 \end{cases} \Rightarrow -p_0 < \delta < \operatorname{min}(p - p_0, 0) \]

If \(\delta > 0\), we have:

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