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 required sample size for a non-inferiority test of two independent means.
`solve_diff`	Estimate the required difference for a non-inferiority test of two independent means.
`solve_margin`	Estimate the required margin for a non-inferiority test of two independent means.
`solve_treatment_std`	Estimate the required standard deviation in the treatment group for a non-inferiority test of two independent means.
`solve_reference_std`	Estimate the required standard deviation in the reference group for a non-inferiority test of two independent means.

solve_power ¶

solve_power(
    *,
    diff: float | None = None,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    margin: float,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    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\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If `diff` is not provided, this must be specified along with `reference_mean`.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If `diff` is not provided, this must be specified along with `treatment_mean`.	`None`
`margin`	`float`	The non-inferiority margin (\(\delta\)) provide a negative value if a higher mean is better provide a positive value if a higher mean is worse	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
`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. `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\). `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` is `'z'` 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).	`'welch'`

Returns:

Type	Description
`float`	The calculated 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(
    *,
    diff: float | None = None,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    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 required sample size 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\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If `diff` is not provided, this must be specified along with `reference_mean`.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If `diff` is not provided, this must be specified along with `treatment_mean`.	`None`
`margin`	`float`	The non-inferiority margin (\(\delta\)) provide a negative value if a higher mean is better provide a positive value if a higher mean is worse	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`
`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. `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\). `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` is `'z'` 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).	`'welch'`

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(
    *,
    margin: float,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    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 required difference for a non-inferiority test of two independent means.

Parameters:

Name	Type	Description	Default
`margin`	`float`	The non-inferiority margin (\(\delta\)) provide a negative value if a higher mean is better provide a positive value if a higher mean is worse	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
`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. `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\). `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` is `'z'` 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).	`'welch'`

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`.

solve_margin ¶

solve_margin(
    *,
    diff: float,
    treatment_std: float,
    reference_std: float,
    treatment_size: int,
    reference_size: int,
    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 required margin 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`	`int`	Sample size for the treatment group (\(n_1\)).	required
`reference_size`	`int`	Sample size for the reference group (\(n_2\)).	required
`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. `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\). `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` is `'z'` 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).	`'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.	`'negative'`

Returns:

Type	Description
`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 | None = None,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    margin: float,
    treatment_size: int,
    reference_size: int,
    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 required standard deviation 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\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If `diff` is not provided, this must be specified along with `reference_mean`.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If `diff` is not provided, this must be specified along with `treatment_mean`.	`None`
`margin`	`float`	The non-inferiority margin (\(\delta\)) provide a negative value if a higher mean is better provide a positive value if a higher mean is worse	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
`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. `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\). `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` is `'z'` 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 `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `equal_var=False` and `reference_std=None`.

solve_reference_std ¶

solve_reference_std(
    *,
    diff: float | None = None,
    treatment_mean: float | None = None,
    reference_mean: float | None = None,
    margin: float,
    treatment_size: int,
    reference_size: int,
    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 required standard deviation 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\)). If provided, `treatment_mean` and `reference_mean` will be ignored.	`None`
`treatment_mean`	`float`	Mean in the treatment group (\(\mu_1\)). If `diff` is not provided, this must be specified along with `reference_mean`.	`None`
`reference_mean`	`float`	Mean in the reference group (\(\mu_2\)). If `diff` is not provided, this must be specified along with `treatment_mean`.	`None`
`margin`	`float`	The non-inferiority margin (\(\delta\)) provide a negative value if a higher mean is better provide a positive value if a higher mean is worse	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
`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. `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\). `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` is `'t'` 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 `diff` is not provided, and both `treatment_mean` and `reference_mean` are not provided.
`ValueError`	If `equal_var=False` and `treatment_std=None`.