sheap.SheaProducts.Utils.Sample_handlers module

Flattening and Summarizing Utilities

This module provides helpers to: - Concatenate lists of dictionaries with array-like leaves. - Flatten nested “masses” / parameter dictionaries to pandas DataFrames. - Pivot nested results per object into per-object dictionaries. - Summarize posterior samples via 16/50/84 percentiles.

Notes

• All functions are NumPy/JAX friendly; arrays may be numpy.ndarray or jax.numpy.ndarray.

• Percentile summaries follow a common convention:

  median = 50th percentile, err_minus = 50th - 16th, err_plus = 84th - 50th.

flatten_mass_dict(masses)

Flatten a masses dictionary into a DataFrame.

Parameters:

masses (dict) – Mapping line -> {stat_name: {"median": scalar, "err_minus": scalar, "err_plus": scalar}}.

Returns:

Columns: line_name, quantity, median, err_minus, err_plus.

Return type:

pandas.DataFrame

flatten_mass_samples_to_df(dict_samples)

Flatten nested mass sample summaries into a tidy DataFrame.

Parameters:

dict_samples (dict) – Mapping object_name -> {"masses": {line: {quantity: stats_dict}}}. Each stats_dict must have keys median, err_minus, err_plus (scalars or 0-d arrays).

Returns:

Columns: object, line, quantity, median, err_minus, err_plus.

Return type:

pandas.DataFrame

flatten_param_dict(dict_basic_params)

Convert a nested parameter dictionary into a tidy table.

Parameters:

dict_basic_params (dict) – Structure like: {kind: {"lines": [...], "component": [...], <param>: {"median": [...], "err_minus": [...], "err_plus": [...]}, ...}}

Returns:

One row per (line, component, kind, parameter), with median and error bars.

Return type:

pandas.DataFrame

flatten_scalar_dict(name, scalar_dict)

Flatten a scalar-valued dictionary (e.g., L_bol/L_w summaries) into a DataFrame.

Parameters:

• name (str) – Label for the quantity (e.g., "L_bol" or "L_w").

• scalar_dict (dict) – Mapping key -> {"median": scalar, "err_minus": scalar, "err_plus": scalar}.

Returns:

Columns: quantity, wavelength_or_line, median, err_minus, err_plus.

Return type:

pandas.DataFrame

pivot_and_split(obj_names, result)

Two-pass approach:

1. Normalize the tree once: replace uarray leaves with {‘value’: vals, ‘error’: errs} and plain arrays with {‘median’: arr, ‘error’: 0} when leading dim == N.

2. Create per-object slices without calling unumpy again.

summarize_nested_samples(d, run_summarize=True)

Recursively apply summarize_samples() to array-like leaves.

Parameters:

• d (dict) – Nested dictionary whose leaves may be arrays to summarize.

• run_summarize (bool, default True) – If False, returns d unchanged.

Returns:

Same structure as input with arrays replaced by percentile summaries.

Return type:

dict

Notes

• Keys named "component" are passed through untouched (often categorical).

• JAX arrays are accepted; they are converted to NumPy within

  summarize_samples().

summarize_samples(samples)

Summarize a sample vector by 16th/50th/84th percentiles.

Parameters:

samples (array-like) – 1D vector of draws, or 2D array where each column is a separate variable. JAX arrays are accepted and converted to NumPy for percentile computation.

Returns:

{"median": ..., "err_minus": ..., "err_plus": ...}.

Return type:

dict

Notes

• If more than 20% of entries are NaN, a warning is emitted and percentiles are computed with np.nanpercentile.

• For 1D input, returns scalars; for 2D (n, m), returns length-m arrays.

concat_dicts(list_of_dicts)

Concatenate lists/arrays across a list of homogeneous dictionaries.

Parameters:

list_of_dicts (list of dict) – Each dict must share the same keys. Values are arrays (or array-like) that can be concatenated along their first axis.

Returns:

Dictionary with the same keys; each value is the concatenation of the corresponding values across the input list, then transposed (so that samples shape usually becomes (N, ...)).

Return type:

dict

Notes

This is used to merge per-profile/line dictionaries into a single per-region dict. It expects all leaves to be concatenable; non-numeric leaves should be filtered out before calling.

concat_dicts_combine(list_of_dicts)