calculator Module

Optimized calculator classes with caching for epidemiological computations.

This module provides cached calculator implementations that improve performance for repeated calculations and provide consistent interfaces.

Classes

class episia.core.calculator.CacheStrategy(value)

Bases: Enum

Caching strategies for calculators.

LRU = 'lru'

MANUAL = 'manual'

NONE = 'none'

class episia.core.calculator.CalculationStats(call_count=0, cache_hits=0, total_time=0.0, last_call_time=0.0)

Bases: object

Statistics about calculation performance.

Parameters:

• call_count (int)

• cache_hits (int)

• total_time (float)

• last_call_time (float)

__init__(call_count=0, cache_hits=0, total_time=0.0, last_call_time=0.0)

Parameters:

• call_count (int)

• cache_hits (int)

• total_time (float)

• last_call_time (float)

Return type:

None

property average_time: float

Average calculation time in milliseconds.

property cache_hit_rate: float

Cache hit rate as percentage.

cache_hits: int = 0

call_count: int = 0

last_call_time: float = 0.0

total_time: float = 0.0

class episia.core.calculator.BaseCalculator(cache_strategy=CacheStrategy.LRU)

Bases: object

Base class for all calculators with built-in caching and statistics.

Features: - Automatic caching of results - Performance statistics - Input validation hooks - Consistent error handling

Parameters:

cache_strategy (CacheStrategy)

__init__(cache_strategy=CacheStrategy.LRU)

Parameters:

cache_strategy (CacheStrategy)

cached_method(func)

Decorator for caching method results.

Parameters:

func (Callable) – Method to cache

Returns:

Decorated method with caching

Return type:

Callable

clear_cache()

Clear all cached results.

Return type:

None

disable_cache()

Disable caching temporarily.

Return type:

None

enable_cache()

Enable caching.

Return type:

None

class episia.core.calculator.EpidemiologicalCalculator(cache_strategy=CacheStrategy.LRU)

Bases: BaseCalculator

Calculator for common epidemiological computations.

Provides cached implementations of frequently used calculations.

Parameters:

cache_strategy (CacheStrategy)

__init__(cache_strategy=CacheStrategy.LRU)

Parameters:

cache_strategy (CacheStrategy)

attributable_fraction_exposed(rr)

Calculate attributable fraction among exposed.

Parameters:

rr (float) – Risk ratio

Returns:

Attributable fraction

Return type:

float

binomial_probability(k, n, p)

Calculate binomial probability P(X = k).

Parameters:

• k (int) – Number of successes

• n (int) – Number of trials

• p (float) – Probability of success

Returns:

Binomial probability

Return type:

float

confidence_interval_proportion(p, n, confidence=0.95)

Calculate confidence interval for proportion.

Parameters:

• p (float) – Proportion

• n (int) – Sample size

• confidence (float) – Confidence level (0-1)

Returns:

Tuple of (lower, upper)

Return type:

tuple

odds_ratio(a, b, c, d)

Calculate odds ratio with caching.

Parameters:

• a (int) – 2x2 table cells

• b (int) – 2x2 table cells

• c (int) – 2x2 table cells

• d (int) – 2x2 table cells

Returns:

Odds ratio

Return type:

float

poisson_probability(k, lambda_)

Calculate Poisson probability P(X = k).

Parameters:

• k (int) – Number of events

• lambda – Rate parameter

• lambda_ (float)

Returns:

Poisson probability

Return type:

float

population_attributable_fraction(rr, p_exposed)

Calculate population attributable fraction.

Parameters:

• rr (float) – Risk ratio

• p_exposed (float) – Proportion exposed in population

Returns:

Population attributable fraction

Return type:

float

risk_ratio(a, b, c, d)

Calculate risk ratio with caching.

Parameters:

• a (int) – 2x2 table cells

• b (int) – 2x2 table cells

• c (int) – 2x2 table cells

• d (int) – 2x2 table cells

Returns:

Risk ratio

Return type:

float

standard_error_proportion(p, n)

Calculate standard error of a proportion.

Parameters:

• p (float) – Proportion (0-1)

• n (int) – Sample size

Returns:

Standard error

Return type:

float

class episia.core.calculator.MatrixCalculator(cache_strategy=CacheStrategy.LRU)

Bases: BaseCalculator

Calculator for matrix operations used in epidemiological models.

Parameters:

cache_strategy (CacheStrategy)

__init__(cache_strategy=CacheStrategy.LRU)

Parameters:

cache_strategy (CacheStrategy)

basic_reproduction_number(next_generation_matrix)

Calculate basic reproduction number R0.

Parameters:

next_generation_matrix (ndarray) – Matrix K

Returns:

R0 (spectral radius of K)

Return type:

float

effective_reproduction_number(R0, susceptible_proportion)

Calculate effective reproduction number Rt.

Parameters:

• R0 (float) – Basic reproduction number

• susceptible_proportion (float) – Proportion susceptible

Returns:

Effective reproduction number

Return type:

float

next_generation_matrix(transmission_matrix, duration_matrix)

Calculate next generation matrix R0 = K = T * D.

Parameters:

• transmission_matrix (ndarray) – Matrix T

• duration_matrix (ndarray) – Matrix D

Returns:

Next generation matrix K

Return type:

ndarray

Functions

episia.core.calculator.cached_function(maxsize=128)

Decorator for caching function results.

Parameters:

maxsize (int) – Maximum cache size

Returns:

Decorated function

Singleton Instances

episia.core.calculator.epi_calculator = EpidemiologicalCalculator()

Calculator for common epidemiological computations.

Provides cached implementations of frequently used calculations.

episia.core.calculator.matrix_calculator = MatrixCalculator()

Calculator for matrix operations used in epidemiological models.

Examples

Basic usage of epidemiological calculator:

from episia.core.calculator import epi_calculator

# Calculate risk ratio with automatic caching
rr = epi_calculator.risk_ratio(a=40, b=10, c=20, d=30)

# View performance statistics
print(f"Cache hit rate: {epi_calculator.stats.cache_hit_rate:.1f}%")

Using cached function decorator:

from episia.core.calculator import cached_function

@cached_function(maxsize=100)
def expensive_computation(x, y):
    # Expensive calculation here
    return x ** y