ts-data-generator 0.3.0

A Python library for generating synthetic time series data

Synthetic Time Series Data Generator

A Python library for generating synthetic time series data

^{Special thanks to: Nike-Inc repo}

Installation

For Dev

You can install with uv directly by

uv sync --extra dev

Standalone

uv pip install ts-data-generator

If imputer is required, then uv pip install "ts-data-generator[imputer]". See imputer usage

Usage

1. To check out constructing for time series data, check the sample notebook here
2. To extract the trends from an existing data (requires scipy), check this sample notebook here

UV

You can easily run it using uv

uvx --python 3.11 --from ts-data-generator tsdata generate \
    --start "2019-01-01" \
    --end "2019-01-12" \
    --granularity "5min" \
    --dims "product_id:random_float:1,4" \
    --dims "const:constant:5" 
    --mets "sales:LinearTrend(limit=500)+WeekendTrend(weekend_effect=50)" 
    --mets "trend:LinearTrend(limit=10)" 
    --output "data.csv"

CLI

You can also use the command line utility tsdata to generate the data.

~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ tsdata                  
Usage: tsdata [OPTIONS] COMMAND [ARGS]...

  CLI tool for generating time series data.

Options:
  --help  Show this message and exit.

Commands:
  dimensions  List all available dimension functions in ts_data_generator.utils.functions.
  generate    Generate time series data and save it to a CSV file.
  metrics     List all available metric trends in ts_data_generator.utils.trends.
~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ 

~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ tsdata dimensions       
Available dimension functions are:
- auto_generate_name(category: str) -> str
        Example: name:auto_generate_name:mycat
- constant(value: Union[int, str, float, list])
        Example: name:constant:10
- ordered_choice(iterable)
        Example: name:ordered_choice:A,B,C
- random_choice(iterable: Iterable[~T]) -> Generator[~T, NoneType, NoneType]
        Example: name:random_choice:A,B,C
- random_float(start: float, end: float)
        Example: name:random_float:0.0,1.0
- random_int(start: int, end: int) -> Generator[int, NoneType, NoneType]
        Example: name:random_int:1,100
~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ 

~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ tsdata metrics   
Available metric trends & parameters are:
- LinearTrend(name: str = 'default', offset: float = 0.0, noise_level: float = 0.0, limit: float = 2.0)
        Example: sales:LinearTrend(offset=0,noise_level=1,limit=10)
- SinusoidalTrend(name: str = 'default', amplitude: float = 1, freq: float = 1, phase: float = 0, noise_level: float = 0)
        Example: sales:SinusoidalTrend(amplitude=1,freq=24,phase=0,noise_level=0)
- StockTrend(name: str = 'default', amplitude: float = 15.0, direction: Literal['up', 'down'] = 'up', noise_level: float = 0.0)
        Example: sales:StockTrend(amplitude=15.0,direction='up',noise_level=0.0)
- WeekendTrend(name: str = 'default', weekend_effect: float = 1.0, direction: Literal['up', 'down'] = 'up', noise_level: float = 0.0, limit: float = 10.0)
        Example: sales:WeekendTrend(weekend_effect=10,direction='up',noise_level=0.5,limit=10)
~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ 

~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ tsdata generate
Usage: tsdata generate [OPTIONS]

  Generate time series data and save it to a CSV file.

Options:
  --start TEXT                    Start datetime 'YYYY-MM-DD'
  --end TEXT                      End datetime 'YYYY-MM-DD'
  --granularity [s|min|5min|h|D|W|ME|Y]
                                  Granularity of the time series data
  --dims TEXT                     + separated list of dimensions definition of format 'name:function:values'
  --mets TEXT                     + separated list of metrics definition trends of format 'name:trend(*params)'
  --output TEXT                   Output file name
  --help                          Show this message and exit.
~/G/ts-data-generator on  main! 🐍 (ts-data-generator) $ 

For example you can call this cli tool like below to generate data

tsdata generate \
  --start "2019-01-01" \
  --end "2019-01-12" \
  --granularity "5min" \
  --dims "product:random_choice:A,B,C,D" \
  --dims "product_id:random_float:1,4" \
  --dims "const:constant:5" \
  --mets "sales:LinearTrend(limit=500)+WeekendTrend(weekend_effect=50)" \
  --mets "trend:LinearTrend(limit=10)" \
  --output "data.csv"

Release method

1. git tag <x.x.x>
2. git push origin <x.x.x>