ts-data-generator 0.0.1a1__tar.gz

ts_data_generator-0.0.1a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MANOJ MANIVANNAN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ts_data_generator-0.0.1a1/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.3
+Name: ts-data-generator
+Version: 0.0.1a1
+Summary: A Python library for generating synthetic time series data
+License: MIT
+Keywords: synthetic data,data generator,python,time series
+Author: Manoj Manivannan
+Author-email: manojm18@live.in
+Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Provides-Extra: dev
+Requires-Dist: black ; extra == "dev"
+Requires-Dist: flake8 ; extra == "dev"
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: pydantic
+Requires-Dist: pytest
+Requires-Dist: python-dotenv
+Description-Content-Type: text/markdown
+
+<!-- html title in the middle -->
+<p style="text-align: center;">
+    <h1 align="center">Synthetic Time Series Data Generator</h1>
+    <h3 align="center">A Python library for generating synthetic time series data</h3>
+</p>
+<p align="center">
+<img src="notebooks/image.png" alt="MarineGEO circle logo" style="height: 1000px; width:800px;"/>
+</p>
+
+
+<!-- insert image from notebooks directory -->
+
+
+
+## Installation
+
+### Repo
+After cloning this repo and creating a virtual environment, run the following command:
+```bash
+pip install --editable .
+```
+### PyPi
+Coming soon
+
+
+## Usage
+
+```python
+d = DataGen()
+d.start_datetime = "2019-01-01"
+d.end_datetime = "2019-01-03"
+d.granularity = Granularity.FIVE_MIN
+d.add_dimension("product", random_choice(["A", "B", "C", "D"]))
+
+metric1_trend = SinusoidalTrend(name="sine", amplitude=10, freq=24, phase=0, noise_level=10)
+
+d.add_metric(name="temperature", trends=[metric1_trend])
+
+metric2_trend = SinusoidalTrend(name="sine", amplitude=1, freq=12, phase=0, noise_level=2)
+metric3_trend = LinearTrend(name="linear", limit=100, offset=10, noise_level=1)
+
+d.add_metric(name="humidity", trends=[metric2_trend,metric3_trend])
+d.generate_data()
+df = d.data
+
+# Use utility functions
+processed_df = some_function(df)
+```
+
+#### Release method
+1. `git tag <x.x.x>`
+2. `git push origin <x.x.x>`

ts_data_generator-0.0.1a1/README.md

@@ -0,0 +1,52 @@
+<!-- html title in the middle -->
+<p style="text-align: center;">
+    <h1 align="center">Synthetic Time Series Data Generator</h1>
+    <h3 align="center">A Python library for generating synthetic time series data</h3>
+</p>
+<p align="center">
+<img src="notebooks/image.png" alt="MarineGEO circle logo" style="height: 1000px; width:800px;"/>
+</p>
+
+
+<!-- insert image from notebooks directory -->
+
+
+
+## Installation
+
+### Repo
+After cloning this repo and creating a virtual environment, run the following command:
+```bash
+pip install --editable .
+```
+### PyPi
+Coming soon
+
+
+## Usage
+
+```python
+d = DataGen()
+d.start_datetime = "2019-01-01"
+d.end_datetime = "2019-01-03"
+d.granularity = Granularity.FIVE_MIN
+d.add_dimension("product", random_choice(["A", "B", "C", "D"]))
+
+metric1_trend = SinusoidalTrend(name="sine", amplitude=10, freq=24, phase=0, noise_level=10)
+
+d.add_metric(name="temperature", trends=[metric1_trend])
+
+metric2_trend = SinusoidalTrend(name="sine", amplitude=1, freq=12, phase=0, noise_level=2)
+metric3_trend = LinearTrend(name="linear", limit=100, offset=10, noise_level=1)
+
+d.add_metric(name="humidity", trends=[metric2_trend,metric3_trend])
+d.generate_data()
+df = d.data
+
+# Use utility functions
+processed_df = some_function(df)
+```
+
+#### Release method
+1. `git tag <x.x.x>`
+2. `git push origin <x.x.x>`

ts_data_generator-0.0.1a1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ts_data_generator"]
+
+[project]
+name = "ts-data-generator"
+version = "0.0.1a1"
+description = "A Python library for generating synthetic time series data"
+requires-python = ">=3.8"
+dependencies = [
+    "pytest",
+    "python-dotenv",
+    "pandas",
+    "pydantic",
+    "matplotlib"
+]
+readme = "README.md"
+authors = [
+    { name = "Manoj Manivannan", email = "manojm18@live.in" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = ["synthetic data", "data generator", "python", "time series"]
+
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+testpaths = [
+    "tests",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "flake8",
+]
+

ts_data_generator-0.0.1a1/src/ts_data_generator/__init__.py

@@ -0,0 +1,8 @@
+"""
+Data Generator Library - A tool for generating synthetic data
+"""
+
+from .data_gen import DataGen
+
+__version__ = "0.1.0"
+__all__ = ["DataGen"]

ts_data_generator-0.0.1a1/src/ts_data_generator/data_gen.py

@@ -0,0 +1,387 @@
+"""
+Core DataGen class implementation
+"""
+
+from typing import Optional, Union, Dict, Set, List, Generator
+from .schema.models import Metrics, Dimensions, Granularity
+from .utils.trends import Trends
+import pandas as pd
+from datetime import datetime
+
+
+class DataGen:
+    """Main class for generating synthetic data"""
+
+    def __init__(
+        self,
+        dimensions: List[Dimensions] = None,
+        metrics: List[Metrics] = None,
+        start_datetime: Optional[str] = None,
+        end_datetime: Optional[str] = None,
+        granularity: Granularity = Granularity.FIVE_MIN,
+    ):
+        """Initialize DataGen with empty data"""
+
+        self._dimensions = dimensions or []  # Initialize to an empty set if None
+        self._metrics = metrics or []  # Initialize to an empty set if None
+        self._start_datetime = start_datetime
+        self._end_datetime = end_datetime
+        self._granularity = granularity
+
+    def __repr__(self):
+        return f"""DataGen Class
+            dimensions  = {[d.to_json() for d in self._dimensions]}, 
+            metrics     = {[m.to_json() for m in self._metrics]}, 
+            start_datetime  = {self.start_datetime}, 
+            end_datetime    = {self.end_datetime}, 
+            granularity = {self.granularity})
+            """
+
+    @property
+    def start_datetime(self):
+        return self._start_datetime
+
+    @start_datetime.setter
+    def start_datetime(self, value: str):
+        """Set start_datetime and validate it.
+
+        Args:
+            value (str): Start date in ISO format (YYYY-MM-DD).
+        """
+        if value is not None:
+            try:
+                datetime.fromisoformat(value)
+            except ValueError:
+                raise ValueError("Dates must be in ISO format (YYYY-MM-DD)")
+        self._start_datetime = value
+
+    @property
+    def end_datetime(self):
+        return self._end_datetime
+
+    @end_datetime.setter
+    def end_datetime(self, value: str):
+        """Set end_datetime and validate it.
+
+        Args:
+            value (str): End date in ISO format (YYYY-MM-DD).
+        """
+        if value is not None:
+            try:
+                datetime.fromisoformat(value)
+            except ValueError:
+                raise ValueError("Dates must be in ISO format (YYYY-MM-DD)")
+        self._end_datetime = value
+
+    @property
+    def granularity(self):
+        if isinstance(self._granularity, Granularity):
+            return self._granularity.value
+        return self._granularity
+
+    @granularity.setter
+    def granularity(self, value: Granularity):
+        """Set granularity and validate it.
+
+        Args:
+            value (str): Granularity in "5min", "H", "D".
+        """
+        if value is not None:
+            try:
+                Granularity(value)
+            except ValueError:
+                raise ValueError("Granularity must be 5min, H or D")
+        self._granularity = value
+
+    @property
+    def dimensions(self):
+        return {d.name: d for d in self._dimensions}
+
+    @property
+    def metrics(self):
+        return {m.name: m for m in self._metrics}
+    
+    @property
+    def trends(self):
+        return {m.name: {t.name: t for t in m._trends} for m in self._metrics}
+
+    def _validate_metrics(self) -> None:
+        """Validate metrics format and logic.
+
+        Raises:
+            ValueError: If metrics are invalid
+        """
+        if not self.metrics:
+            raise ValueError("metrics must be set")
+
+    def _validate_dimensions(self) -> None:
+        """Validate dimensions format and logic.
+
+        Raises:
+            ValueError: If dimensions are invalid
+        """
+        if not self.dimensions:
+            raise ValueError("dimensions must be set")
+
+        for d in self._dimensions:
+            if not isinstance(d.function, Generator):
+                raise ValueError(
+                    f"{d.name} dimension function must be a generator object"
+                )
+
+    def _validate_dates(self) -> None:
+        """Validate start_datetime and end_datetime format and logic.
+
+        Raises:
+            ValueError: If dates are invalid or start_datetime is after end_datetime
+        """
+        if not self.start_datetime:
+            raise ValueError("start_datetime must be set")
+
+        if not self.end_datetime:
+            raise ValueError("end_datetime must be set")
+
+        if (self.start_datetime is None) != (self.end_datetime is None):
+            raise ValueError(
+                "Both start_datetime and end_datetime must be either set or None"
+            )
+
+        start = datetime.fromisoformat(self.start_datetime)
+        end = datetime.fromisoformat(self.end_datetime)
+
+        if start > end:
+            raise ValueError("start_datetime cannot be after end_datetime")
+
+    def add_dimension(self, name: str, function) -> None:
+        """
+        Add a new dimension to the collection.
+
+        A dimension represents an additional attribute or aspect of the dataset. Each dimension is
+        identified by a unique name and associated with a function that generates its values.
+
+        Args:
+            name (str): The unique name of the dimension.
+            function (int | str | Generator): A callable (e.g., generator function) that produces values for the dimension.
+
+        Raises:
+            ValueError: If a dimension with the same name already exists in the collection.
+
+        Example:
+            >>> def sample_generator():
+            ...     while True:
+            ...         yield "sample_value"
+            ...
+            >>> my_object.add_dimension(name="category", function=sample_generator())
+        """
+        dimension = Dimensions(name=name, function=function)
+        # Raise error if self._dimensions already contains a dimension with the same name
+        if dimension in self._dimensions:
+            raise ValueError(f"Dimension with name {name} already exists")
+        self._dimensions.append(dimension)
+
+    def update_dimension(self, name: str, function) -> None:
+        """
+        Update an existing dimension in the DataGen instance.
+
+        Allows updating the function associated with a dimension. The dimension is identified by its name.
+
+        Args:
+            name (str): The unique name of the dimension to update.
+            function (int | str | Generator): int or string or callable (e.g., generator function) that produces values for the dimension.
+                If None, the function will remain unchanged.
+
+        Raises:
+            ValueError: If the dimension with the specified name does not exist.
+            ValueError: If the provided function is not a callable object.
+
+        Example:
+            ```python
+            # Updating an existing dimension
+            def new_generator():
+                while True:
+                    yield "new_value"
+
+            data_gen.update_dimension(name="category", function=new_generator())
+            ```
+        """
+        if name not in self.dimensions:
+            raise ValueError(f"Dimension with name '{name}' does not exist.")
+
+        dimension = self.dimensions[name]
+
+        if function is not None:
+            if (
+                not isinstance(function, Generator)
+                and not isinstance(function, int)
+                and not isinstance(function, str)
+                and not isinstance(function, float)
+            ):
+                raise ValueError(
+                    "Provided function must be callable or int or float or string."
+                )
+            dimension.function = function
+
+    def add_metric(
+        self,
+        name: str,
+        trends: Set[Trends]
+    ) -> None:
+        """
+        Add a metric to the DataGen instance.
+
+        This method allows you to add a new metric with specified characteristics to the DataGen instance.
+        The `function_type` determines the type of data generation (e.g., sine wave, constant value, etc.).
+        For sine or cosine metrics, additional parameters (`frequency_in_hour`, `offset_in_minutes`, and `scale`)
+        must be provided. For constant metrics, only `scale` is required.
+
+        Args:
+            name (str): The unique name of the metric.
+            function_type (str): The type of function used for data generation.
+                Must be one of ["sine", "cosine", "constant", "generator"].
+            frequency_in_hour (Optional[float]): The frequency of oscillation in hours.
+                Required for "sine" and "cosine".
+            offset_in_minutes (Optional[float]): The phase offset in minutes.
+                Required for "sine" and "cosine".
+            scale (Optional[float]): The amplitude of the wave or the constant value.
+                Required for all function types.
+
+        Raises:
+            ValueError: If a metric with the same name already exists.
+            ValueError: If required parameters for the specified `function_type` are missing.
+
+        Example:
+            ```python
+            # Adding a sine metric
+            data_gen.add_metric(
+                name="sine_metric",
+                function_type="sine",
+                frequency_in_hour=1.0,
+                offset_in_minutes=15.0,
+                scale=10.0
+            )
+
+            # Adding a constant metric
+            data_gen.add_metric(
+                name="constant_metric",
+                function_type="constant",
+                scale=5.0
+            )
+            ```
+        """
+        metric = Metrics(
+            name=name,
+            trends=trends
+        )
+        # Raise error if self._metrics already contains a metric with the same name
+        for m in self._metrics:
+            if name == m.name:
+                raise ValueError(f"Metric with name '{name}' already exists")
+        self._metrics.append(metric)
+
+    def update_metric(
+        self,
+        name: str,
+        function_value: Optional[Generator] = None,
+        frequency_in_hour: Optional[float] = None,
+        offset_in_minutes: Optional[float] = None,
+        scale: Optional[float] = None,
+    ) -> None:
+        """
+        Update an existing metric in the DataGen instance.
+
+        Allows updating the characteristics of a metric. The metric is identified by its name.
+
+        Args:
+            name (str): The unique name of the metric to update.
+            function_value (Optional[Generator]): A new generator function for the metric.
+                Required if `function_type` is "generator".
+            frequency_in_hour (Optional[float]): The new frequency of oscillation in hours.
+                Required if `function_type` is "sine" or "cosine".
+            offset_in_minutes (Optional[float]): The new phase offset in minutes.
+                Required if `function_type` is "sine" or "cosine".
+            scale (Optional[float]): The new amplitude or constant value. If None, the scale remains unchanged.
+
+        Raises:
+            ValueError: If the metric with the specified name does not exist.
+            ValueError: If required parameters for the specified `function_type` are missing.
+
+        Example:
+            ```python
+            # Updating an existing metric
+            data_gen.update_metric(
+                name="sine_metric",
+                frequency_in_hour=2.0,
+                scale=15.0
+            )
+            ```
+        """
+        if name not in self.metrics:
+            raise ValueError(f"Metric with name '{name}' does not exist.")
+
+        metric = self.metrics[name]
+
+
+        if metric._function_type == "generator" and function_value is not None:
+            metric._function_value = function_value
+        elif metric._function_type in {"sine", "cosine"}:
+            if frequency_in_hour is None or offset_in_minutes is None or scale is None:
+                raise ValueError(
+                    "frequency_in_hour, offset_in_minutes, and scale are required for sine or cosine."
+                )
+            metric._frequency_in_hour = frequency_in_hour
+            metric._offset_in_minutes = offset_in_minutes
+            metric._scale = scale
+        elif metric._function_type == "constant":
+            if function_value is None:
+                raise ValueError("function_value is required for constant.")
+            metric._function_value = function_value
+
+    def generate_data(self) -> pd.DataFrame:
+        """Generate a sample DataFrame with unique IDs and values.
+
+        Args:
+            rows: Number of rows to generate. Must be positive.
+
+        Returns:
+            pd.DataFrame: Generated data with 'id' and 'value' columns
+
+        Raises:
+            ValueError: If rows is less than or equal to 0
+            TypeError: If rows cannot be converted to int
+        """
+        # Validate dates
+        self._validate_dates()
+        self._validate_dimensions()
+        self._validate_metrics()
+
+        self._timestamps = pd.date_range(
+            start=self.start_datetime,
+            end=self.end_datetime,
+            freq=self.granularity,
+        )
+
+        # create an empty dataframe with timestamps as index
+        self.metric_data = pd.DataFrame(index=self._timestamps)
+
+
+        # Generate metric data 
+        for _, metric in self.metrics.items():
+            # recursively concant the dataframe to self.data
+            self.metric_data = pd.concat([self.metric_data, metric.generate(self._timestamps)], axis=1)
+
+
+
+        # Generate dimension data directly using a dictionary comprehension
+        self.dimension_data = pd.DataFrame(
+            {
+                column_name: [
+                    next(dimension.function) if not isinstance(dimension.function, (int, str)) else dimension.function
+                    for _ in range(len(self._timestamps))
+                ]
+                for column_name, dimension in self.dimensions.items()
+            },
+            index=self._timestamps,
+    )
+
+        self.data = pd.concat([self.dimension_data, self.metric_data], axis=1)
+

ts_data_generator-0.0.1a1/src/ts_data_generator/schema/models.py

@@ -0,0 +1,172 @@
+from pydantic import BaseModel
+from abc import ABC, abstractmethod
+from typing import Any, Callable, TypeVar, Generator, Literal, Optional, Union, Set
+from enum import Enum
+from ..utils.functions import auto_generate_name
+from ..utils.trends import Trends
+import pandas as pd
+import numpy as np
+
+T = TypeVar("T")
+
+
+class Granularity(Enum):
+    FIVE_MIN = "5min"
+    HOURLY = "H"
+    DAILY = "D"
+
+
+class Metrics(ABC):
+    def __init__(
+        self,
+        name: str = "default",
+        trends: Set[Trends] = []
+    ):
+        """
+        Initialize a Metrics object.
+
+        Args:
+            name (str): Name of the metric.
+            function_type (Literal): Type of function to generate data (e.g., "sine", "cosine", "constant", "generator").
+            function_value (Optional[Generator]): A generator function for this metric; required if function_type is "generator".
+            frequency_in_hour (Optional[str]): Frequency of trend to oscillate in hours; required if function_type in [sine, cosine].
+            offset_in_minutes (Optional[str]): Phase offset of trend in minutes; required if function_type in [sine, cosine].
+            scale (Optional[float]): Amplitude of the wave; required if function_type in [sine, cosine].
+        """
+        self._name = (
+            auto_generate_name(category="metric") if name == "default" else name
+        )
+        self._trends = trends
+        # self._function_type = function_type
+
+        # # Validate required arguments for sine and cosine
+        # if function_type in {"sine", "cosine"}:
+        #     if frequency_in_hour is None or offset_in_minutes is None or scale is None:
+        #         raise ValueError(
+        #             "frequency_in_hour, offset_in_minutes, and scale are required for sine or cosine"
+        #         )
+        #     self._frequency_in_hour = frequency_in_hour
+        #     self._offset_in_minutes = offset_in_minutes
+        #     self._scale = scale
+        #     self._function_value = None
+
+        # elif function_type == "generator":
+        #     if function_value is None:
+        #         raise ValueError("function_value is required for generator")
+        #     self._function_value = function_value
+        #     self._frequency_in_hour = None
+        #     self._offset_in_minutes = None
+        #     self._scale = None
+
+        # elif function_type == "constant":
+        #     if function_value is None:
+        #         raise ValueError("scale is required for constant")
+        #     if not isinstance(function_value, (int, float)):
+        #         raise ValueError("function_value must be an integer or float")
+        #     self._function_value = function_value
+
+        #     self._frequency_in_hour = None
+        #     self._offset_in_minutes = None
+        #     self._scale = None
+    @property
+    def name(self) -> str:
+        """Get the name of the metric."""
+        return self._name
+    
+    @property
+    def trends(self) -> Set[Trends]:
+        """Get the trends of the metric."""
+        return self._trends
+
+    def generate(self, timestamps) -> pd.DataFrame:
+        """Generate data for this metric.
+
+        Args:
+            timestamps: List of timestamps from pd.date_range
+        """
+
+        data = np.zeros(len(timestamps))
+
+        for t in self._trends:
+            data += t.generate(timestamps)
+
+        self._data = pd.DataFrame(data, columns=[self._name], index=timestamps)
+        return self._data
+
+
+    def __repr__(self):
+        # drop few keys from the dictionary
+        json_data = self.to_json()
+
+        return str(json_data)
+
+    # add a function to represent the metric in json format
+    def to_json(self):
+        return {
+            "name": self._name,
+            "trends": [t._name for t in self._trends],
+        }
+
+
+class Dimensions(ABC):
+    def __init__(self, name: str, function: Union[int, str, float, Generator]):
+        """Initialize a dimension with a name and value generation function.
+
+        Args:
+            name: Name of the dimension
+            function: Function that generates values for this dimension
+        """
+        self._name = name
+        self._function = function
+
+    @property
+    def name(self) -> str:
+        """Get the name of the dimension."""
+        return self._name
+
+    @property
+    def function(self) -> Union[int, str, float, Generator]:
+        """Get the value generation function."""
+        return self._function
+
+    @function.setter
+    def function(self, value: Union[int, str, float, Generator]) -> None:
+        """Set the value generation function.
+
+        Args:
+            value: Function that generates values for this dimension. Should be a generator object
+        """
+        # validate if value is a generator object
+        if (
+            not isinstance(value, int)
+            and not isinstance(value, str)
+            and not isinstance(value, float)
+            and not isinstance(value, Generator)
+        ):
+            raise ValueError(
+                "function must be a generator object or int or str or float"
+            )
+        self._function = value
+
+    def _create_generator(self, timestamps) -> Generator[T, None, None]:
+        """Create a generator that yields dimension values.
+
+        Args:
+            timestamps: List of timestamps from pd.date_range
+
+        """
+        pass
+
+    def __eq__(self, other: object) -> bool:
+        """Enable equality comparison for set operations."""
+        if not isinstance(other, Dimensions):
+            return NotImplemented
+        return self._name == other.name
+
+    def __hash__(self) -> int:
+        """Enable hashing for set operations."""
+        return hash(self._name)
+
+    # add a function to represent the dimension in json format
+    def to_json(self):
+        return {"name": self.name, "function": self.function.__repr__()}

ts_data_generator-0.0.1a1/src/ts_data_generator/utils/functions.py

@@ -0,0 +1,77 @@
+# create several out of the box generator functions to be used in the DataGen class
+
+import random
+import numpy as np
+import pandas as pd
+
+def constant(value):
+    """
+    Returns a constant value.
+
+    Args:
+        value: The constant value to return.
+
+    """
+    while True:
+        yield value
+        
+def random_choice(iterable):
+    """
+    Returns a random element from the given iterable.
+
+    Args:
+        iterable (iterable): The iterable to choose from.
+
+    """
+    while True:
+        yield random.choice(iterable)
+
+
+def random_int(start, end):
+    """
+    Returns a random integer between start and end, inclusive.
+
+    Args:
+        start (int): The starting value of the range.
+        end (int): The ending value of the range.
+
+    """
+    while True:
+        yield random.randint(start, end)
+
+
+def random_float(start, end):
+    """
+    Returns a random float between start and end, inclusive.
+
+    Args:
+        start (float): The starting value of the range.
+        end (float): The ending value of the range.
+
+    """
+    while True:
+        yield random.uniform(start, end)
+
+
+def ordered_choice(iterable):
+    """
+    Returns a random element from the given iterable in order.
+
+    Args:
+        iterable (iterable): The iterable to choose from.
+
+    """
+    while True:
+        yield random.choice(iterable)
+
+
+def auto_generate_name(category):
+    """
+    Generates a unique name for a metric or dimension.
+
+    Args:
+        category (str): The category of the name, either 'metric' or 'dimension'.
+
+    """
+    return f"{category}_{random.randint(1, 100)}"
+

ts_data_generator-0.0.1a1/src/ts_data_generator/utils/trends.py

@@ -0,0 +1,249 @@
+import numpy as np
+from abc import ABC, abstractmethod
+from typing import Any, Callable, TypeVar, Generator, Literal, Optional, Union
+import pandas as pd
+
+class Trends(ABC):
+    def __init__(
+            self,
+            name: str = "default",
+
+    ):
+        """
+        Initialize a Trends object.
+
+        Args:
+            name (str): Name of the trend.
+
+        """
+        self._name = name
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @abstractmethod
+    def generate(
+        self,
+        timestamps: pd.DatetimeIndex,
+    ) -> np.array:
+        """
+        Generate a time series trend.
+
+        Args:
+            start_datetime (Union[str, pd.Timestamp]): Start datetime of the trend.
+            end_datetime (Union[str, pd.Timestamp]): End datetime of the trend.
+
+        """
+        pass
+
+        
+class SinusoidalTrend(Trends):
+    def __init__(
+        self,
+        name: str = "default",
+        amplitude: float = 1,
+        freq: float = 1,
+        phase: float = 0,
+        noise_level: float = 0,
+    ):
+        """
+        Initialize a SinusoidalTrend object.
+
+        Args:
+            name (str): Name of the trend.
+            amplitude (float): Amplitude of the sinusoidal wave.
+            freq (float): Frequency of the sinusoidal wave in days.
+            phase (float): Phase offset of the sinusoidal wave in hours.
+            noise_level (float): Standard deviation of the noise.
+        """
+        super().__init__(name)
+        self._amplitude = amplitude
+        self._freq = freq
+        self._phase = phase
+        self._noise_level = noise_level
+
+    @property
+    def amplitude(self) -> float:
+        return self._amplitude
+    
+    @property
+    def freq(self) -> float:
+        return self._freq
+    
+    @property
+    def phase(self) -> float:
+        return self._phase
+    
+    @property
+    def noise_level(self) -> float:
+        return self._noise_level
+
+    def generate(self, timestamps: pd.DatetimeIndex) -> np.ndarray:
+        """
+        Generate a sinusoidal wave with added noise.
+
+        Args:
+            timestamps (pd.DatetimeIndex): Array of timestamps.
+
+        Returns:
+            np.ndarray: Sinusoidal wave with noise.
+        """
+        # Calculate the time in fractional days
+        time_in_days = (timestamps - timestamps[0]).total_seconds() / (24 * 3600)
+
+        # Convert phase to fractional days
+        phase_in_days = self._phase / 24.0
+
+        # Calculate the sinusoidal wave
+        base_wave = self._amplitude * np.sin(2 * np.pi * (1/self._freq) * (time_in_days + phase_in_days))
+
+        # Add noise
+        noise = np.random.normal(0, self._noise_level, len(timestamps))
+        sinusoidal_wave = base_wave + noise
+
+        return sinusoidal_wave
+    
+    
+
+class LinearTrend(Trends):
+    def __init__(
+        self,
+        name: str = "default",
+        offset: float = 0.0,
+        noise_level: float = 0.0,
+        limit: float = 2.0,
+    ):
+        """
+        Initialize a LinearTrend object.
+
+        Args:
+            name (str): Name of the trend.
+            limit (float): Upper limit of the linear trend.
+            offset (float): Intercept (b) of the linear trend.
+            noise_level (float): Standard deviation of the noise.
+        """
+        super().__init__(name)
+
+        self._offset = offset
+        self._noise_level = noise_level
+        # check if limit is within the range of 1 and 100
+        if limit < 1 or limit > 100:
+            raise ValueError("Limit must be within the range of 1 and 100")
+        self._limit = limit
+
+    @property
+    def limit(self) -> float:
+        return self._limit
+
+    @property
+    def offset(self) -> float:
+        return self._offset
+
+    @property
+    def noise_level(self) -> float:
+        return self._noise_level
+
+    def generate(self, timestamps) -> np.ndarray:
+        """
+        Generate a linear trend with optional noise.
+
+        Args:
+            timestamps (pd.DatetimeIndex): Array of timestamps.
+
+        Returns:
+            np.ndarray: Generated linear trend values.
+        """
+        # Calculate time differences in the appropriate unit
+        time_deltas = (timestamps - timestamps[0])
+
+        if timestamps.freq == "5min":  # 5-minute granularity
+            time_numeric = time_deltas.total_seconds() / 60.0  # Convert to minutes
+        elif timestamps.freq == "H":  # Hourly granularity
+            time_numeric = time_deltas.total_seconds() / 3600.0  # Convert to hours
+        elif timestamps.freq == "D":  # Daily granularity
+            time_numeric = time_deltas.days  # Use days directly
+        else:
+            raise ValueError("Unsupported granularity. Use 5T, H, or D.")
+
+        self._coefficient = np.radians(np.sin(self._limit/len(time_numeric)))
+
+        # Calculate the linear trend
+        base_trend = self._coefficient * time_numeric + self._offset
+
+        # Add noise
+        noise = np.random.normal(0, self._noise_level, len(timestamps))
+        trend_with_noise = base_trend + noise
+
+        return trend_with_noise
+
+class WeekendTrend(Trends):
+    def __init__(
+        self,
+        name: str = "default",
+        weekend_effect: float = 1.0,
+        direction: Literal["up", "down"] = "up",
+        noise_level: float = 0.0,
+        limit: float = 10.0,
+    ):
+        """
+        Initialize a WeekendTrend object.
+
+        Args:
+            name (str): Name of the trend.
+            weekend_effect (float): Magnitude of the weekend effect.
+            direction (Literal["up", "down"]): Direction of the weekend effect.
+            noise_level (float): Standard deviation of the noise.
+            limit (float): Maximum value for the weekend effect.
+        """
+        super().__init__(name)
+        self._weekend_effect = weekend_effect
+        self._direction = direction
+        self._noise_level = noise_level
+        self._limit = limit
+
+    @property
+    def weekend_effect(self) -> float:
+        return self._weekend_effect
+
+    @property
+    def direction(self) -> str:
+        return self._direction
+
+    @property
+    def noise_level(self) -> float:
+        return self._noise_level
+
+    @property
+    def limit(self) -> float:
+        return self._limit
+
+    def generate(self, timestamps: pd.DatetimeIndex) -> np.ndarray:
+        """
+        Generate a weekend-specific trend.
+
+        Args:
+            timestamps (pd.DatetimeIndex): Array of timestamps.
+
+        Returns:
+            np.ndarray: Trend values with weekend effect.
+        """
+        # Initialize the trend with zeros
+        trend = np.zeros(len(timestamps))
+
+        # Determine if each timestamp falls on a weekend (Saturday or Sunday)
+        is_weekend = timestamps.weekday >= 5
+
+        # Apply the weekend effect
+        weekend_adjustment = self._weekend_effect if self._direction == "up" else -self._weekend_effect
+        trend[is_weekend] = weekend_adjustment
+
+
+        # Clip the trend to the specified limit
+        trend = np.clip(trend, -self._limit, self._limit)
+
+        # Add noise
+        noise = np.random.normal(0, self._noise_level, len(timestamps))
+        trend += noise
+
+        return trend

ts_data_generator-0.0.1a1/src/ts_data_generator/utils.py

@@ -0,0 +1,16 @@
+"""
+Utility functions for data generation
+"""
+import pandas as pd
+
+def some_function(data: pd.DataFrame) -> pd.DataFrame:
+    """
+    Example utility function
+    
+    Args:
+        data: Input DataFrame
+        
+    Returns:
+        pd.DataFrame: Processed DataFrame
+    """
+    return data.copy()