fips.aggregators.ObsAggregator

class fips.aggregators.ObsAggregator(by=None, level=None, freq=None, func='mean', blocks=None)

Aggregates the observation space of an inverse problem.

Builds a sparse (n_agg x n_obs) weight matrix W and applies it to each component of the problem:

z_agg = W @ z  # aggregated observations
H_agg = W @ H  # aggregated forward operator
S_z_agg = W @ S_z @ W.T  # covariance propagation
c_agg = W @ c  # aggregated constant (if vector)

For func='mean' each non-zero entry in row i equals 1/nᵢ (the reciprocal of the group size), so W @ z yields group means and W @ S_z @ W.T scales variances by 1/nᵢ². For func='sum' every entry is 1. Only 'mean' and 'sum' are supported because other functions do not have a well-defined covariance propagation rule.

Grouping interface

Exactly one of by or level must be provided:

• by : an index level name (str), a list of level names, or a callable that accepts the obs pd.Index and returns group labels.

• level + freq : resample a datetime index level at the given pandas offset alias (e.g. level='obs_time', freq='D'). All other index levels are preserved as exact-match grouping keys.

When the obs index has a 'block' level it is always prepended as a grouping key, ensuring observations from different blocks are never merged.

Partial aggregation

blocks restricts aggregation to the named block(s). Observations belonging to other blocks are passed through unchanged via identity rows in W, so the returned arrays cover the full observation space.

type by:

Union[str, list[str], Callable, None]

param by:

Explicit grouping specification. Mutually exclusive with level.

type by:

str | list[str] | Callable, optional

type level:

Optional[str]

param level:

Index level to group / resample. Requires either a matching level name in the obs index or use alongside freq.

type level:

str, optional

type freq:

Optional[str]

param freq:

Pandas offset alias for resampling level (e.g. 'D', 'h').

type freq:

str, optional

type func:

str

param func:

Aggregation function. Default 'mean'.

type func:

{‘mean’, ‘sum’}

type blocks:

Union[str, list[str], None]

param blocks:

Block name(s) to aggregate. Unlisted blocks pass through as-is.

type blocks:

str | list[str], optional

param Apply to inverse problem components:

param ———————————–:

param apply(obs:

Apply the aggregation to the inverse problem components.

param forward_operator:

Apply the aggregation to the inverse problem components.

param modeldata_mismatch:

Apply the aggregation to the inverse problem components.

param constant):

Apply the aggregation to the inverse problem components.

Attributes

by	Explicit grouping specification.
level	Index level to group / resample.
freq	Pandas offset alias for resampling 'level' (e.g. 'D', 'h').
func	Aggregation function, either 'mean' or 'sum'.
blocks	Block name(s) to aggregate.

Methods

apply(obs, forward_operator, modeldata_mismatch)

Apply W to the inverse problem components.