pystatpower.models.mean.independent.inequality ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for an inequality test of two independent means.
`solve_size`	Estimate the required sample size for an inequality test of two independent means.
`solve_diff`	Estimate the required difference for an inequality test of two independent means.
`solve_treatment_mean`	Estimate the required mean in the treatment group for an inequality test of two independent means.
`solve_reference_mean`	Estimate the required mean in the reference group for an inequality test of two independent means.
`solve_treatment_std`	Estimate the required standard deviation in the treatment group for an inequality test of two independent means.
`solve_reference_std`	Estimate the required standard deviation in the reference group for an inequality test of two independent means.

solve_power ¶

solve_power(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    alpha: float = 0.05,
    method: Literal["z", "t"] = "t",
    equal_var: bool = False,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Calculate the statistical power for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If provided together with `reference_mean`, `diff` is ignored.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If provided together with `treatment_mean`, `diff` is ignored.	`None`
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_std`	`float`	Standard deviation in the treatment group (\(\sigma_1\)).	required
`reference_std`	`float`	Standard deviation in the reference group (\(\sigma_2\)).	required
`treatment_size`	`int`	Sample size in the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size in the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If `True`: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, the degree of freedom \(df = n_1 + n_2 - 2\). If `False`: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If `method='z'` and `equal_var=True`, the standard deviation of the two groups must be equal.	`False`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `method='z'` and `equal_var=True` but `treatment_std` does not equal to `reference_std`.

solve_size ¶

solve_size(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    treatment_std: float,
    reference_std: float,
    ratio: float = 1,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = False,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> tuple[int, int]

Estimate the required sample size for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If provided together with `reference_mean`, `diff` is ignored.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If provided together with `treatment_mean`, `diff` is ignored.	`None`
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_std`	`float`	Standard deviation in the treatment group (\(\sigma_1\)).	required
`reference_std`	`float`	Standard deviation in the reference group (\(\sigma_2\)).	required
`ratio`	`float`	Ratio of treatment sample size to reference sample size (\(k = n_1 / n_2\)).	`1`
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If True: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method="t"`, degree of freedom \(df = n_1 + n_2 - 2\). If False: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method="t"`, the degree of freedom is adjusted based on the `df_adjust` parameter. If `method='z'` and `equal_var=True`, the standard deviation of the two groups must be equal.	`False`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `method='z'` and `equal_var=True` but `treatment_std` does not equal to `reference_std`.

solve_diff ¶

solve_diff(
    *,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    search_direction: Literal["above", "below"] = "above",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = False,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Estimate the required difference for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_std`	`float`	Standard deviation in the treatment group (\(\sigma_1\)).	required
`reference_std`	`float`	Standard deviation in the reference group (\(\sigma_2\)).	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`search_direction`	`Literal['above', 'below']`	Specify whether to search for the mean difference above or below 0. `'above'`: Search the difference above 0. `'below'`: Search the difference below 0.	`'above'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If `True`: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, degree of freedom \(df = n_1 + n_2 - 2\). If `False`: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If `method='z'` and `equal_var=True`, the standard deviation of the two groups must be equal.	`False`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

Type	Description
`float`	The required difference between the treatment and reference means.

Raises:

Type	Description
`ValueError`	If `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `method='z'` and `equal_var=True` but `treatment_std` does not equal to `reference_std`.

solve_treatment_mean ¶

solve_treatment_mean(
    *,
    reference_mean: float,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    search_direction: Literal["above", "below"] = "above",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = False,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Estimate the required mean in the treatment group for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)).	required
`treatment_std`	`float`	Standard deviation in the treatment group (\(\sigma_1\)).	required
`reference_std`	`float`	Standard deviation in the reference group (\(\sigma_2\)).	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`search_direction`	`Literal['above', 'below']`	Specify whether to search for the treatment mean above or below the reference mean. `'above'`: Search the treatment mean above the reference mean. `'below'`: Search the treatment mean below the reference mean.	`'above'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If `True`: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, degree of freedom \(df = n_1 + n_2 - 2\). If `False`: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If `method='z'` and `equal_var=True`, the standard deviation of the two groups must be equal.	`False`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `method='z'` and `equal_var=True` but `treatment_std` does not equal to `reference_std`.

solve_reference_mean ¶

solve_reference_mean(
    *,
    treatment_mean: float,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    search_direction: Literal["above", "below"] = "below",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = False,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Estimate the required mean in the reference group for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_2\)).	required
`treatment_std`	`float`	Standard deviation in the treatment group (\(\sigma_1\)).	required
`reference_std`	`float`	Standard deviation in the reference group (\(\sigma_2\)).	required
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`search_direction`	`Literal['above', 'below']`	Specify whether to search for the reference mean above or below the treatment mean. `'above'`: Search the reference mean above the treatment mean. `'below'`: Search the reference mean below the treatment mean.	`'below'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If `True`: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, degree of freedom \(df = n_1 + n_2 - 2\). If `False`: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If `method='z'` and `equal_var=True`, the standard deviation of the two groups must be equal.	`False`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `method='z'` and `equal_var=True` but `treatment_std` does not equal to `reference_std`.

solve_treatment_std ¶

solve_treatment_std(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = True,
    reference_std: float | None = None,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Estimate the required standard deviation in the treatment group for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If provided together with `reference_mean`, `diff` is ignored.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If provided together with `treatment_mean`, `diff` is ignored.	`None`
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If `True`: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, degree of freedom \(df = n_1 + n_2 - 2\). If `False`: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If Z test is used and `equal_var` is True, the standard deviation of the two groups must be equal.	`True`
`reference_std`	`float \| None`	Standard deviation in the reference group (\(\sigma_2\)). If `equal_var=True`, this parameter is ignored, otherwise, you must specify this parameter.	`None`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `equal_var=False` but `reference_std` is not provided.

solve_reference_std ¶

solve_reference_std(
    *,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    diff: float | None = None,
    treatment_size: int,
    reference_size: int,
    alternative: Literal[
        "two-sided", "lower one-sided", "upper one-sided"
    ] = "two-sided",
    alpha: float = 0.05,
    power: float = 0.8,
    method: Literal["z", "t"] = "t",
    equal_var: bool = True,
    treatment_std: float | None = None,
    df_adjust: Literal[
        "satterthwaite", "welch"
    ] = "satterthwaite",
) -> float

Estimate the required standard deviation in the reference group for an inequality test of two independent means.

Parameters:

Name	Type	Description	Default
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If provided together with `reference_mean`, `diff` is ignored.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If provided together with `treatment_mean`, `diff` is ignored.	`None`
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_size`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['two-sided', 'lower one-sided', 'upper one-sided']`	Type of the alternative hypothesis. `'two-sided'`: Two-sided alternative hypothesis: \(\mu_1 \neq \mu_2\) `'lower one-sided'`: Lower one-sided alternative hypothesis: \(\mu_1 < \mu_2\) `'upper one-sided'`: Upper one-sided alternative hypothesis: \(\mu_1 > \mu_2\)	`'two-sided'`
`alpha`	`float`	Significance level. If `alternative` is `'two-sided'`, provide the two-sided significance level. If `alternative` is `'lower one-sided'` or `'upper one-sided'`, provide the one-sided significance level.	`0.05`
`power`	`float`	Desired statistical power.	`0.8`
`method`	`Literal['z', 't']`	The distribution used for the test. `'z'`: Standard normal distribution (large sample approximation). `'t'`: Student's or non-central t distribution.	`'t'`
`equal_var`	`bool`	Whether to assume equal variances between groups. If True: Assume \(\sigma_1^2 = \sigma_2^2\). Use Pooled Variance to calculate SE. If `method='t'`, degree of freedom \(df = n_1 + n_2 - 2\). If False: Assume \(\sigma_1^2 \neq \sigma_2^2\). Use Unpooled Variance to calculate SE. If `method='t'`, the degree of freedom is adjusted based on the `df_adjust` parameter. If Z test is used and `equal_var` is True, the standard deviation of the two groups must be equal.	`True`
`treatment_std`	`float \| None`	Standard deviation in the treatment group (\(\sigma_1\)). If `equal_var=True`, this parameter is ignored, otherwise, you must specify this parameter.	`None`
`df_adjust`	`Literal['satterthwaite', 'welch']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'satterthwaite'`: Adjustment based on Satterthwaite (1946). `'welch'`: Adjustment based on Welch (1947).	`'satterthwaite'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `equal_var=False` but `treatment_std` is not provided.