lmlib.statespace.cost.Segment#

class lmlib.statespace.cost.Segment(a, b, direction, g, delta=0, label=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]

See also [Wildhaber2018] [Wildhaber2019]

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) – \(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.

  • 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

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