Time Varying Sinusoid

timecave.data_generation.time_series_functions.frequency_varying_sinusoid_ts(number_samples, max_interval_size, frequency, amplitude=1, phase=0)

Generate a time series of a sinusoidal signal with varying frequency.

This function generates a time series of a sinusoidal signal where the frequency varies over time.

Parameters:

Name	Type	Description	Default
number_samples	int	The number of samples in the time series.	required
max_interval_size	float	The maximum time interval size for the time series.	required
frequency	BaseFrequency	An object representing the base frequency of the sinusoid, which may vary over time.	required
amplitude	float	The amplitude of the sinusoidal signal.	1
phase	float	The initial phase of the sinusoidal signal in radians.	1

Returns:

Type	Description
ndarray	An array representing the generated time series of the sinusoidal signal with varying frequency.

See also

sinusoid_ts: Generate a simple sinusoid.

Examples:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from timecave.data_generation.frequency_modulation import FrequencyModulationWithStep, FrequencyModulationLinear
>>> from timecave.data_generation.time_series_functions import frequency_varying_sinusoid_ts

Generate a sinusoid whose frequency varies abruptly:

>>> mod = FrequencyModulationWithStep(20, 5);
>>> ts = frequency_varying_sinusoid_ts(100, 10, frequency=mod);
>>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
>>> plt.show();

Time series with linearly varying frequencies can be generated as well:

>>> mod_lin = FrequencyModulationLinear(1, 0.2);
>>> ts2 = frequency_varying_sinusoid_ts(1000, 10, frequency=mod_lin, amplitude=5);
>>> _ = plt.plot(np.arange(0, ts2.shape[0]), ts2);
>>> plt.show();

Source code in timecave/data_generation/time_series_functions.py

def frequency_varying_sinusoid_ts(
    number_samples: int,
    max_interval_size: float,
    frequency: BaseFrequency,
    amplitude: float = 1,
    phase: float = 0,
) -> np.ndarray:
    """
    Generate a time series of a sinusoidal signal with varying frequency.

    This function generates a time series of a sinusoidal signal where the frequency varies over time.

    Parameters
    ----------
    number_samples : int
        The number of samples in the time series.

    max_interval_size : float
        The maximum time interval size for the time series.

    frequency : BaseFrequency
        An object representing the base frequency of the sinusoid, which may vary over time.

    amplitude : float, default=1
        The amplitude of the sinusoidal signal.

    phase : float, default=1
        The initial phase of the sinusoidal signal in radians.

    Returns
    -------
    np.ndarray
        An array representing the generated time series of the sinusoidal signal with varying frequency.

    See also
    --------
    [sinusoid_ts](sinusoid.md): Generate a simple sinusoid.

    Examples
    --------
    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> from timecave.data_generation.frequency_modulation import FrequencyModulationWithStep, FrequencyModulationLinear
    >>> from timecave.data_generation.time_series_functions import frequency_varying_sinusoid_ts

    Generate a sinusoid whose frequency varies abruptly:

    >>> mod = FrequencyModulationWithStep(20, 5);
    >>> ts = frequency_varying_sinusoid_ts(100, 10, frequency=mod);
    >>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
    >>> plt.show();

    ![step_freq](../../../images/Step_freq.png)

    Time series with linearly varying frequencies can be generated as well:

    >>> mod_lin = FrequencyModulationLinear(1, 0.2);
    >>> ts2 = frequency_varying_sinusoid_ts(1000, 10, frequency=mod_lin, amplitude=5);
    >>> _ = plt.plot(np.arange(0, ts2.shape[0]), ts2);
    >>> plt.show();

    ![lin_freq](../../../images/Lin_freq.png)
    """
    _check_number_samples(number_samples)
    _check_max_interval_size(max_interval_size)

    time = np.linspace(0, max_interval_size, number_samples)
    frequency = frequency.modulate(time=time)
    time_series = amplitude * np.sin(2 * np.pi * frequency * time + phase)
    return time_series