pystatpower.mean.single.superiority ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for a superiority test of one sample mean.
`solve_size`	Estimate the required sample size for a superiority test of one sample mean.
`solve_diff`	Estimete the required mean difference between the alternative hypothesis and the null hypothesis for a superiority test of one sample mean.
`solve_mean`	Estimate the required mean under the alternative hypothesis for a superiority test of one sample mean.
`solve_null_mean`	Estimate the required mean under the null hypothesis for a superiority test of one sample mean.
`solve_std`	Estimate the required standard deviation for a superiority test of one sample mean.
`solve_margin`	Estimate the required margin for a superiority test of one sample mean.

solve_power ¶

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

Calculate the statistical power for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`mean`	`float \| None`	Mean under the alternative hypothesis. If `diff` is not specified, this parameter and `null_mean` are required.	`None`
`null_mean`	`float \| None`	Mean under the null hypothesis. If `diff` is not specified, this parameter and `mean` are required.	`None`
`diff`	`float \| None`	Mean difference between the alternative hypothesis and the null hypothesis. If both `mean` and `null_mean` are not specified, this parameter is required.	`None`
`margin`	`float`	The superiority 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)`.	required
`std`	`float`	Standard deviation.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and either `mean` or `null_mean` is not specified.

solve_size ¶

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

Estimate the required sample size for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`mean`	`float \| None`	Mean under the alternative hypothesis. If `diff` is not specified, this parameter and `null_mean` are required.	`None`
`null_mean`	`float \| None`	Mean under the null hypothesis. If `diff` is not specified, this parameter and `mean` are required.	`None`
`diff`	`float \| None`	Mean difference between the alternative hypothesis and the null hypothesis. If both `mean` and `null_mean` are not specified, this parameter is required.	`None`
`margin`	`float`	The superiority 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)`.	required
`std`	`float`	Standard deviation.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and either `mean` or `null_mean` is not specified.

solve_diff ¶

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

Estimete the required mean difference between the alternative hypothesis and the null hypothesis for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`margin`	`float`	The superiority 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)`.	required
`std`	`float`	Standard deviation.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

Name	Type	Description
`float`	`float`	The required mean difference between the alternative hypothesis and the null hypothesis.

solve_mean ¶

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

Estimate the required mean under the alternative hypothesis for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`null_mean`	`float`	Mean under the null hypothesis.	required
`margin`	`float`	The superiority 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)`.	required
`std`	`float`	Standard deviation.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

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

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,
) -> float

Estimate the required mean under the null hypothesis for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`mean`	`float`	Mean under the alternative hypothesis.	required
`margin`	`float`	The superiority 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)`.	required
`std`	`float`	Standard deviation.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

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

solve_std ¶

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

Estimate the required standard deviation for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`mean`	`float \| None`	Mean under the alternative hypothesis. If `diff` is not specified, this parameter and `null_mean` are required.	`None`
`null_mean`	`float \| None`	Mean under the null hypothesis. If `diff` is not specified, this parameter and `mean` are required.	`None`
`diff`	`float \| None`	Mean difference between the alternative hypothesis and the null hypothesis. If both `mean` and `null_mean` are not specified, this parameter is required.	`None`
`margin`	`float`	The superiority 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)`.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

Name	Type	Description
`float`	`float`	The required standard deviation.

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and either `mean` or `null_mean` is not specified.

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,
) -> float

Estimate the required margin for a superiority test of one sample mean.

Parameters:

Name	Type	Description	Default
`mean`	`float \| None`	Mean under the alternative hypothesis. If `diff` is not specified, this parameter and `null_mean` are required.	`None`
`null_mean`	`float \| None`	Mean under the null hypothesis. If `diff` is not specified, this parameter and `mean` are required.	`None`
`diff`	`float \| None`	Mean difference between the alternative hypothesis and the null hypothesis. If both `mean` and `null_mean` are not specified, this parameter is required.	`None`
`std`	`float`	Standard deviation.	required
`size`	`int`	Sample size.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `'greater'`, the alternative hypothesis is \(\mu - \mu_0 > \delta\) If `alternative` is `'less'`, the alternative hypothesis is \(\mu - \mu_0 < \delta\)	required
`alpha`	`float`	Significance level. The superiority 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`

Returns:

Name	Type	Description
`float`	`float`	The required superiority margin. If `alternative` is `'greater'`, the returned value is in the range \((0, \hat{\mu} - \hat{\mu}_0)\) If `alternative` is `'less'`, the returned value is in the range \((\hat{\mu} - \hat{\mu}_0, 0)\)

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and either `mean` or `null_mean` is not specified.