pystatpower.mean.independent.superiority ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for a superiority test of two independent means.
`solve_size`	Estimate the required sample size for a superiority test of two independent means.
`solve_treatment_mean`	Estimate the required mean in the treatment group for a superiority test of two independent means.
`solve_reference_mean`	Estimate the required mean in the reference group for a superiority test of two independent means.
`solve_diff`	Estimate the required difference between the mean in treatment and reference groups for a superiority test of two independent means.
`solve_margin`	Estimate the required margin for a superiority test of two independent means.
`solve_treatment_std`	Estimate the required standard deviation in the treatment group for a superiority test of two independent means.
`solve_reference_std`	Estimate the required standard deviation in the reference group for a superiority test of two independent means.

solve_power ¶

solve_power(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    margin: float,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Calculate the statistical power for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float \| None`	Mean in the treatment group. If `diff` is not specified, this parameter must be specified along with `reference_mean`.	`None`
`reference_mean`	`float \| None`	Mean in the reference group. If `diff` is not specified, this parameter must be specified along with `treatment_mean`.	`None`
`diff`	`float \| None`	Mean difference between treatment and reference group. If both `treatment_mean` and `reference_mean` are not specified, this parameter must be specified.	`None`
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	required
`alpha`	`float`	Significance level. The superiority test is a one-sided test, and 0.025 is a commonly used significance level.	`0.025`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and neither `treatment_mean` nor `reference_mean` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_size ¶

solve_size(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    margin: float,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    ratio: float = 1,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> tuple[int, int]

Estimate the required sample size for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float \| None`	Mean in the treatment group. If `diff` is not specified, this parameter must be specified along with `reference_mean`.	`None`
`reference_mean`	`float \| None`	Mean in the reference group. If `diff` is not specified, this parameter must be specified along with `treatment_mean`.	`None`
`diff`	`float \| None`	Mean difference between treatment and reference group. If both `treatment_mean` and `reference_mean` are not specified, this parameter must be specified.	`None`
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`ratio`	`float`	Ratio of sample size in the treatment and reference group.	`1`
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Type	Description
`tuple[int, int]`	tuple[int, int]: The required sample sizes for the treatment and reference groups, respectively.

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and neither `treatment_mean` nor `reference_mean` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_treatment_mean ¶

solve_treatment_mean(
    *,
    reference_mean: float,
    margin: float,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required mean in the treatment group for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`reference_mean`	`float`	Mean in the reference group.	required
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required mean in the treatment group.

Raises:

Type	Description
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_reference_mean ¶

solve_reference_mean(
    *,
    treatment_mean: float,
    margin: float,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required mean in the reference group for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group.	required
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required mean in the reference group.

Raises:

Type	Description
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_diff ¶

solve_diff(
    *,
    margin: float,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required difference between the mean in treatment and reference groups for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required difference between the mean in treatment and reference groups.

Raises:

Type	Description
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_margin ¶

solve_margin(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    treatment_std: float | None = None,
    reference_std: float | None = None,
    std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = False,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required margin for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float \| None`	Mean in the treatment group. If `diff` is not specified, this parameter must be specified along with `reference_mean`.	`None`
`reference_mean`	`float \| None`	Mean in the reference group. If `diff` is not specified, this parameter must be specified along with `treatment_mean`.	`None`
`diff`	`float \| None`	Mean difference between treatment and reference group. If both `treatment_mean` and `reference_mean` are not specified, this parameter must be specified.	`None`
`treatment_std`	`float \| None`	Standard deviation in the treatment group.	`None`
`reference_std`	`float \| None`	Standard deviation in the reference group.	`None`
`std`	`float \| None`	Standard deviation in both groups. This is a convenience parameter that will override `treatment_std` and `reference_std` when `dist` is `z` and `equal_var` is `True`. If you specify `dist` as `z` and `equal_var` as `True`, you can just specify `std` instead of `treatment_std` and `reference_std`. Internally, the value of `std` will be treated as the standard deviation of both the treatment and reference groups.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`False`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required superiority margin for the test. If `alternative` is `greater`, the returned value is in the range \([0, \hat{\mu}_1 - \hat{\mu}_2)\) If `alternative` is `less`, the returned value is in the range \((\hat{\mu}_1 - \hat{\mu}_2, 0]\)

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and neither `treatment_mean` nor `reference_mean` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True`, and any of `treatment_std`, `reference_std` or `std` is not specified.
`ValueError`	If `dist` is `z` and `equal_var` is `True` without specifying `std`: `treatment_std` and `reference_std` are not equal if both are provided.

solve_treatment_std ¶

solve_treatment_std(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    margin: float,
    reference_std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = True,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required standard deviation in the treatment group for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float \| None`	Mean in the treatment group. If `diff` is not specified, this parameter must be specified along with `reference_mean`.	`None`
`reference_mean`	`float \| None`	Mean in the reference group. If `diff` is not specified, this parameter must be specified along with `treatment_mean`.	`None`
`diff`	`float \| None`	Mean difference between treatment and reference group. If both `treatment_mean` and `reference_mean` are not specified, this parameter must be specified.	`None`
`margin`	`float`	The superiority 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
`reference_std`	`float \| None`	Standard deviation in the reference group. If `dist` is `z` and `equal_var` is `True`, this parameter is ignored. If `dist` is `z` and `equal_var` is `False`, this parameter is required. If `dist` is `t` and `equal_var` is `True`, this parameter is optional. If specified, this value is used to calculate the standard error of mean difference. If `dist` is `t` and `equal_var` is `False`, this parameter is required.	`None`
`treatment_size`	`int`	Sample size for the treatment group.	required
`reference_size`	`int`	Sample size for the reference group.	required
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`True`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required standard deviation in the treatment group.

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and neither `treatment_mean` nor `reference_mean` is not specified.
`ValueError`	If `equal_var` is `False`, and `reference_std` is not specified.

solve_reference_std ¶

solve_reference_std(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    margin: float,
    treatment_std: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal["greater", "less"],
    alpha: float = 0.025,
    power: float = 0.8,
    dist: Literal["z", "t"] = "t",
    equal_var: bool = True,
    approx_t_method: Literal[
        "welch", "satterthwaite"
    ] = "welch",
) -> float

Estimate the required standard deviation in the reference group for a superiority test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float \| None`	Mean in the treatment group. If `diff` is not specified, this parameter must be specified along with `reference_mean`.	`None`
`reference_mean`	`float \| None`	Mean in the reference group. If `diff` is not specified, this parameter must be specified along with `treatment_mean`.	`None`
`diff`	`float \| None`	Mean difference between treatment and reference group. If both `treatment_mean` and `reference_mean` are not specified, this parameter must be specified.	`None`
`margin`	`float`	The superiority 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
`treatment_std`	`float \| None`	Standard deviation in the treatment group. If `dist` is `z` and `equal_var` is `True`, this parameter is ignored. If `dist` is `z` and `equal_var` is `False`, this parameter is required. If `dist` is `t` and `equal_var` is `True`, this parameter is optional. If specified, this value is used to calculate the standard error of mean difference. If `dist` is `t` and `equal_var` is `False`, this parameter is required.	`None`
`alternative`	`Literal['greater', 'less']`	Type of the alternative hypothesis. If `alternative` is `greater`, the alternative hypothesis is \(\mu_1 - \mu_2 > \delta\) (\(\delta \geqslant 0\)) If `alternative` is `less`, the alternative hypothesis is \(\mu_1 - \mu_2 < \delta\) (\(\delta \leqslant 0\))	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`
`dist`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution. `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between treatment and reference groups. `True`: Variances are assumed equal. `False`: Variances are assumed unequal.	`True`
`approx_t_method`	`Literal['welch', 'satterthwaite']`	Approximate t-test method. It is used when `dist` is `'t'` and `equal_var` = `False`. `'welch'`: Welch's approximate t-test (1947). `'satterthwaite'`: Satterthwaite's approximate t-test (1946).	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The required standard deviation in the reference group.

Raises:

Type	Description
`ValueError`	If `diff` is not specified, and neither `treatment_mean` nor `reference_mean` is not specified.
`ValueError`	If `equal_var` is `False`, and `treatment_std` is not specified.