Synthetic data

Data generation utilities for testing changepoint detection algorithms.

This module provides functions to generate synthetic time series data with known changepoints for testing and benchmarking changepoint detection methods.

generate_normal_time_series(num_segments, min_length=50, max_length=1000, seed=42, device=None)

Generate univariate time series with changepoints in mean and variance.

Creates a time series consisting of multiple segments, each with different Gaussian parameters (mean and variance).

Parameters:

Name	Type	Description	Default
num_segments	int	Number of segments to generate.	required
min_length	int	Minimum length of each segment (default: 50).	50
max_length	int	Maximum length of each segment (default: 1000).	1000
seed	int or None	Random seed for reproducibility (default: 42).	42
device	str, torch.device, or None	Device to place tensors on.	None

Returns:

Name	Type	Description
partition	Tensor	Length of each segment. Shape: [num_segments].
data	Tensor	Generated time series data. Shape: [T, 1] where T is total length.

Examples:

>>> partition, data = generate_normal_time_series(3, 50, 200, seed=42)
>>> print(f"Generated {len(data)} data points in {len(partition)} segments")
>>> print(f"Segment lengths: {partition}")

Notes

Each segment has: - Mean sampled from Normal(0, 10²) - Standard deviation sampled from |Normal(0, 1)| + 0.1 (kept away from 0)

generate_multivariate_normal_time_series(num_segments, dims, min_length=50, max_length=1000, seed=42, device=None)

Generate multivariate time series with changepoints in mean and covariance.

Creates a multivariate time series with segments having different Gaussian parameters (mean vectors and covariance matrices).

Parameters:

Name	Type	Description	Default
num_segments	int	Number of segments to generate.	required
dims	int	Dimensionality of the time series.	required
min_length	int	Minimum length of each segment (default: 50).	50
max_length	int	Maximum length of each segment (default: 1000).	1000
seed	int or None	Random seed for reproducibility (default: 42).	42
device	str, torch.device, or None	Device to place tensors on.	None

Returns:

Name	Type	Description
partition	Tensor	Length of each segment. Shape: [num_segments].
data	Tensor	Generated time series data. Shape: [T, dims] where T is total length.

Examples:

>>> partition, data = generate_multivariate_normal_time_series(3, 5, seed=42)
>>> print(f"Generated {data.shape[0]} time points with {data.shape[1]} dimensions")
>>> print(f"Segment lengths: {partition}")

Notes

Each segment has: - Mean vector sampled from Normal(0, 10²) for each dimension - Covariance matrix generated as A @ A.T where A ~ Normal(0, 1)

generate_correlation_change_example(min_length=50, max_length=1000, seed=42, device=None)

Generate the motivating example from Xiang & Murphy (2007).

Creates a 2D time series with three segments that have the same mean but different correlation structures, demonstrating changepoints that are only detectable through covariance changes.

Parameters:

Name	Type	Description	Default
min_length	int	Minimum length of each segment (default: 50).	50
max_length	int	Maximum length of each segment (default: 1000).	1000
seed	int or None	Random seed for reproducibility (default: 42).	42
device	str, torch.device, or None	Device to place tensors on.	None

Returns:

Name	Type	Description
partition	Tensor	Length of each segment. Shape: [3].
data	Tensor	Generated time series data. Shape: [T, 2] where T is total length.

Examples:

>>> partition, data = generate_correlation_change_example(seed=42)
>>> print(f"Generated correlation change example with segments: {partition}")

Notes

The three segments have covariance matrices: 1. [[1.0, 0.75], [0.75, 1.0]] - Positive correlation 2. [[1.0, 0.0], [0.0, 1.0]] - No correlation 3. [[1.0, -0.75], [-0.75, 1.0]] - Negative correlation

All segments have zero mean, so changepoints are only in correlation.

References

Xiang, X., & Murphy, K. (2007). Modeling changing dependency structure in multivariate time series. ICML, 1055-1062.

generate_mean_shift_example(num_segments=4, segment_length=100, shift_magnitude=3.0, noise_std=1.0, seed=42, device=None)

Generate time series with abrupt mean shifts.

Creates a time series with segments of equal length but different means, useful for testing basic changepoint detection capabilities.

Parameters:

Name	Type	Description	Default
num_segments	int	Number of segments (default: 4).	4
segment_length	int	Length of each segment (default: 100).	100
shift_magnitude	float	Magnitude of mean shifts between segments (default: 3.0).	3.0
noise_std	float	Standard deviation of noise (default: 1.0).	1.0
seed	int or None	Random seed for reproducibility (default: 42).	42
device	str, torch.device, or None	Device to place tensors on.	None

Returns:

Name	Type	Description
partition	Tensor	Length of each segment. Shape: [num_segments].
data	Tensor	Generated time series data. Shape: [T, 1] where T is total length.

Examples:

>>> partition, data = generate_mean_shift_example(4, 100, shift_magnitude=2.0)
>>> print(f"Generated mean shift example: {len(data)} points, {len(partition)} segments")

Notes

Means alternate between 0 and shift_magnitude, creating a step function pattern that should be easy to detect.

generate_variance_change_example(num_segments=3, segment_length=150, variance_levels=None, seed=42, device=None)

Generate time series with variance changes but constant mean.

Creates segments with the same mean but different variances, testing the ability to detect heteroscedastic changepoints.

Parameters:

Name	Type	Description	Default
num_segments	int	Number of segments (default: 3).	3
segment_length	int	Length of each segment (default: 150).	150
variance_levels	Tensor or None	Variance levels for each segment. If None, uses [0.5, 2.0, 0.8].	None
seed	int or None	Random seed for reproducibility (default: 42).	42
device	str, torch.device, or None	Device to place tensors on.	None

Returns:

Name	Type	Description
partition	Tensor	Length of each segment. Shape: [num_segments].
data	Tensor	Generated time series data. Shape: [T, 1] where T is total length.

Examples:

>>> partition, data = generate_variance_change_example(3, 100)
>>> print(f"Generated variance change example with {len(data)} points")

Notes

All segments have zero mean, so changepoints are only detectable through variance changes. This tests the algorithm's sensitivity to second-moment changes.

generate_multinormal_time_series(*args, **kwargs)

Backward compatibility wrapper for generate_multivariate_normal_time_series.

generate_xuan_motivating_example(*args, **kwargs)

Backward compatibility wrapper for generate_correlation_change_example.