superstats.utils#

General utility functions used across superstats.

superstats.utils.prepare_plot_data(estimates, targets, variable_keys=None, variable_names=None)[source]#

Resolve dict-or-array estimates/targets into stacked arrays plus display names.

For dict input, per-key arrays are stacked along a new last axis in the order given by variable_keys (or all keys, by default). For array input, estimates/targets are used as-is and variable_keys is ignored.

Parameters:

estimatesMapping[str, np.ndarray] or np.ndarray: If a dict, per-key arrays sharing the same leading shape, to be stacked into a new last axis. If an array, used directly (already includes the params axis). Must be the same kind (dict or array) as targets.
targetsMapping[str, np.ndarray] or np.ndarray: Same convention as estimates, one fewer axis than estimates in the array case (no sample axis). Must be the same kind (dict or array) as estimates.
variable_keyssequence of str or None, optional, default: None: Which keys to select from estimates/targets when they are dicts, and in what order. By default, all keys, in dict insertion order. Ignored if estimates/targets are arrays.
variable_namessequence of str or None, optional, default: None: Display names for the columns, in the same order as the selected variables. Defaults to variable_keys (if dicts) or param_0, param_1, … (if arrays).

Returns:

estimates_arr, targets_arr, namestuple: Stacked arrays of shape (…, num_params) and a list of display names, one per column.

Raises:

ValueError: If estimates and targets are not both dicts or both arrays, if variable_keys references a key missing from either dict, or if variable_names doesn’t match the number of selected/resolved variables.

Parameters:

estimates (Mapping[str, ndarray] | ndarray)
targets (Mapping[str, ndarray] | ndarray)
variable_keys (Sequence[str] | None)
variable_names (Sequence[str] | None)

Return type:

tuple[ndarray, ndarray, list[str]]

superstats.utils.scaled_sigmoid(x, lower_bound, upper_bound)[source]#

Apply a sigmoid transformation and rescale to a bounded interval.

This function maps input values to a specified range using a scaled sigmoid. The transformation is: lower_bound + (upper_bound - lower_bound) / (1 + exp(-x))

Parameters:

xfloat or np.ndarray: Input value(s) to transform.
lower_boundfloat or np.ndarray: Lower bound of the output range.
upper_boundfloat or np.ndarray: Upper bound of the output range.

Returns:

yfloat or np.ndarray - transformed value(s) in: [lower_bound, upper_bound]

Parameters:

x (float | ndarray)
lower_bound (float | ndarray)
upper_bound (float | ndarray)

Return type:

float | ndarray

Modules

`dispatch`	Dispatch helpers for workflow and generative-model construction.
`logging`	Small logging helpers for superstats.
`plotting`	Shared data preparation helpers for plotting functions.
`transformations`	Parameter transformation functions.