utilities Module#

Helper functions, decorators, and utilities used throughout the Episia package.

This module provides common utility functions for data manipulation, formatting, type checking, and terminal animations.

Decorators#

episia.core.utilities.timer(func)[source]#

Decorator to measure function execution time.

Parameters:: func (Callable) – Function to time
Returns:: Decorated function
Return type:: Callable

episia.core.utilities.validate_input(validator=None, **validators)[source]#

Decorator to validate function inputs.

Parameters:

validator (Callable | None) – General validator for all arguments
**validators (Callable) – Specific validators for named parameters

Returns:

Decorated function

Return type:

Callable

episia.core.utilities.deprecated(version, replacement=None)[source]#

Decorator to mark functions as deprecated.

Parameters:

version (str) – Version when deprecated
replacement (str | None) – Replacement function name

Returns:

Decorated function

Return type:

Callable

episia.core.utilities.memoize(maxsize=128)[source]#

Simple memoization decorator.

Parameters:: maxsize (int) – Maximum cache size
Returns:: Decorated function
Return type:: Callable

Data Utilities#

episia.core.utilities.safe_divide(numerator, denominator, default=nan)[source]#

Safe division with handling of zero denominators.

Parameters:

numerator (Number | ndarray) – Numerator
denominator (Number | ndarray) – Denominator
default (Any) – Value to return when denominator is zero

Returns:

Result of division or default value

Return type:

Number | ndarray

episia.core.utilities.clip_values(values, lower=None, upper=None)[source]#

Clip values to specified bounds.

Parameters:

values (Number | ndarray) – Values to clip
lower (float | None) – Lower bound
upper (float | None) – Upper bound

Returns:

Clipped values

Return type:

Number | ndarray

episia.core.utilities.format_number(value, decimals=3, scientific=False)[source]#

Format number for display.

Parameters:

value (float) – Number to format
decimals (int) – Number of decimal places
scientific (bool) – Use scientific notation

Returns:

Formatted string

Return type:

str

episia.core.utilities.format_pvalue(p)[source]#

Format p-value for display.

Parameters:: p (float) – P-value
Returns:: Formatted p-value
Return type:: str

episia.core.utilities.create_bins(data, n_bins=10, method='equal_width')[source]#

Create bins for histogram or categorization.

Parameters:

data (ndarray) – Data to bin
n_bins (int) – Number of bins
method (str) – ‘equal_width’ or ‘equal_frequency’

Returns:

Bin edges

Return type:

ndarray

Statistical Utilities#

episia.core.utilities.logit(p)[source]#

Logit transformation.

Parameters:: p (float | ndarray) – Probability (0-1)
Returns:: Logit(p)
Return type:: float | ndarray

episia.core.utilities.expit(x)[source]#

Expit (inverse logit) transformation.

Parameters:: x (float | ndarray) – Log-odds value
Returns:: Probability
Return type:: float | ndarray

episia.core.utilities.standardize(x, ddof=1)[source]#

Standardize array (z-score normalization).

Parameters:

x (ndarray) – Array to standardize
ddof (int) – Degrees of freedom for std calculation

Returns:

Standardized array

Return type:

ndarray

episia.core.utilities.winsorize(x, limits=(0.05, 0.05))[source]#

Winsorize array by limiting extreme values.

Parameters:

x (ndarray) – Array to winsorize
limits (Tuple[float, float]) – Tuple of (lower_limit, upper_limit) as proportions

Returns:

Winsorized array

Return type:

ndarray

Context Managers#

episia.core.utilities.numpy_errstate(**kwargs)[source]#

Context manager for numpy error handling.

Parameters:: **kwargs – Numpy error state parameters

Example

with numpy_errstate(divide=’ignore’, invalid=’ignore’):: result = np.divide(a, b)

episia.core.utilities.pandas_display_options(**kwargs)[source]#

Context manager for pandas display options.

Parameters:: **kwargs – Pandas display options

Example

with pandas_display_options(max_rows=10, precision=3):: print(df)

Type Checking#

episia.core.utilities.is_numeric(x)[source]#

Check if value is numeric.

Parameters:: x (Any) – Value to check
Returns:: True if numeric
Return type:: bool

episia.core.utilities.is_integer_array(x)[source]#

Check if array contains only integers.

Parameters:: x (Any) – Array to check
Returns:: True if all values are integers
Return type:: bool

episia.core.utilities.is_binary_array(x)[source]#

Check if array contains only binary values (0/1).

Parameters:: x (Any) – Array to check
Returns:: True if all values are 0 or 1
Return type:: bool

File Utilities#

episia.core.utilities.sanitize_filename(filename)[source]#

Sanitize filename by removing invalid characters.

Parameters:: filename (str) – Original filename
Returns:: Sanitized filename
Return type:: str

Random Utilities#

episia.core.utilities.set_random_seed(seed=None)[source]#

Set random seed for reproducibility.

Parameters:: seed (int | None) – Random seed
Return type:: None

episia.core.utilities.generate_random_id(length=8)[source]#

Generate random ID string.

Parameters:: length (int) – Length of ID
Returns:: Random ID string
Return type:: str

Terminal Animation#

class episia.core.utilities.EpiLoader(message='Working', width=40)[source]#

Bases: object

Premium terminal loading animation — Episia branded.

Displays a multi-line animated block with:

Gradient wave bar (teal → blue → violet, Episia palette)
Pulsing status label
Live elapsed timer
Fully silent in non-TTY contexts (CI, pipes, Jupyter)

Works on Windows, macOS, and Linux. Falls back to ASCII when the terminal does not support Unicode block characters.

Usage:

from episia.core.utilities import EpiLoader

with EpiLoader("Running SEIR model"):
    result = model.run()

with EpiLoader("Generating report", width=50):
    report.save_html("report.html")

Parameters:

message (str)
width (int)

__init__(message='Working', width=40)[source]#

Parameters:

message (str)
width (int)

episia.core.utilities.Spinner = EpiLoader#

Premium terminal loading animation — Episia branded.

Displays a multi-line animated block with:

Gradient wave bar (teal → blue → violet, Episia palette)
Pulsing status label
Live elapsed timer
Fully silent in non-TTY contexts (CI, pipes, Jupyter)

Works on Windows, macOS, and Linux. Falls back to ASCII when the terminal does not support Unicode block characters.

Usage:

from episia.core.utilities import EpiLoader

with EpiLoader("Running SEIR model"):
    result = model.run()

with EpiLoader("Generating report", width=50):
    report.save_html("report.html")

Parameters:

message (str)
width (int)

Examples#

Using decorators:

from episia.core.utilities import timer, deprecated

@timer
def slow_function():
    # This will print execution time
    time.sleep(1)

@deprecated(version="0.2.0", replacement="new_function")
def old_function():
    pass

Using data utilities:

from episia.core.utilities import safe_divide, format_pvalue

# Safe division
result = safe_divide(10, 0, default=float('inf'))

# Format p-value
p_str = format_pvalue(0.0005)  # Returns "<0.001"

Using context managers:

from episia.core.utilities import numpy_errstate

with numpy_errstate(divide='ignore', invalid='ignore'):
    result = np.divide(a, b)  # No warnings

Terminal animation:

from episia.core.utilities import EpiLoader

with EpiLoader("Running SEIR model"):
    result = model.run()  # Shows animated progress