pystatpower.models.mean.independent.superiority ¶

Functions:

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

solve_power ¶

solve_power(*, diff: float, margin: float, treatment_std: float, reference_std: float, treatment_size: float, reference_size: float, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, method: Literal['z', 't'] = 't', equal_var: bool = False, df_adjust: Literal['welch', 'satterthwaite'] = 'welch') -> float

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

Parameters:

Name	Type	Description	Default
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)).	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher mean indicates a better outcome Use a negative value if a lower mean indicates a better outcome	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 in the treatment group (\(n_1\)).	required
`reference_size`	`float`	Sample size in the reference group (\(n_2\)).	required
`alternative`	`Literal['lower', 'upper']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`

Returns:

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

Raises:

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

solve_size ¶

solve_size(*, diff: float, margin: float, treatment_std: float, reference_std: float, ratio: float = 1, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, power: float = 0.8, method: Literal['z', 't'] = 't', equal_var: bool = False, df_adjust: Literal['welch', 'satterthwaite'] = 'welch') -> tuple[int, int]

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

Parameters:

Name	Type	Description	Default
`diff`	`float`	Expected mean difference between treatment and reference group (\(\mu_1 - \mu_2\)).	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher mean indicates a better outcome Use a negative value if a lower mean indicates a better outcome	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
`ratio`	`float`	Ratio of treatment sample size to reference sample size (\(k = n_1 / n_2\)).	`1`
`alternative`	`Literal['lower', 'upper']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`

Returns:

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

Raises:

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

solve_diff ¶

solve_diff(*, margin: float, treatment_std: float, reference_std: float, treatment_size: float, reference_size: float, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, power: float = 0.8, method: Literal['z', 't'] = 't', equal_var: bool = False, df_adjust: Literal['welch', 'satterthwaite'] = 'welch', alternative_when_zero_margin: Literal['positive', 'negative'] = 'positive') -> float

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

Parameters:

Name	Type	Description	Default
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher mean indicates a better outcome Use a negative value if a lower mean indicates a better outcome	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']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`
`alternative_when_zero_margin`	`Literal['positive', 'positive']`	The direction of difference when `margin=0`. `'positive'`: Search for a positive difference. `'negative'`: Search for a negative difference. If `margin` is not equal to `0`, this parameter is ignored.	`'positive'`

Returns:

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

Raises:

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

Notes

The search interval for mean difference (\(\mu_1 - \mu_2\)) is constrained by the superiority margin (\(\delta\)) to ensure the alternative hypothesis remains plausible.

\[ \text{Search Interval} = \begin{cases} (\delta, \ +\infty) & , \text{if alternative is upper} \\ (-\infty, \ \delta) & , \text{if alternative is lower} \\ \end{cases} \]

solve_margin ¶

solve_margin(*, diff: float, treatment_std: float, reference_std: float, treatment_size: float, reference_size: float, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, power: float = 0.8, method: Literal['z', 't'] = 't', equal_var: bool = False, df_adjust: Literal['welch', 'satterthwaite'] = 'welch') -> float

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

Parameters:

Name	Type	Description	Default
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \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']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`

Returns:

Type	Description
`float`	The required superiority margin.

Raises:

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

Notes

The search interval for superiority margin (\(\delta\)) is constrained by the mean difference (\(\mu_1 - \mu_2\)) to ensure the alternative hypothesis remains plausible.

\[ \text{Search Interval} = \begin{cases} [0, \ \mu_1 - \mu_2) & , \text{if alternative is upper} \\ (\mu_1 - \mu_2, \ 0] & , \text{if alternative is lower} \\ \end{cases} \]

solve_treatment_std ¶

solve_treatment_std(*, diff: float, margin: float, treatment_size: float, reference_size: float, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, power: float = 0.8, method: Literal['z', 't'] = 't', equal_var: bool = True, reference_std: float | None = None, df_adjust: Literal['welch', 'satterthwaite'] = 'welch') -> float

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

Parameters:

Name	Type	Description	Default
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)).	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher mean indicates a better outcome Use a negative value if a lower mean indicates a better outcome	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']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method='t'` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `equal_var=False` and `reference_std=None`.

solve_reference_std ¶

solve_reference_std(*, diff: float, margin: float, treatment_size: float, reference_size: float, alternative: Literal['lower', 'upper'] = 'upper', alpha: float = 0.025, power: float = 0.8, method: Literal['z', 't'] = 't', equal_var: bool = True, treatment_std: float | None = None, df_adjust: Literal['welch', 'satterthwaite'] = 'welch') -> float

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

Parameters:

Name	Type	Description	Default
`diff`	`float`	Mean difference between treatment and reference group (\(\mu_1 - \mu_2\)).	required
`margin`	`float`	The superiority margin (\(\delta\)) Use a positive value if a higher mean indicates a better outcome Use a negative value if a lower mean indicates a better outcome	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']`	The direction of the alternative hypothesis. `'lower'`: lower-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 < \delta\) `'upper'`: upper-tailed alternative hypothesis: \(H_1: \mu_1 - \mu_2 > \delta\)	`'upper'`
`alpha`	`float`	One-sided significance level.	`0.025`
`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_2\)). If `equal_var=True`, this parameter is ignored, otherwise, you must specify this parameter.	`None`
`df_adjust`	`Literal['welch', 'satterthwaite']`	Degree of freedom adjustment method when `method="t"` and `equal_var=False`. `'welch'`: Adjustment based on Welch (1947). `'satterthwaite'`: Adjustment based on Satterthwaite (1946).	`'welch'`

Returns:

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

Raises:

Type	Description
`ValueError`	If `equal_var=False` and `treatment_std=None`.