results Module#

Unified rich result classes for Episia public API.

This module provides a consistent result interface across all Episia modules. Every public function returns a subclass of EpiResult, ensuring consistent serialization and visualization.

Base Classes#

class episia.api.results.EpiResult[source]#

Bases: ABC

Abstract base class for all Episia result objects.

All public-API results inherit from this class and share:

  • Serialization: to_dict(), to_json(), to_dataframe()

  • Metadata: confidence, method, warnings

  • Visualization: plot()

plot(backend='plotly', **kwargs)[source]#

Render a visualization of this result.

Parameters:

  • backend (str) – ‘plotly’ (default, interactive) or ‘matplotlib’ (publication).

  • **kwargs – Passed to the underlying plot function.

to_dataframe()[source]#

Return a pandas DataFrame summary of the result.

abstract to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

to_json(indent=2)[source]#

Serialize result to a JSON string.

Parameters:

indent (int)

Return type:

str

class episia.api.results.ConfidenceInterval(lower, upper, confidence=0.95, method='wald')[source]#

Bases: object

Container for a confidence interval.

Parameters:
lower#

Lower bound.

Type:

float

upper#

Upper bound.

Type:

float

confidence#

Confidence level (e.g. 0.95).

Type:

float

method#

Method used to compute the interval.

Type:

str

__init__(lower, upper, confidence=0.95, method='wald')#
Parameters:
Return type:

None

confidence: float = 0.95#
contains(value)[source]#

Return True if value falls within the interval.

Parameters:

value (float)

Return type:

bool

lower: float#
method: str = 'wald'#
to_dict()[source]#
Return type:

Dict[str, Any]

upper: float#

Result Classes#

class episia.api.results.AssociationResult(measure, estimate, ci, p_value=None, null_value=1.0, method='wald', n_total=None, metadata=<factory>)[source]#

Bases: EpiResult

Result for a single association measure (RR, OR, RD…).

Parameters:
measure#

Name of the measure (e.g. ‘risk_ratio’).

Type:

str

estimate#

Point estimate.

Type:

float

ci#

ConfidenceInterval object.

Type:

episia.api.results.ConfidenceInterval

p_value#

P-value for the null hypothesis.

Type:

float | None

null_value#

Null hypothesis value (1.0 for ratios, 0.0 for differences).

Type:

float

method#

Statistical method used.

Type:

str

n_total#

Total sample size.

Type:

int | None

metadata#

Extra key/value pairs (exposed/unexposed counts, etc.).

Type:

Dict[str, Any]

__init__(measure, estimate, ci, p_value=None, null_value=1.0, method='wald', n_total=None, metadata=<factory>)#
Parameters:
Return type:

None

ci: ConfidenceInterval#
estimate: float#
measure: str#
metadata: Dict[str, Any]#
method: str = 'wald'#
n_total: int | None = None#
null_value: float = 1.0#
p_value: float | None = None#
property significant: bool#

True if the CI does not contain the null value.

to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

class episia.api.results.ProportionResult(proportion, ci, numerator=None, denominator=None, label='proportion', metadata=<factory>)[source]#

Bases: EpiResult

Result for a proportion or rate with confidence interval.

Parameters:
proportion#

Point estimate.

Type:

float

ci#

ConfidenceInterval.

Type:

episia.api.results.ConfidenceInterval

numerator#

Event count.

Type:

int | None

denominator#

Population at risk.

Type:

int | None

label#

Human-readable label (e.g. ‘attack_rate’).

Type:

str

metadata#

Extra context.

Type:

Dict[str, Any]

__init__(proportion, ci, numerator=None, denominator=None, label='proportion', metadata=<factory>)#
Parameters:
Return type:

None

ci: ConfidenceInterval#
denominator: int | None = None#
label: str = 'proportion'#
metadata: Dict[str, Any]#
numerator: int | None = None#
proportion: float#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

class episia.api.results.SampleSizeResult(n_total=None, n_per_group=None, n_cases=None, n_controls=None, power=None, alpha=0.05, effect_size=None, design='', method='', assumptions=<factory>, note=None)[source]#

Bases: EpiResult

Result for a sample size or statistical power calculation.

Parameters:
n_total#

Total required sample size.

Type:

int | None

n_per_group#

Per-group size for balanced designs.

Type:

int | None

n_cases#

Cases required (case-control designs).

Type:

int | None

n_controls#

Controls required.

Type:

int | None

power#

Achieved or requested power.

Type:

float | None

alpha#

Significance level.

Type:

float

effect_size#

Effect size used.

Type:

float | None

design#

Study design name.

Type:

str

method#

Calculation method.

Type:

str

assumptions#

Input parameters for traceability.

Type:

Dict[str, Any]

note#

Optional interpretive note.

Type:

str | None

__init__(n_total=None, n_per_group=None, n_cases=None, n_controls=None, power=None, alpha=0.05, effect_size=None, design='', method='', assumptions=<factory>, note=None)#
Parameters:
Return type:

None

alpha: float = 0.05#
assumptions: Dict[str, Any]#
design: str = ''#
effect_size: float | None = None#
method: str = ''#
n_cases: int | None = None#
n_controls: int | None = None#
n_per_group: int | None = None#
n_total: int | None = None#
note: str | None = None#
power: float | None = None#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

class episia.api.results.DiagnosticResult(sensitivity, specificity, ppv, npv, lr_positive, lr_negative, accuracy, youden, tp=0, fp=0, fn=0, tn=0, prevalence=None, ci_sensitivity=None, ci_specificity=None)[source]#

Bases: EpiResult

Result for a diagnostic test performance evaluation.

Parameters:
sensitivity#

True positive rate.

Type:

float

specificity#

True negative rate.

Type:

float

ppv#

Positive predictive value.

Type:

float

npv#

Negative predictive value.

Type:

float

lr_positive#

Positive likelihood ratio.

Type:

float

lr_negative#

Negative likelihood ratio.

Type:

float

accuracy#

Overall accuracy.

Type:

float

youden#

Youden’s J index.

Type:

float

tp, fp, fn, tn

Confusion matrix counts.

prevalence#

Prevalence used (sample or provided).

Type:

float | None

ci_sensitivity#

CI for sensitivity.

Type:

episia.api.results.ConfidenceInterval | None

ci_specificity#

CI for specificity.

Type:

episia.api.results.ConfidenceInterval | None

__init__(sensitivity, specificity, ppv, npv, lr_positive, lr_negative, accuracy, youden, tp=0, fp=0, fn=0, tn=0, prevalence=None, ci_sensitivity=None, ci_specificity=None)#
Parameters:
Return type:

None

accuracy: float#
ci_sensitivity: ConfidenceInterval | None = None#
ci_specificity: ConfidenceInterval | None = None#
fn: int = 0#
fp: int = 0#
lr_negative: float#
lr_positive: float#
npv: float#
ppv: float#
prevalence: float | None = None#
sensitivity: float#
specificity: float#
tn: int = 0#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

tp: int = 0#
youden: float#
class episia.api.results.ROCResult(fpr, tpr, thresholds, auc, optimal_threshold, optimal_point, method='youden')[source]#

Bases: EpiResult

Result for ROC curve analysis.

Parameters:
fpr#

False positive rates array.

Type:

numpy.ndarray

tpr#

True positive rates array.

Type:

numpy.ndarray

thresholds#

Threshold values array.

Type:

numpy.ndarray

auc#

Area under the curve.

Type:

float

optimal_threshold#

Threshold maximising the chosen criterion.

Type:

float

optimal_point#

Dict with sens/spec at optimal threshold.

Type:

Dict[str, float]

method#

Criterion for optimal threshold selection.

Type:

str

__init__(fpr, tpr, thresholds, auc, optimal_threshold, optimal_point, method='youden')#
Parameters:
Return type:

None

auc: float#
fpr: ndarray#
method: str = 'youden'#
optimal_point: Dict[str, float]#
optimal_threshold: float#
thresholds: ndarray#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

tpr: ndarray#
class episia.api.results.StratifiedResult(measure, mh_estimate, ci, p_value=None, homogeneity_p=None, effect_modifier=False, stratum_results=<factory>, n_strata=0)[source]#

Bases: EpiResult

Result for stratified (Mantel-Haenszel) analysis.

Parameters:
measure#

‘mh_risk_ratio’ or ‘mh_odds_ratio’.

Type:

str

mh_estimate#

Pooled MH estimate.

Type:

float

ci#

CI for pooled estimate.

Type:

episia.api.results.ConfidenceInterval

p_value#

P-value for pooled test.

Type:

float | None

homogeneity_p#

P-value for Breslow-Day homogeneity test.

Type:

float | None

effect_modifier#

True if homogeneity rejected (p < 0.05).

Type:

bool

stratum_results#

Per-stratum AssociationResult list.

Type:

List[episia.api.results.AssociationResult]

n_strata#

Number of strata.

Type:

int

__init__(measure, mh_estimate, ci, p_value=None, homogeneity_p=None, effect_modifier=False, stratum_results=<factory>, n_strata=0)#
Parameters:
Return type:

None

ci: ConfidenceInterval#
effect_modifier: bool = False#
homogeneity_p: float | None = None#
measure: str#
mh_estimate: float#
n_strata: int = 0#
p_value: float | None = None#
stratum_results: List[AssociationResult]#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

class episia.api.results.ModelResult(model_type, t, compartments, parameters, r0=None, peak_infected=None, peak_time=None, final_size=None, metadata=<factory>)[source]#

Bases: EpiResult

Result for a compartmental epidemic model simulation.

Parameters:
model_type#

‘SIR’, ‘SEIR’, ‘SEIRD’, etc.

Type:

str

t#

Time array.

Type:

numpy.ndarray

compartments#

Dict of compartment name to array.

Type:

Dict[str, numpy.ndarray]

parameters#

Input parameters (beta, gamma, R0…).

Type:

Dict[str, float]

r0#

Basic reproduction number.

Type:

float | None

peak_infected#

Peak infected count.

Type:

float | None

peak_time#

Time of peak infection.

Type:

float | None

final_size#

Total proportion infected at end.

Type:

float | None

metadata#

Extra simulation context.

Type:

Dict[str, Any]

__init__(model_type, t, compartments, parameters, r0=None, peak_infected=None, peak_time=None, final_size=None, metadata=<factory>)#
Parameters:
Return type:

None

compartments: Dict[str, ndarray]#
final_size: float | None = None#
metadata: Dict[str, Any]#
model_type: str#
parameters: Dict[str, float]#
peak_infected: float | None = None#
peak_time: float | None = None#
r0: float | None = None#
t: ndarray#
to_dataframe()[source]#

Return time-series DataFrame with one column per compartment.

to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

class episia.api.results.TimeSeriesResult(times, values, trend=None, trend_method=None, doubling_time=None, metadata=<factory>)[source]#

Bases: EpiResult

Result for temporal epidemiological analysis (incidence, trends).

Parameters:
times#

Array of time points or period labels.

Type:

numpy.ndarray

values#

Observed values (counts or rates).

Type:

numpy.ndarray

trend#

Fitted trend values (if computed).

Type:

numpy.ndarray | None

trend_method#

Name of trend method used.

Type:

str | None

doubling_time#

Estimated doubling time (if applicable).

Type:

float | None

metadata#

Additional analysis context.

Type:

Dict[str, Any]

__init__(times, values, trend=None, trend_method=None, doubling_time=None, metadata=<factory>)#
Parameters:
Return type:

None

doubling_time: float | None = None#
metadata: Dict[str, Any]#
times: ndarray#
to_dataframe()[source]#

Return a pandas DataFrame summary of the result.

to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

trend: ndarray | None = None#
trend_method: str | None = None#
values: ndarray#
class episia.api.results.RegressionResult(model_type, coefficients, p_values, ci_table, odds_ratios=None, aic=None, bic=None, n=None, converged=True)[source]#

Bases: EpiResult

Result for logistic or Poisson regression.

Parameters:
model_type#

‘logistic’, ‘poisson’, ‘linear’.

Type:

str

coefficients#

Dict of variable to coefficient.

Type:

Dict[str, float]

odds_ratios#

Dict of variable to OR (logistic only).

Type:

Dict[str, float] | None

ci_table#

Dict of variable to (lower, upper) CI tuple.

Type:

Dict[str, Tuple[float, float]]

p_values#

Dict of variable to p-value.

Type:

Dict[str, float]

aic#

Akaike information criterion.

Type:

float | None

bic#

Bayesian information criterion.

Type:

float | None

n#

Sample size.

Type:

int | None

converged#

Whether optimisation converged.

Type:

bool

__init__(model_type, coefficients, p_values, ci_table, odds_ratios=None, aic=None, bic=None, n=None, converged=True)#
Parameters:
Return type:

None

aic: float | None = None#
bic: float | None = None#
ci_table: Dict[str, Tuple[float, float]]#
coefficients: Dict[str, float]#
converged: bool = True#
model_type: str#
n: int | None = None#
odds_ratios: Dict[str, float] | None = None#
p_values: Dict[str, float]#
to_dict()[source]#

Return a JSON-serializable dictionary of all result fields.

Return type:

Dict[str, Any]

Factory Functions#

episia.api.results.make_ci(lower, upper, confidence=0.95, method='wald')[source]#

Convenience factory for ConfidenceInterval.

Parameters:
Return type:

ConfidenceInterval

episia.api.results.make_association(measure, estimate, ci_lower, ci_upper, confidence=0.95, method='wald', p_value=None, null_value=1.0, n_total=None, **metadata)[source]#

Convenience factory for AssociationResult.

Parameters:
Return type:

AssociationResult

episia.api.results.make_proportion(proportion, ci_lower, ci_upper, numerator=None, denominator=None, label='proportion', confidence=0.95, method='wilson')[source]#

Convenience factory for ProportionResult.

Parameters:
Return type:

ProportionResult

On this page
Edit on GitHub
Show Source