Segment statistics

segment_statistics describes the segments between detected changepoints: their mean and spread, and the direction and size of each change.

Describe the segments between detected changepoints.

The detectors say where a series changes; segment_statistics says how: the mean and spread of every segment, and for each changepoint the direction and size of the change in mean (issue #42).

SegmentStatistics

Bases: NamedTuple

Per-segment summaries returned by segment_statistics.

All fields are CPU tensors; the statistics are float64. For K changepoints there are K + 1 segments. means and stds have shape [K + 1] for univariate data and [K + 1, D] for [T, D] data; the change fields have K rows.

Attributes:

Name	Type	Description
starts, ends	Tensor	First index and one-past-last index of each segment (long).
lengths	Tensor	Number of observations in each segment (long).
means	Tensor	Sample mean of each segment.
stds	Tensor	Sample standard deviation of each segment (n - 1 in the denominator; 0 for a segment of one observation).
mean_changes	Tensor	means[k + 1] - means[k]: positive when the series moves up at changepoint k.
z_scores	Tensor	mean_changes divided by its standard error sqrt(std_k^2 / n_k + std_{k+1}^2 / n_{k+1}) (Welch). A rough guide to how clearly the mean moved; it ignores that the changepoint was chosen from the same data, so it overstates significance. nan when both segments have zero spread.

segment_statistics(data, starts)

Mean, spread and direction of change for the segments between changepoints.

Parameters:

Name	Type	Description	Default
data	Tensor or array - like	The series, [T] or [T, D].	required
starts	torch.Tensor or sequence of int	Index of the first observation of each new segment, as returned by get_map_changepoints. Index 0 may be included or not. The offline detector reports the last index of the old segment instead, so add 1 to its positions: segment_statistics(data, torch.where(probs > 0.5)[0] + 1).	required

Returns:

Type	Description
SegmentStatistics	See the class for the fields.

Raises:

Type	Description
ValueError	If data is not [T] or [T, D], is complex, or has NaN or Inf, or a start is outside [0, T) or repeated.

Examples:

>>> stats = segment_statistics(data, get_map_changepoints(R))
>>> stats.mean_changes  # tensor([ 3.1, -2.9]): up at the first change, down at the second