pystatpower.models.mean.independent.noninferiority ¶

Functions:

Name	Description
`solve_power`	Calculate the statistical power for a non-inferiority test of two independent means.
`solve_size`	Estimate the sample size required for a non-inferiority test of two independent means.
`solve_diff`	Estimate the difference required for a non-inferiority test of two independent means.
`solve_margin`	Estimate the non-inferiority margin required for a non-inferiority test of two independent means.
`solve_treatment_std`	Estimate the standard deviation required in the treatment group for a non-inferiority test of two independent means.
`solve_reference_std`	Estimate the standard deviation required in the reference group for a non-inferiority 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, 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher mean indicates a better outcome Use a positive 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
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`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. Defaults to "t".	`'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. Defaults to False. If Z test is used and `equal_var` is 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). Defaults to "welch".	`'welch'`

Returns:

Name	Type	Description
`float`	`float`	The calculated 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, 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher mean indicates a better outcome Use a positive 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\)). Defaults to 1.	`1`
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`0.025`
`power`	`float`	Desired statistical power. Defaults to 0.8.	`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. Defaults to "t".	`'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. Defaults to False. If Z test is used and `equal_var` is 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). Defaults to "welch".	`'welch'`

Returns:

Name	Type	Description
`float`	`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, 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 difference required for a non-inferiority test of two independent means.

Parameters:

Name	Type	Description	Default
`margin`	`float`	The non-inferiority margin (\(\delta\)) Use a negative value if a higher mean indicates a better outcome Use a positive 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
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`0.025`
`power`	`float`	Desired statistical power. Defaults to 0.8.	`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. Defaults to "t".	`'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. Defaults to False. If Z test is used and `equal_var` is 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). Defaults to "welch".	`'welch'`

Returns:

Name	Type	Description
`float`	`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`.

solve_margin ¶

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

Estimate the non-inferiority margin required for a non-inferiority 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
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`0.025`
`power`	`float`	Desired statistical power. Defaults to 0.8.	`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. Defaults to "t".	`'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. Defaults to False. If Z test is used and `equal_var` is 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). Defaults to "welch".	`'welch'`
`margin_selection`	`Literal['positive', 'negative']`	Selection criterion when two mathematically valid solutions exist (one for "higher is better", one for "worse") "positive": Returns the positive margin. "negative": Returns the negative margin. Defaults to "negative".	`'negative'`

Returns:

Name	Type	Description
`float`	`float`	The required non-inferiority 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 non-inferiority margin (\(\sigma\)) is constrained by the mean difference (\(\mu_1 - \mu_2\)) to ensure the alternative hypothesis remains plausible.

\[ \text{Search Interval} = \begin{cases} (-\infty, \ \min\left(0, \ \mu_1 - \mu_2\right)) & , \text{if } \delta < 0 \\ (\max\left(\mu_1 - \mu_2, \ 0\right), \ \infty) & , \text{if } \delta > 0 \\ \end{cases} \]

solve_treatment_std ¶

solve_treatment_std(*, diff: float, margin: float, treatment_size: float, reference_size: float, 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher mean indicates a better outcome Use a positive 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
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`0.025`
`power`	`float`	Desired statistical power. Defaults to 0.8.	`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. Defaults to "t".	`'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. Defaults to True. 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). Defaults to "welch".	`'welch'`

Returns:

Name	Type	Description
`float`	`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, 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 non-inferiority 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 non-inferiority margin (\(\delta\)) Use a negative value if a higher mean indicates a better outcome Use a positive 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
`alpha`	`float`	One-sided significance level. Defaults to 0.025.	`0.025`
`power`	`float`	Desired statistical power. Defaults to 0.8.	`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. Defaults to "t".	`'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. Defaults to True. 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). Defaults to "welch".	`'welch'`

Returns:

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

Raises:

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