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 sample size required for an inequality test of two independent means.
`solve_diff`	Estimate the difference required for an inequality test of two independent means.
`solve_treatment_mean`	Estimate the mean required in the treatment group for an inequality test of two independent means.
`solve_reference_mean`	Estimate the mean required in the reference group for an inequality test of two independent means.
`solve_treatment_std`	Estimate the standard deviation required in the treatment group for an inequality test of two independent means.
`solve_reference_std`	Estimate the standard deviation required 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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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`	`float`	Sample size in the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size in the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`alpha`	`float`	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['lower', 'upper', 'both'] = 'both', 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 sample size required 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['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`alpha`	`float`	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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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 difference required 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`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`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.	`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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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 mean required 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`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`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.	`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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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 mean required 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`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`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.	`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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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 standard deviation required 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`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`alpha`	`float`	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: float, reference_size: float, alternative: Literal['lower', 'upper', 'both'] = 'both', 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 standard deviation required 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`	`float`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size for the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper', 'both']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 < \mu_2\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 > \mu_2\) `'both'`: two-tailed alternative hypothesis: \(H_1: \mu_1 \neq \mu_2\)	`'both'`
`alpha`	`float`	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.