pystatpower.mean.single.superiority ¶

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 superiority margin.
`solve_diff`	Estimate the required mean difference.
`solve_superiority_mean`	Estimate the required superiority 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,
    superiority_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 `superiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `superiority_mean`, the `offset` is calculated as `mean` - `superiority_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 superiority 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 mean under 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`
`superiority_mean`	The superiority mean. If `alternative` is `'greater'`, the superiority mean is defined as the smallest mean that exceeds the null hypothesis mean and is considered superior. If `alternative` is `'less'`, the superiority mean is defined as the largest mean that falls below the null hypothesis mean and is considered superior. 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` - `superiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the superiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `superiority_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 superiority 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,
    superiority_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 `superiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `superiority_mean`, the `offset` is calculated as `mean` - `superiority_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 superiority 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 mean under 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`
`superiority_mean`	The superiority mean. If `alternative` is `'greater'`, the superiority mean is defined as the smallest mean that exceeds the null hypothesis mean and is considered superior. If `alternative` is `'less'`, the superiority mean is defined as the largest mean that falls below the null hypothesis mean and is considered superior. 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` - `superiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the superiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `superiority_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 superiority 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,
    superiority_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 `superiority_mean` If you specify this parameter along with `margin`, the `superiority_mean` is calculated as `null_mean` + `margin`. TYPE: `float \| None` DEFAULT: `None`
`margin`	The superiority margin. This parameter must be used together with `null_mean` to calculate the `superiority_mean` If you specify this parameter along with `null_mean`, the `superiority_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`
`superiority_mean`	The superiority mean. If `alternative` is `'greater'`, the superiority mean is defined as the smallest mean that exceeds the null hypothesis mean and is considered superior. If `alternative` is `'less'`, the superiority mean is defined as the largest mean that falls below the null hypothesis mean and is considered superior. 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 superiority 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 superiority 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 superiority 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 superiority 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 superiority 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 superiority 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 superiority 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 superiority 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 superiority 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_superiority_mean ¶

solve_superiority_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 superiority mean.

If alternative is 'greater', the superiority mean is defined as the smallest mean that exceeds the null hypothesis mean and is considered superior.
If alternative is 'less', the superiority mean is defined as the largest mean that falls below the null hypothesis mean and is considered superior.

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 superiority 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 superiority 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 superiority 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 superiority 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 offset.

solve_std ¶

solve_std(
    *,
    mean: float | None = None,
    null_mean: float | None = None,
    margin: float | None = None,
    diff: float | None = None,
    superiority_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 `superiority_mean`, or alternatively, in conjunction with `null_mean` and `margin` to calculate the `offset`. If you specify this parameter along with `superiority_mean`, the `offset` is calculated as `mean` - `superiority_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 superiority 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 mean under 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`
`superiority_mean`	The superiority mean. If `alternative` is `'greater'`, the superiority mean is defined as the smallest mean that exceeds the null hypothesis mean and is considered superior. If `alternative` is `'less'`, the superiority mean is defined as the largest mean that falls below the null hypothesis mean and is considered superior. 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` - `superiority_mean`. TYPE: `float \| None` DEFAULT: `None`
`offset`	The offset, defined as the difference between the mean under the alternative hypothesis and the superiority mean. If you specify this parameter, all of `mean`, `null_mean`, `margin`, `diff`, `superiority_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 superiority 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.