pystatpower.mean.single.noninferiority ¶

FUNCTION	DESCRIPTION
`solve_power`	Calculate the statistical power.
`solve_size`	Estimate the required sample size.
`solve_mean`	Estimate the required mean under the alternative hypothesis.
`solve_null_mean`	Estimate the required mean under the null hypothesis.
`solve_margin`	Estimate the required non-inferiority margin.
`solve_diff`	Estimate the required mean difference.
`solve_noninferiority_mean`	Estimate the required non-inferiority mean.
`solve_offset`	Estimate the required offset.
`solve_std`	Estimate the required standard deviation.

solve_power ¶

solve_power(
    *,
    mean: float | None = None,
    null_mean: float | None = None,
    margin: float | None = None,
    diff: float | None = None,
    noninferiority_mean: float | None = None,
    offset: float | None = None,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    dist: Literal["z", "t"] = "t",
) -> float

Calculate the statistical power.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. This parameter must be used together with `noninferiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `noninferiority_mean`, the `offset` is calculated as `mean` - `noninferiority_mean`. If you specify this parameter along with `null_mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`null_mean`	Mean under the null hypothesis. This parameter must be used together with `mean` and `margin` to calculate the `offset`. If you specify this parameter along with `mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`margin`	The non-inferiority margin. This parameter must be used together with `diff`, or alternatively, in conjunction with `mean` and `null_mean` to calculate the `offset`. If you specify this parameter along with `diff`, the `offset` is calculated as `diff` - `margin`. If you specify this parameter along with `mean` and `null_mean`, the `offset` is calculated as `mean` - `null_mean` - `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 \| None` DEFAULT: `None`
`diff`	Difference between the mean under the alternative hypothesis and the null hypothesis. This parameter must be used together with `margin` to calculate the `offset`. If you specify this parameter along with `margin`, the `offset` if calculated as `diff` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`noninferiority_mean`	The non-inferiority mean. If `alternative` is `'greater'`, the non-inferiority mean is defined as the smallest mean that is less than the null hypothesis mean yet still considered non-inferior. If `alternative` is `'less'`, the non-inferiority mean is defined as the largest mean that is greater than the null hypothesis mean yet still considered non-inferior. This parameter must be used together with `mean` to calculate the `offset`. If you specify this parameter along with `mean`, the `offset` if calculated as `mean` - `noninferiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the non-inferiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `noninferiority_mean` are ignored. TYPE: `float \| None` DEFAULT: `None`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

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

RAISES	DESCRIPTION
`ValueError`	The given set of parameters is insufficient to determine the offset.

solve_size ¶

solve_size(
    *,
    mean: float | None = None,
    null_mean: float | None = None,
    margin: float | None = None,
    diff: float | None = None,
    noninferiority_mean: float | None = None,
    offset: float | None = None,
    std: float,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> int

Estimate the required sample size.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. This parameter must be used together with `noninferiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `noninferiority_mean`, the `offset` is calculated as `mean` - `noninferiority_mean`. If you specify this parameter along with `null_mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`null_mean`	Mean under the null hypothesis. This parameter must be used together with `mean` and `margin` to calculate the `offset`. If you specify this parameter along with `mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`margin`	The non-inferiority margin. This parameter must be used together with `diff`, or alternatively, in conjunction with `mean` and `null_mean` to calculate the `offset`. If you specify this parameter along with `diff`, the `offset` is calculated as `diff` - `margin`. If you specify this parameter along with `mean` and `null_mean`, the `offset` is calculated as `mean` - `null_mean` - `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 \| None` DEFAULT: `None`
`diff`	Difference between the mean under the alternative hypothesis and the null hypothesis. This parameter must be used together with `margin` to calculate the `offset`. If you specify this parameter along with `margin`, the `offset` if calculated as `diff` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`noninferiority_mean`	The non-inferiority mean. If `alternative` is `'greater'`, the non-inferiority mean is defined as the smallest mean that is less than the null hypothesis mean yet still considered non-inferior. If `alternative` is `'less'`, the non-inferiority mean is defined as the largest mean that is greater than the null hypothesis mean yet still considered non-inferior. This parameter must be used together with `mean` to calculate the `offset`. If you specify this parameter along with `mean`, the `offset` if calculated as `mean` - `noninferiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the non-inferiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `noninferiority_mean` are ignored. TYPE: `float \| None` DEFAULT: `None`
`std`	Standard deviation. TYPE: `float`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`int`	The required sample size.

RAISES	DESCRIPTION
`ValueError`	The given set of parameters is insufficient to determine the offset.

solve_mean ¶

solve_mean(
    *,
    null_mean: float | None = None,
    margin: float | None = None,
    noninferiority_mean: float | None = None,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required mean under the alternative hypothesis.

PARAMETER	DESCRIPTION
`null_mean`	Mean under the null hypothesis. This parameter must be used together with `margin` to calculate the `noninferiority_mean` If you specify this parameter along with `margin`, the `noninferiority_mean` is calculated as `null_mean` + `margin`. TYPE: `float \| None` DEFAULT: `None`
`margin`	The non-inferiority margin. This parameter must be used together with `null_mean` to calculate the `noninferiority_mean` If you specify this parameter along with `null_mean`, the `noninferiority_mean` is calculated as `null_mean` + `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 \| None` DEFAULT: `None`
`noninferiority_mean`	The non-inferiority mean. If `alternative` is `'greater'`, the non-inferiority mean is defined as the smallest mean that is less than the null hypothesis mean yet still considered non-inferior. If `alternative` is `'less'`, the non-inferiority mean is defined as the largest mean that is greater than the null hypothesis mean yet still considered non-inferior. If you specify this parameter, both `null_mean` and `mean` are ignored. TYPE: `float \| None` DEFAULT: `None`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`float`	The required mean under the alternative hypothesis.

RAISES	DESCRIPTION
`ValueError`	The given set of parameters is insufficient to determine the noninferiority mean.

solve_null_mean ¶

solve_null_mean(
    *,
    mean: float,
    margin: float,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required mean under the null hypothesis.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. 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`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`float`	The required mean under the null hypothesis.

solve_margin ¶

solve_margin(
    *,
    mean: float | None = None,
    null_mean: float | None = None,
    diff: float | None = None,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required non-inferiority margin.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. This parameter must be used together with `null_mean` to calculate the `diff`. If you specify this parameter along with `null_mean`, the `diff` is calculated as `mean` - `null_mean`. TYPE: `float \| None` DEFAULT: `None`
`null_mean`	Mean under the null hypothesis. This parameter must be used together with `mean` to calculate the `diff`. If you specify this parameter along with `mean`, the `diff` is calculated as `mean` - `null_mean`. TYPE: `float \| None` DEFAULT: `None`
`diff`	Mean difference between the alternative hypothesis and the null hypothesis. If you specify this parameter, both `mean` and `null_mean` are ignored. TYPE: `float \| None` DEFAULT: `None`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`float`	The required non-inferiority margin. If `alternative` is `'greater'`, the returned value is in the range \((-\infty, \hat{\mu} - \hat{\mu}_0)\) If `alternative` is `'less'`, the returned value is in the range \((\hat{\mu} - \hat{\mu}_0, +\infty)\)

RAISES	DESCRIPTION
`ValueError`	The given set of parameters is insufficient to determine the mean difference.

solve_diff ¶

solve_diff(
    *,
    margin: float,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required mean difference.

PARAMETER	DESCRIPTION
`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`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`float`	The required mean difference between the alternative hypothesis and the null hypothesis.

solve_noninferiority_mean ¶

solve_noninferiority_mean(
    *,
    mean: float,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required non-inferiority mean.

If alternative is 'greater', the non-inferiority mean is defined as the smallest mean that is less than the null hypothesis mean yet still considered non-inferior.
If alternative is 'less', the non-inferiority mean is defined as the largest mean that is greater than the null hypothesis mean yet still considered non-inferior.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. TYPE: `float`
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

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

solve_offset ¶

solve_offset(
    *,
    std: float,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required offset.

The offset is defined as the difference between the mean under the alternative hypothesis and the non-inferiority mean.

PARAMETER	DESCRIPTION
`std`	Standard deviation. TYPE: `float`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

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

solve_std ¶

solve_std(
    *,
    mean: float | None = None,
    null_mean: float | None = None,
    margin: float | None = None,
    diff: float | None = None,
    noninferiority_mean: float | None = None,
    offset: float | None = None,
    size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
) -> float

Estimate the required standard deviation.

PARAMETER	DESCRIPTION
`mean`	Mean under the alternative hypothesis. This parameter must be used together with `noninferiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `noninferiority_mean`, the `offset` is calculated as `mean` - `noninferiority_mean`. If you specify this parameter along with `null_mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`null_mean`	Mean under the null hypothesis. This parameter must be used together with `mean` and `margin` to calculate the `offset`. If you specify this parameter along with `mean` and `margin`, the `offset` is calculated as `mean` - `null_mean` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`margin`	The non-inferiority margin. This parameter must be used together with `diff`, or alternatively, in conjunction with `mean` and `null_mean` to calculate the `offset`. If you specify this parameter along with `diff`, the `offset` is calculated as `diff` - `margin`. If you specify this parameter along with `mean` and `null_mean`, the `offset` is calculated as `mean` - `null_mean` - `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 \| None` DEFAULT: `None`
`diff`	Difference between the mean under the alternative hypothesis and the null hypothesis. This parameter must be used together with `margin` to calculate the `offset`. If you specify this parameter along with `margin`, the `offset` if calculated as `diff` - `margin`. TYPE: `float \| None` DEFAULT: `None`
`noninferiority_mean`	The non-inferiority mean. If `alternative` is `'greater'`, the non-inferiority mean is defined as the smallest mean that is less than the null hypothesis mean yet still considered non-inferior. If `alternative` is `'less'`, the non-inferiority mean is defined as the largest mean that is greater than the null hypothesis mean yet still considered non-inferior. This parameter must be used together with `mean` to calculate the `offset`. If you specify this parameter along with `mean`, the `offset` if calculated as `mean` - `noninferiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the non-inferiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `noninferiority_mean` are ignored. TYPE: `float \| None` DEFAULT: `None`
`size`	Sample size. TYPE: `int`
`alternative`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta \ (\delta < 0)\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \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`
`dist`	The distribution used for the test. `'z'`: Normal distribution. `'t'`: Student's t distribution. TYPE: `Literal['z', 't']` DEFAULT: `'t'`

RETURNS	DESCRIPTION
`float`	The required standard deviation.

RAISES	DESCRIPTION
`ValueError`	The given set of parameters is insufficient to determine the offset.