lmlib.statespace.cost.Segment#

class lmlib.statespace.cost.Segment(a, b, direction, g, delta=0, label=None, gamma=None)#

Bases: object

Segment represents a window of finite or infinite interval borders used to select and weight signal samples in a cost function.

Segments are commonly used in combination with ALSSM signal models to select and weight the samples in cost functions, see CostSegment or CompositeCost. The window of a segment either has an exponentially decaying shape or is defined by the output of its own ALSSM model, denoted ast the window ALSSM. The selection of a window also controls the direction of a stable recursive cost computation (forward or backward).

In cunjunction with an ALSSM, a Segment leads to a cost function of the form

\[J_k(x) = \sum_{i=k+a}^{k+b} \gamma^{i-k-\delta}\big(CA^{i-k}x - y_i\big)^2 \ ,\]

and when additionally using sample weights \(v_k\), of the form

\[J_k(x) = \sum_{i=k+a}^{k+b} v_k {\alpha}_{k+\delta}(k+\delta) \big(CA^{i-k}x - y_i\big)^2 \ ,\]

with the sample weights \(v_k\) and the window weight \(\alpha_k(j)\) which depends on the sample weights, see Equation (14) in [Wildhaber2018]

Parameters

a (int, np.inf) – Left boundary of the segment’s interval
b (int, np.inf) – Right boundary of the segment’s interval
g (int, float, None) – \(g > 0\). Effective number of samples under the window. This is used as a (more readable) surrogate for the window decay of exponential windows, see [Wildhaber2018].
\(g\) is counted to the left or right of \(k+ \delta\), for for forward or backward computation direction, respectively.
direction (str) – Computation direction of recursive computations (also selects a left- or right-side decaying window)
statespace.FORWARD or ‘fw’ use forward computation with forward recursions
statespace.BACKWARD or ‘bw’ use backward computation with backward recursions
delta (int, optional) – Exponential window is normalized to 1 at relative index delta.
gamma (float, int) – Window Constant Decay, (Alternative for g. If gamma is set g has to be None) gamma is to choose dependent of the direction (forward, backward). Forward directions with gamma <= 1 will raise a warning for possible instability, backwards directions with gamma >= 1. See [Wildhaber2018] Table IV
label (str, None, optional) – Segment label, useful for debugging in more complex systems (default: label = None)

Notes

The interval of the semgment includes both boundaries a and b into the calculations. i.e., if the sum runs over the interval \(k \in [a,b] \) samples.

Examples

>>> segment = lm.Segment(a=-20, b=-1, direction=lm.FORWARD, g=15)
>>> print(segment)
Segment : a:-20, b:-1, fw, g:15, delta:0, label: None

>>> segment = lm.Segment(a=-0, b=100, direction=lm.BACKWARD, g=15, delta=30, label="right-sided window with shift")
>>> print(segment)
Segment : a:0, b:100, bw, g:15, delta:30, label: right-sided window with shift

Methods

`__init__`(a, b, direction, g[, delta, label, ...])
`set_boundaries`(a, b)
`window`([thd])	Returns the per-sample window weighs

Attributes

`a`	Left boundary of the segment's interval \(a\)
`b`	Right boundary of the segment's interval \(b\)
`delta`	Relative window shift \(\delta\)
`direction`	Sets the segment's recursion computation direction
`g`	Effective number of samples \(g\), setting the window with
`gamma`	Window decay factor \(\gamma\)
`label`	Label of the segment

property a#

Left boundary of the segment’s interval \(a\)

Type: int, np.inf

property b#

Right boundary of the segment’s interval \(b\)

Type: int, np.inf

property delta#

Relative window shift \(\delta\)

Type: int

property direction#

Sets the segment’s recursion computation direction

FORWARD, FW or ‘fw’ use forward computation with forward recursions
BACKWARD, BW or ‘bw’ use backward computation with backward recursions

Type: str

property g#

Effective number of samples \(g\), setting the window with

The effective number of samples \(g\) is used to derive and set the window decay factor \(\gamma\) internally.

[Wildhaber2018] [Section III.A]

Type: int, float, None

property gamma#

Window decay factor \(\gamma\)

Window decay factor \(\gamma\) is set internally on the initialization of a new segment object and is derived from the effective number of samples Segment.g as follows:

for a segment with forward recursions: \(\gamma = \frac{g}{g-1}\)
for a segment with forward recursions: \(\gamma = \big(\frac{g}{g-1}\big)^{-1}\)

[Wildhaber2018] [Table IV]

Type: float

property label#

Label of the segment

Type: str, None

window(thd=1e-06)#

Returns the per-sample window weighs

The return values are the window weights \(\alpha_{\delta}(i) \quad \forall i \in [a, b]\) for a constant \(\gamma\). The window weight function is defined as

\[w_i = \gamma^{i}\]

For more details see [Wildhaber2018].

Parameters

thd (float, None, optional) – Threshold for infinite Segment boundaries. Crops any window weight below the threshold.

Returns

range of length JR: relative index range of window with respect to segment’s boundaries.
array of shape=(JR) of floats: per-index window weight over the reported index range

Return type

tuple (range, array)

JR : index range length

Examples

lmlib.statespace.cost.RLSAlssmSteadyState

lmlib.statespace.backend