跳转至

pystatpower

Modules:

models

Modules:

correlation

Modules:

inequality

Functions:

  • solve_correlation –

    Estimate the alternative correlation coefficient required for the difference test between two correlation coefficients.

  • solve_null_correlation –

    Estimeta the null correlation coefficient required for the difference test between two correlation coefficients.

  • solve_power –

    Calculate the power of the difference test between two correlation coefficients.

  • solve_size –

    Estimate the sample size required for the difference test between two correlation coefficients.

solve_correlation(null_correlation: float, size: float, alpha: float = 0.05, power: float = 0.8, bias_adj: bool = False, search_direction: str = 'upper') -> float

Estimate the alternative correlation coefficient required for the difference test between two correlation coefficients.

Parameters:

  • nnull_correlation
    (float) –

    Correlation coefficient under the null hypothesis.

  • size
    (float) –

    Sample size.

  • alpha
    (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • power
    (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • bias_adj
    (bool, default: False ) –

    Specify whether or not the bias adjustment is used. Default is False.

  • search_direction
    (str, default: 'upper' ) –

    Specify the search direction relative to the null correlation. Default is 'upper'.

Returns:

  • correlation ( float ) –

    The required alternative correlation.

solve_null_correlation(correlation: float, size: int, alpha: float = 0.05, power: float = 0.05, bias_adj: bool = False, search_direction: str = 'lower') -> float

Estimeta the null correlation coefficient required for the difference test between two correlation coefficients.

Parameters:

  • correlation
    (float) –

    Correlation coefficient under the alternative hypothesis.

  • size
    (int) –

    Sample size.

  • alpha
    (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • power
    (float, default: 0.05 ) –

    Power of the test. Default is 0.05.

  • bias_adj
    (bool, default: False ) –

    Specify whether or not the bias adjustment is used. Default is False.

  • search_direction
    (str, default: 'lower' ) –

    Specify the search direction relative to the alternative correlation. Default is 'lower'.

Returns:

  • null_correlation ( float ) –

    The required null correlation.

solve_power(null_correlation: float, correlation: float, size: float, alpha: float = 0.05, bias_adj: bool = False) -> float

Calculate the power of the difference test between two correlation coefficients.

Parameters:

  • null_correlation
    (float) –

    Correlation coefficient under the null hypothesis.

  • correlation
    (float) –

    Correlation coefficient under the alternative hypothesis.

  • size
    (float) –

    Sample size.

  • alpha
    (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • bias_adj
    (bool, default: False ) –

    Specify whether or not the bias adjustment is used. Default is False.

Returns:

  • power ( float ) –

    Power of the test.

solve_size(null_correlation: float, correlation: float, alpha: float = 0.05, power: float = 0.8, bias_adj: bool = False) -> float

Estimate the sample size required for the difference test between two correlation coefficients.

Parameters:

  • null_correlation
    (float) –

    Correlation coefficient under the null hypothesis.

  • correlation
    (float) –

    Correlation coefficient under the alternative hypothesis.

  • alpha
    (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • power
    (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • bias_adj
    (bool, default: False ) –

    Specify whether or not the bias adjustment is used. Default is False.

Returns:

  • size ( float ) –

    The required sample size.

proportion

Modules:

independent

Modules:

noninferiority

Functions:

  • solve_margin –

    Estimate the non-inferiority margin required for the non-inferiority test between two independent proportions.

  • solve_power –

    Calculate the power of the non-inferiority test between two independent proportions.

  • solve_reference_proportion –

    Estimate the reference proportion required for the non-inferiority test between two independent proportions.

  • solve_size –

    Estimate the sample size required for the non-inferiority test between two independent proportions.

  • solve_treatment_proportion –

    Estimate the treatment proportion required for the non-inferiority test between two independent proportions.

solve_margin(treatment_proportion: float, reference_proportion: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False, margin_selection: Literal['positive', 'negative'] = 'negative') -> float

Estimate the non-inferiority margin required for the non-inferiority test between two independent proportions.

Parameters:

  • treatment_proportion (float) –

    Treatment proportion.

  • reference_proportion (float) –

    Reference proportion.

  • treatment_size (float) –

    Treatment sample size.

  • reference_size (float) –

    Reference sample size.

  • alpha (float, default: 0.05 ) –

    One-sided significance level. Default is 0.05.

  • power (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • pooled (bool, default: False ) –

    Whether or not the pooled method is used. Default is False.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used. Default is False.

  • margin_selection (Literal['positive', 'negative'], default: 'negative' ) –

    selection criterion when two margin solutions exist. Default is "negative".

    • If positive, the positive margin is returned.
    • If negative, the negative margin is returned.

    Note: If only one solution exists, this parameter is ignored.

Returns:

  • margin ( float ) –

    The required non-inferiority margin.

Notes

The non-inferiority margin should be negative when higher is better, otherwise positive.

The range of the non-inferiority margin \((\delta)\) is determined by the treatment proportion \((p_1)\) and reference proportion \((p_2)\):

If higher proportion is better:

\[ \delta \in \begin{cases} (-p_2, \ 0) & , \text{if } p_1 \ge p_2 \\ (-p_2, \ p_1-p_2) & , \text{if } p_1 \lt p_2 \end{cases} \]

If higher proportion is worse:

\[ \delta \in \begin{cases} (p_1-p_2, \ 1-p_2) & , \text{if } p_1 \gt p_2 \\ (0, \ 1-p_2) & , \text{if } p_1 \le p_2 \end{cases} \]
solve_power(treatment_proportion: float, reference_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, pooled: bool = False, continuity_correction: bool = False) -> float

Calculate the power of the non-inferiority test between two independent proportions.

Parameters:

  • treatment_proportion (float) –

    Treatment proportion.

  • reference_proportion (float) –

    Reference proportion.

  • margin (float) –

    Non-inferiority margin, which should be negative when higher is better, otherwise positive.

  • treatment_size (float) –

    Treatment sample size.

  • reference_size (float) –

    Reference sample size.

  • alpha (float, default: 0.05 ) –

    One-sided significance level. Default is 0.05.

  • pooled (bool, default: False ) –

    Whether or not the pooled method is used. Default is False.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used. Default is False.

Returns:

  • power ( float ) –

    Power of the test.

solve_reference_proportion(treatment_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> float

Estimate the reference proportion required for the non-inferiority test between two independent proportions.

Parameters:

  • treatment_proportion (float) –

    Treatment proportion.

  • margin (float) –

    Non-inferiority margin, which should be negative when higher is better, otherwise positive.

  • treatment_size (float) –

    Treatment sample size.

  • reference_size (float) –

    Reference sample size.

  • alpha (float, default: 0.05 ) –

    One-sided significance level. Default is 0.05.

  • power (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • pooled (bool, default: False ) –

    Whether or not the pooled method is used. Default is False.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used. Default is False.

Returns:

  • reference_proportion ( float ) –

    The required reference proportion.

Notes

The range of the reference proportion \((p_2)\) is determined by the treatment proportion \((p_1)\) and non-inferiority margin \((\delta)\):

\[ \begin{cases} (-\delta, \ p_1) \cup \left(\max\left(p_1, \ -\delta\right), \min\left(p_1-\delta, \ 1\right)\right) & , \text{if } \delta < 0 \\ (p_1, \ 1-\delta) \cup \left(\max\left(p_1-\delta, \ 0\right), \ \min\left(p_1, \ 1-\delta\right)\right) & , \text{if } \delta > 0 \end{cases} \]
solve_size(treatment_proportion: float, reference_proportion: float, margin: float, ratio: float = 1, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> tuple[int, int]

Estimate the sample size required for the non-inferiority test between two independent proportions.

Parameters:

  • treatment_proportion (float) –

    Treatment proportion.

  • reference_proportion (float) –

    Reference proportion.

  • margin (float) –

    Non-inferiority margin, which should be negative when higher is better, otherwise positive.

  • ratio (float, default: 1 ) –

    Ratio of the sample size of the treatment group to the reference group. Default is 1.

  • alpha (float, default: 0.05 ) –

    One-sided significance level. Default is 0.05.

  • power (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • pooled (bool, default: False ) –

    Whether or not the pooled method is used. Default is False.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used. Default is False.

Returns:

  • size ( tuple[int, int] ) –

    The required sample size.

solve_treatment_proportion(reference_proportion: float, margin: float, treatment_size: float, reference_size: float, alpha: float = 0.05, power: float = 0.8, pooled: bool = False, continuity_correction: bool = False) -> float

Estimate the treatment proportion required for the non-inferiority test between two independent proportions.

Parameters:

  • reference_proportion (float) –

    Reference proportion.

  • margin (float) –

    Non-inferiority margin, which should be negative when higher is better, otherwise positive.

  • treatment_size (float) –

    Treatment sample size.

  • reference_size (float) –

    Reference sample size.

  • alpha (float, default: 0.05 ) –

    One-sided significance level. Default is 0.05.

  • power (float, default: 0.8 ) –

    Power of the test. Default is 0.80.

  • pooled (bool, default: False ) –

    Whether or not the pooled method is used. Default is False.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used. Default is False.

Returns:

  • treatment_proportion ( float ) –

    The required treatment proportion.

Notes

The range of the treatment proportion \((p_1)\) is determined by the reference proportion \((p_2)\) and non-inferiority margin \((\delta)\):

\[ \begin{cases} \left(\max\left(p_2+\delta, \ 0\right), 1\right) & , \text{if } \delta < 0 \\ \left(0, \ \min\left(p_2+\delta, \ 1\right)\right) & , \text{if } \delta > 0 \end{cases} \]
superiority

定性指标、两独立样本、优效性检验

Functions:

  • size –

    估算定性指标两独立样本优效性检验的样本量

size(alpha: float, power: float, treatment_proportion: float, reference_proportion: float, margin: float, ratio: float = 1, pooled: bool = False, continuity_correction: bool = False)

估算定性指标两独立样本优效性检验的样本量

Parameters:

  • alpha (float) –

    显著性水平

  • power (float) –

    检验效能

  • treatment_proportion (float) –

    试验组指标值

  • reference_proportion (float) –

    对照组指标值

  • margin (float) –

    优效界值

  • ratio (float, default: 1 ) –

    样本量分配比例，试验组：对照组

  • pooled (bool, default: False ) –

    是否使用合并方差

  • continuity_correction (bool, default: False ) –

    是否使用连续性校正

single

Modules:

ci

Functions:

  • solve_ci_width –

    Calculate the confidence interval width for one proportion.

  • solve_proportion –

    Estimate the proportion required to achieve a given confidence interval for one proportion.

  • solve_size –

    Estimate the sample size required to achieve a given confidence interval for one proportion.

solve_ci_width(proportion: float, size: float, alpha: float = 0.05, method: str = 'clopper-pearson', continuity_correction: bool = True) -> float

Calculate the confidence interval width for one proportion.

Parameters:

  • proportion (float) –

    Proportion.

  • size (float) –

    Sample size.

  • alpha (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • method (str, default: 'clopper-pearson' ) –

    Specify the method for calculating confidence interval. Default is clopper_pearson.

  • continuity_correction (bool, default: True ) –

    Specify whether or not the continuity correction is used, only valid for method = wald or wilson. Default is False.

Returns:

  • ci_width ( float ) –

    The confidence interval width.

solve_proportion(size: float, ci_width: float, alpha: float = 0.05, method: str = 'clopper_pearson', continuity_correction: bool = False, side: str = 'upper') -> float

Estimate the proportion required to achieve a given confidence interval for one proportion.

Parameters:

  • size (float) –

    Sample size.

  • ci_width (float) –

    Confidence interval width.

  • alpha (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • method (str, default: 'clopper_pearson' ) –

    The method for calculating confidence interval. Default is clopper_pearson.

  • continuity_correction (bool, default: False ) –

    Whether or not the continuity correction is used, only valid for method = wald or wilson. Default is False.

  • side (str, default: 'upper' ) –

    Which root to return. Must be lower (proportion closer to 0) or upper (proportion closer to 1). Default is upper.

Returns:

  • ci_width ( float ) –

    The confidence interval width.

solve_size(proportion: float, ci_width: float, alpha: float = 0.05, method: str = 'clopper_pearson', continuity_correction: bool = False) -> float

Estimate the sample size required to achieve a given confidence interval for one proportion.

Parameters:

  • proportion (float) –

    Proportion.

  • ci_width (float) –

    Confidence interval width.

  • alpha (float, default: 0.05 ) –

    Significance level. Default is 0.05.

  • method (str, default: 'clopper_pearson' ) –

    Specify the method for calculating confidence interval. Default is clopper_pearson.

  • continuity_correction (bool, default: False ) –

    Specify whether or not the continuity correction is used, only valid for method = wald or wilson. Default is False.

Returns:

  • size ( float ) –

    The required sample size.

inequality

Functions:

  • solve_null_proportion –

    Estimate the null proportion (p0) required to achieve a target power for a one-sample proportion test.

  • solve_power –

    Calculate the power for a one-sample proportion test.

  • solve_proportion –

    Estimate the alternative proportion (p1) required to achieve a target power for a one-sample proportion test.

  • solve_size –

    Estimate the sample size required for a one-sample proportion test.

solve_null_proportion(proportion: float, size: int, alternative: Literal['one-sided', 'two-sided'] = 'two-sided', alpha: float = 0.05, power: float = 0.8, phat: bool = False, continuity_correction: bool = False, proportion_selection: Literal['lower', 'upper'] = 'lower') -> float

Estimate the null proportion (p0) required to achieve a target power for a one-sample proportion test.

Parameters:

  • proportion (float) –

    The expected proportion under the alternative hypothesis (p1). Must be in the interval (0, 1).

  • size (int) –

    Total number of independent observations (sample size). Must be >= 1.

  • alternative (Literal['one-sided', 'two-sided'], default: 'two-sided' ) –

    Direction of the test:

    • "two-sided": \(H1: p \neq p_0\)
    • "one-sided": \(H1: p > p_0\) or \(p < p_0\)

    Default is "two-sided".

  • alpha (float, default: 0.05 ) –

    Significance level (Type I error rate). Defaults is 0.05.

  • power (float, default: 0.8 ) –

    Desired statistical power (1 - Type II error rate). Defaults is 0.80.

  • phat (bool, default: False ) –

    Whether to use sample proportion to calculate standard deviation. Defaults is False.

  • continuity_correction (bool, default: False ) –

    Whether to apply continuity correction to the normal approximation. Defaults is False.

  • proportion_selection (Literal['lower', 'upper'], default: 'lower' ) –

    Selection strategy when two valid null proportions exist:

    • "lower": Returns the solution where p0 < p1.
    • "upper": Returns the solution where p0 > p1.

    If only one solution exists in (0, 1), this parameter is ignored. Defaults is "lower".

Returns:

  • null_proportion ( float ) –

    The estimated null proportion (p0).

solve_power(null_proportion: float, proportion: float, size: int, alternative: Literal['one-sided', 'two-sided'] = 'two-sided', alpha: float = 0.05, phat: bool = False, continuity_correction: bool = False) -> float

Calculate the power for a one-sample proportion test.

Parameters:

  • null_proportion (float) –

    The proportion specified under the null hypothesis (p0). Must be in the interval (0, 1).

  • proportion (float) –

    The expected or observed proportion under the alternative hypothesis (p1). Must be in the interval (0, 1).

  • size (int) –

    Total number of independent observations (sample size). Must be >= 1.

  • alternative (Literal['one-sided', 'two-sided'], default: 'two-sided' ) –

    Direction of the test:

    • "two-sided": \(H1: p1 \neq p_0\)
    • "one-sided": \(H1: p1 > p_0\) or \(p1 < p_0\)

    Default is "two-sided".

  • alpha (float, default: 0.05 ) –

    Significance level (Type I error rate). Defaults is 0.05.

  • phat (bool, default: False ) –

    Whether to use sample proportion to calculate standard deviation. Defaults is False.

  • continuity_correction (bool, default: False ) –

    Whether to apply continuity correction to the normal approximation. Defaults is False.

Returns:

  • power ( float ) –

    The calculated power of the test, in the range [0, 1].

solve_proportion(null_proportion: float, size: int, alternative: Literal['one-sided', 'two-sided'] = 'two-sided', alpha: float = 0.05, power: float = 0.8, phat: bool = False, continuity_correction: bool = False, proportion_selection: Literal['lower', 'upper'] = 'upper')

Estimate the alternative proportion (p1) required to achieve a target power for a one-sample proportion test.

Parameters:

  • null_proportion (float) –

    The proportion specified under the null hypothesis (p0). Must be in the interval (0, 1).

  • size (int) –

    Total number of independent observations (sample size). Must be >= 1.

  • alternative (Literal['one-sided', 'two-sided'], default: 'two-sided' ) –

    Direction of the test:

    • "two-sided": \(H1: p \neq p_0\)
    • "one-sided": \(H1: p > p_0\) or \(p < p_0\)

    Default is "two-sided".

  • alpha (float, default: 0.05 ) –

    Significance level (Type I error rate). Defaults is 0.05.

  • power (float, default: 0.8 ) –

    Desired statistical power (1 - Type II error rate). Defaults is 0.80.

  • phat (bool, default: False ) –

    Whether to use sample proportion to calculate standard deviation. Defaults is False.

  • continuity_correction (bool, default: False ) –

    Whether to apply continuity correction to the normal approximation. Defaults is False.

  • proportion_selection (Literal['lower', 'upper'], default: 'upper' ) –

    Selection strategy when two valid alternative proportions exist:

    • "lower": Returns the solution where p1 < p0.
    • "upper": Returns the solution where p1 > p0.

    If only one solution exists in (0, 1), this parameter is ignored. Defaults is "upper".

Returns:

  • proportion ( float ) –

    The estimated alternative proportion (p1).

solve_size(null_proportion: float, proportion: float, alternative: Literal['one-sided', 'two-sided'] = 'two-sided', alpha: float = 0.05, power: float = 0.8, phat: bool = False, continuity_correction: bool = False) -> int

Estimate the sample size required for a one-sample proportion test.

Parameters:

  • null_proportion (float) –

    The proportion specified under the null hypothesis (p0). Must be in the interval (0, 1).

  • proportion (float) –

    The expected proportion under the alternative hypothesis (p1). Must be in the interval (0, 1).

  • alternative (Literal['one-sided', 'two-sided'], default: 'two-sided' ) –

    Direction of the test:

    • "two-sided": \(H1: p \neq p_0\)
    • "one-sided": \(H1: p > p_0\) or \(p < p_0\)

    Default is "two-sided".

  • alpha (float, default: 0.05 ) –

    Significance level (Type I error rate). Defaults is 0.05.

  • power (float, default: 0.8 ) –

    Desired statistical power (1 - Type II error rate). Defaults is 0.80.

  • phat (bool, default: False ) –

    Whether to use sample proportion to calculate standard deviation. Defaults is False.

  • continuity_correction (bool, default: False ) –

    Whether to apply continuity correction to the normal approximation. Defaults is False.

Returns:

  • size ( float ) –

    The minimum sample size (rounded up to the nearest integer) required to achieve the target power.