SAS Specification Classes

class mesas.sas.specs.SAS_Spec(spec, data_df)

Bases: object

Blended SAS (StorAge Selection) function specification.

Represents a time-varying SAS function composed of one or more weighted Component objects. Each component defines a piecewise-linear or continuous CDF over cumulative storage (ST). Components are blended at each timestep using their weight time series to produce a single CDF and inverse CDF.

Parameters:

• spec (dict[str, dict]) – Nested dictionary keyed by component label. Each value is a component specification dictionary (passed to Component).

• data_df (pd.DataFrame) – Input time-series data containing any columns referenced by component specifications (e.g. weight columns, parameter columns).

components

Ordered mapping of component labels to Component instances.

Type:

OrderedDict[str, Component]

N

Number of timesteps (set after make_spec_ts is called).

Type:

int

ST

Padded (N, max_breakpoints) matrix of ST breakpoints, or None before make_spec_ts is called.

Type:

np.ndarray | None

P

Corresponding padded probability matrix.

Type:

np.ndarray | None

make_spec_ts(data_df=None)

Build per-timestep CDF and inverse-CDF interpolators.

Blends all component SAS functions at each timestep using their respective weights and constructs piecewise-linear interpolation objects for the forward and inverse CDF.

Parameters:

data_df (pd.DataFrame or None, optional) – Override data frame. If None, uses the data frame passed at construction.

Return type:

None

inv(P, i)

Evaluate the inverse CDF (quantile function) at a given timestep.

Parameters:

• P (np.ndarray or float) – Cumulative probabilities in [0, 1].

• i (int) – Zero-based timestep index.

Returns:

Cumulative storage (ST) values corresponding to P.

Return type:

np.ndarray

get_parameter_list()

Return concatenated parameter arrays from all learnable components.

Returns:

1-D array of all SAS function parameters, ordered by component.

Return type:

np.ndarray

update_from_parameter_list(parameter_list)

Update component parameters and rebuild interpolators.

Distributes entries of parameter_list across each learnable component’s SAS function, then calls make_spec_ts to refresh the per-timestep CDF interpolators.

Parameters:

parameter_list (np.ndarray) – 1-D array with the same length as get_parameter_list().

Return type:

None

subdivided_copy(label, segment, **kwargs)

Return a copy with one component’s piecewise segment split in two.

Parameters:

• label (str) – Which component’s SAS function to subdivide.

• segment (int) – Which segment to subdivide (numbered from 0 for the youngest).

• **kwargs – Forwarded to the SAS function’s subdivided_copy method (e.g. split_frac).

Returns:

A new spec with the subdivided component; interpolators rebuilt.

Return type:

SAS_Spec

plot(ax=None, **kwargs)

Plot the SAS function for each component.

Parameters:

• ax (matplotlib.axes.Axes or None, optional) – Axes to draw on. A new figure is created if None.

• **kwargs – Additional keyword arguments forwarded to each component’s plot method.

Returns:

Mapping of component labels to the line objects returned by each component’s plot call.

Return type:

dict[str, Any]

get_jacobian(*args, index=None, **kwargs)

Compute the Jacobian of the blended SAS function w.r.t. parameters.

Calls get_jacobian on each learnable component’s SAS function, weights the result, and concatenates column-wise.

Parameters:

• *args (Any) – Positional arguments forwarded to each component’s get_jacobian.

• index (np.ndarray or None, optional) – Timestep indices at which to evaluate. Defaults to all timesteps.

• **kwargs – Additional keyword arguments forwarded to each component’s get_jacobian.

Returns:

Jacobian matrix with shape (len(index), total_params).

Return type:

np.ndarray

class mesas.sas.specs.Component(label, spec, data_df, is_only_component)

Bases: object

A single SAS function component with an associated weight time series.

A Component pairs a per-timestep SAS function (either Piecewise or Continuous) with a weight series so that multiple components can be blended by SAS_Spec.

Parameters:

• label (str) – Identifier for this component, used as a key in SAS_Spec and as a column name in data_df for the weight series (when there are multiple components).

• spec (dict) – Specification dictionary. Must contain either "ST" (and optionally "P") keys for piecewise-linear SAS functions, or "args" with "func"/"scipy.stats" keys for continuous distributions. Values may be scalars, lists, or column-name strings referencing data_df.

• data_df (pd.DataFrame) – Input time-series data frame.

• is_only_component (bool) – If True, weights default to 1.0 for every timestep instead of being read from data_df.

label

Component identifier.

Type:

str

weights

Per-timestep blending weights.

Type:

pd.Series

type

Internal SAS function type code (-1 for scipy/piecewise).

Type:

int

N

Number of timesteps.

Type:

int

expand(value)

Expand a specification value into a per-timestep array.

Scalars are broadcast to all timesteps, strings are looked up as columns in the data frame, and iterables are recursively expanded and stacked.

Parameters:

value (float, str, or Iterable) – A scalar constant, a column name in the data frame, or a sequence of such values (one per breakpoint).

Returns:

Array of shape (N,) for scalar/string inputs or (N, len(value)) for iterable inputs, where N is the number of timesteps.

Return type:

np.ndarray

property ST: ndarray

Stacked ST breakpoints from all timesteps, shape (n_breakpoints, N).

property P: ndarray

Stacked P breakpoints from all timesteps, shape (n_breakpoints, N).

property argsS: ndarray

Stacked argsS arrays from all timesteps.

property argsP: ndarray

Stacked argsP arrays from all timesteps.

property sas_fun: list[Continuous | Piecewise]

List of per-timestep SAS function objects.

plot(*args, i=0, **kwargs)

Plot the component’s SAS function at one timestep.

Parameters:

• *args (Any) – Positional arguments forwarded to the SAS function’s plot.

• i (int, optional) – Timestep index of the SAS function to plot. Default 0.

• **kwargs – Keyword arguments forwarded to the SAS function’s plot. The component label is automatically included.

Returns:

Return value from the underlying SAS function’s plot method.

Return type:

Any