Statistics

fyron.statistics provides small, explicit statistical helpers for clinical data science. It includes common hypothesis tests, multiple-testing correction, manuscript regression tables, correlation and missingness QC, paired model-comparison tests, and bootstrap confidence intervals for scores and model metrics.

The goal is not to hide analysis choices. Fyron makes the test name, statistic, p-value, sample size, and bootstrap settings visible so results can be inspected and reported clearly.

Install

uv add "fyron[statistics]"

Imports

from fyron import statistics as fst

API Contract

Function Summary

Parameter Reference

Result Objects

Statistical tests return StatisticalTestResult.

result = fst.compare_two_groups(
    group_a=[1.2, 1.4, 1.1, 1.3],
    group_b=[1.8, 2.0, 1.7, 2.1],
)

result.test
result.statistic
result.p_value
result.effect_size
result.to_dict()

Bootstrap functions return either BootstrapResult or a DataFrame. The dataclass contains the original estimate, percentile confidence interval, number of completed rounds, and the bootstrap distribution.

boot = fst.bootstrap_summary(
    values=[1.2, 1.4, 1.1, 1.3, 1.5],
    statistic="mean",
    n_rounds=2000,
    random_state=42,
)

boot.estimate
boot.ci_low
boot.ci_high
boot.to_dict()

Choosing Tests

Multiple Testing And FDR

Use Benjamini-Hochberg false discovery rate correction when screening many features, correlations, or univariate models.

adjusted = fst.p_value_correction_table(
    univariate_results,
    p_col="p_value",
    method="fdr_bh",
    alpha=0.05,
)

Supported methods are fdr_bh, bonferroni, holm, and none. The output includes p_adjusted, p_rank, rejected, p_adjust_method, and alpha.

Manuscript Regression Tables

Use regression tables for classical inference alongside ML results.

logistic = fst.fit_logistic_regression_table(
    cohort,
    outcome_col="response",
    covariates=["age", "stage", "l3_sma_cm2"],
    p_adjust="fdr_bh",
)

linear = fst.fit_linear_regression_table(
    cohort,
    outcome_col="risk_score",
    covariates=["age", "stage", "vat_ml"],
)

vif = fst.vif_table(cohort, ["age", "stage", "vat_ml"])

Logistic regression returns odds ratios and confidence intervals. Linear regression returns beta estimates and confidence intervals. Categorical variables are dummy encoded with the first level as reference.

Model Comparison For Papers

Use McNemar's test for paired classification errors and bootstrap AUC difference for discrimination comparisons.

mcnemar = fst.mcnemar_test(y_true, pred_model_a, pred_model_b)

auc_diff = fst.bootstrap_auc_difference(
    y_true,
    prob_model_a,
    prob_model_b,
    n_rounds=2000,
    random_state=42,
)

Fyron uses the bootstrap AUC difference as the default robust comparison in this pass. DeLong testing is intentionally not exposed until a small, well-tested internal implementation is added.

Statistical QC Tables

normality = fst.normality_table(cohort, ["age", "l3_sma_cm2", "vat_ml"])
correlations = fst.correlation_pvalue_table(
    cohort,
    ["age", "l3_sma_cm2", "vat_ml", "risk_score"],
    method="spearman",
    p_adjust="fdr_bh",
)
missingness = fst.missingness_by_group_table(cohort, group_col="stage")
outliers = fst.outlier_table(cohort, ["age", "l3_sma_cm2", "vat_ml"])

These tables are intended for supplements, methods checks, and reviewer-facing data QC. They do not replace a pre-specified statistical analysis plan.

Two-Group Comparisons

compare_two_groups supports Welch t-test, Student t-test, Mann-Whitney U, paired t-test, and Wilcoxon signed-rank tests.

from fyron import statistics as fst

result = fst.compare_two_groups(
    group_a=[42, 47, 51, 49, 45],
    group_b=[55, 58, 53, 60, 57],
    method="mannwhitney",
    alternative="two-sided",
)

result.to_dict()

Clinical guidance:

• Use method="ttest" when the analysis plan assumes approximately normal group distributions.
• Use equal_var=False for Welch's t-test, which is the default.
• Use method="mannwhitney" for a rank-based comparison of independent groups.
• Use paired=True for paired numeric measurements.
• Use method="wilcoxon" for paired rank-based testing.

Categorical Tests

categorical_test accepts a contingency table. With method="auto", Fyron uses Fisher's exact test for sparse 2x2 tables and chi-square otherwise.

result = fst.categorical_test(
    table=[
        [12, 8],
        [4, 16],
    ],
    method="auto",
)

result.test
result.p_value

For larger tables, use chi-square explicitly:

result = fst.categorical_test(
    table=[
        [12, 8, 5],
        [4, 16, 10],
    ],
    method="chi2",
)

Correlation Tests

Spearman is the default because clinical variables are often skewed or ordinal.

result = fst.correlation_test(
    x=[1, 2, 3, 4, 5],
    y=[2.1, 2.9, 3.2, 4.4, 5.1],
    method="spearman",
)

Use method="pearson" when a linear relationship is the planned assumption. Use method="kendall" for small samples or ordinal associations where Kendall's tau is preferred.

Bootstrap A Summary Score

Use bootstrap_summary for uncertainty around a score, biomarker, measurement, or model output distribution.

boot = fst.bootstrap_summary(
    values=cohort["risk_score"],
    statistic="median",
    n_rounds=5000,
    alpha=0.05,
    random_state=42,
)

print(boot.estimate, boot.ci_low, boot.ci_high)

You can also pass a custom one-sample function.

def p90(values):
    import numpy as np

    return float(np.percentile(values, 90))

boot = fst.bootstrap_summary(
    values=cohort["risk_score"],
    statistic=p90,
    n_rounds=2000,
    random_state=42,
)

Bootstrap A Custom Metric

Use bootstrap_metric when the statistic depends on one or more aligned arrays.

import numpy as np
from fyron import statistics as fst

def mean_difference(group, value):
    group = np.asarray(group)
    value = np.asarray(value, dtype=float)
    return float(value[group == 1].mean() - value[group == 0].mean())

boot = fst.bootstrap_metric(
    cohort["treatment_group"],
    cohort["risk_score"],
    metric_func=mean_difference,
    metric_name="risk_score_mean_difference",
    n_rounds=3000,
    random_state=42,
)

The arrays must have the same length. Each bootstrap round samples row indices and passes the resampled arrays to your metric function.

Bootstrap Binary Classification Metrics

Use this for confidence intervals around clinical model metrics.

table = fst.bootstrap_binary_classification_metrics(
    y_true=y_test,
    y_pred=y_pred,
    y_prob=y_prob,
    metrics=[
        "auc",
        "sensitivity",
        "specificity",
        "balanced_accuracy",
        "f1",
    ],
    pos_label=1,
    n_rounds=2000,
    alpha=0.05,
    random_state=42,
)

table

Available metrics:

The result is a DataFrame with metric, estimate, ci_low, ci_high, n_rounds, requested_rounds, dropped_rounds, and alpha.

Effect Sizes And Ratios

Use effect-size helpers when a paper table needs magnitude, not only p-values.

d = fst.cohens_d(group_a, group_b)
v = fst.cramers_v([[10, 5], [3, 12]])
odds = fst.odds_ratio_ci([[10, 5], [3, 12]])

Practical Guidance

• Define the statistical test before looking at the p-value.
• Use random_state for reproducible bootstrap intervals.
• Increase n_rounds for final reports; 1000 is a reasonable development default, while 2000 to 10000 is more common for final tables.
• Keep drop_invalid=True for bootstrap metrics that may be undefined in rare resamples, such as AUC with only one class.
• Report the test name and sample size together with p-values.
• Prefer effect sizes and confidence intervals over p-values alone.