utils Module#

Shared utility functions for Episia visualizations.

These utilities are used internally by the viz modules but are exported for advanced users who want to build custom plots with consistent styling.

Functions#

Color utilities#

episia.viz.utils.hex_to_rgb(hex_color)[source]#

Convert ‘#rrggbb’ to (r, g, b) tuple.

Parameters:: hex_color (str)
Return type:: Tuple[int, int, int]

episia.viz.utils.hex_to_rgba_str(hex_color, alpha=1.0)[source]#

Convert ‘#rrggbb’ to ‘rgba(r,g,b,a)’ string for Plotly.

Parameters:

hex_color (str)
alpha (float)

Return type:

str

episia.viz.utils.adjust_alpha(hex_color, alpha)[source]#

Return rgba string with given alpha convenience wrapper.

Parameters:

hex_color (str)
alpha (float)

Return type:

str

Scale utilities#

episia.viz.utils.nice_log_ticks(vmin, vmax)[source]#

Generate clean tick values for a log-scale axis.

Parameters:

vmin (float) – Minimum positive value.
vmax (float) – Maximum positive value.

Returns:

List of tick values (powers of 10 with optional midpoints).

Return type:

List[float]

episia.viz.utils.symlog_range(values, margin=0.05)[source]#

Return (min, max) range for an axis with symmetric margin.

Parameters:

values (ndarray) – Data values.
margin (float) – Fractional margin to add on each side.

Returns:

(axis_min, axis_max) tuple.

Return type:

Tuple[float, float]

CI band utilities#

episia.viz.utils.ci_band_xy(x, lower, upper)[source]#

Build (x_filled, y_filled) lists for a filled CI band (Plotly toself).

Parameters:

x (ndarray) – Time / x-axis values.
lower (ndarray) – Lower CI bound.
upper (ndarray) – Upper CI bound.

Returns:

(x_poly, y_poly) for go.Scatter(fill=’toself’).

Return type:

Tuple[List, List]

Annotation utilities#

episia.viz.utils.p_value_label(p)[source]#

Format a p-value as a readable string.

p < 0.001 → ‘p<0.001’ p < 0.01 → ‘p<0.01’ p < 0.05 → ‘p<0.05’ p >= 0.05 → ‘NS (p=x.xxx)’

Parameters:: p (float | None)
Return type:: str

episia.viz.utils.significance_stars(p)[source]#

Return significance stars for a p-value.

p < 0.001 → ‘*’ p < 0.01 → ‘’ p < 0.05 → ‘*’ else → ‘ns’

Parameters:: p (float | None)
Return type:: str

Figure sizing#

episia.viz.utils.auto_height(n_rows, row_px=36, min_px=300, max_px=900)[source]#

Calculate a sensible figure height for n_rows of data.

Parameters:

n_rows (int) – Number of data rows / strata.
row_px (int) – Pixels per row.
min_px (int) – Minimum figure height.
max_px (int) – Maximum figure height.

Returns:

Height in pixels.

Return type:

int

episia.viz.utils.px_to_inches(px, dpi=100)[source]#

Convert pixels to inches for Matplotlib figure sizing.

Parameters:

px (int)
dpi (int)

Return type:

float

Examples#

Creating consistent colors:

from episia.viz.utils import hex_to_rgba_str

# Convert hex to rgba with transparency
rgba = hex_to_rgba_str("#1f77b4", alpha=0.3)
# Returns: "rgba(31,119,180,0.3)"

Log scale ticks:

from episia.viz.utils import nice_log_ticks

# Generate clean ticks for range 1 to 10000
ticks = nice_log_ticks(1, 10000)
# Returns: [1, 2, 5, 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000]

P-value formatting:

from episia.viz.utils import p_value_label, significance_stars

print(p_value_label(0.023))  # "p=0.023"
print(significance_stars(0.023))  # "*"

print(p_value_label(0.0005))  # "p<0.001"
print(significance_stars(0.0005))  # "***"

CI band polygon:

from episia.viz.utils import ci_band_xy

x_poly, y_poly = ci_band_xy(
    x=time_points,
    lower=ci_lower,
    upper=ci_upper
)
# Ready for plotly fill="toself"