Upload 23 files

.github/workflows/automated_ci.yaml

@@ -0,0 +1,53 @@
+name: Continuous Integration
+
+on:
+  push:
+    branches: [ "main" ]
+    paths-ignore:
+      - 'README.md'
+      - 'docs/**'
+  pull_request:
+    branches: [ "main" ]
+    paths-ignore:
+      - 'README.md'
+      - 'docs/**'
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Test on ${{ matrix.os }} with Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.8", "3.9", "3.10"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Cache pip dependencies
+        uses: actions/cache@v3
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements*.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 pytest tox tox-gh-actions
+          pip install -r requirements.txt
+          
+      - name: Test with tox
+        run: tox

.github/workflows/python-publish.yaml

@@ -0,0 +1,71 @@
+name: Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write 
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Debug Python version
+        run: 'echo "Using Python version: ${{ matrix.python-version }}"'  
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install flake8 pytest
+          pip install -r requirements.txt
+          pip install -e .
+      - name: Lint with flake8
+        run: |
+          flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+          flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Run tests
+        run: pytest -v
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: pypi 
+    steps:
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

docs/analysis.md

@@ -0,0 +1,108 @@
+# UnivariateAnalysis
+
+> **Note:** The following examples assume a time series DataFrame similar to `complaints.csv`, with columns: `date`and `complaints`.
+
+The `UnivariateAnalysis` class provides a suite of methods for exploratory and statistical analysis of univariate time series data. It helps you understand the distribution, missing values, and outliers in your time series before further modeling or forecasting.
+
+## Features
+
+- Visualizes the distribution and boxplot of the target time series.
+- Computes skewness and kurtosis with interpretation.
+- Checks for missing values and provides recommendations.
+- Detects outliers using IQR and Z-score methods.
+- Logs plots and messages to HTML reports.
+
+## Class: `UnivariateAnalysis`
+
+### Initialization
+
+```python
+UnivariateAnalysis(df: pd.DataFrame, target_col: str, index_col: str = "date", output_filepath: str = "output_filepath")
+```
+
+- **df**: The time series DataFrame (indexed by the time column).
+- **target_col**: The column name of the univariate time series to analyze.
+- **index_col**: The name of the time index column (default: "date").
+- **output_filepath**: Path prefix for saving HTML reports and plots.
+
+> **Note:** Your DataFrame should have a time-based index (e.g., "date", "timestamp").
+
+### Methods
+
+#### `plot_distribution()`
+
+Plots the histogram and boxplot of the target time series column and logs the plot to the HTML report.
+
+**Standalone Example:**
+```python
+from dynamicts.analysis import UnivariateAnalysis
+
+analysis = UnivariateAnalysis(df, target_col="complaints", index_col="date", output_filepath="report")
+fig = analysis.plot_distribution()
+fig.show()
+```
+
+#### `check_distribution_stats()`
+
+Computes skewness and kurtosis for the target column, interprets the results, and logs the summary to the HTML report.
+
+**Standalone Example:**
+```python
+from dynamicts.analysis import UnivariateAnalysis
+
+analysis = UnivariateAnalysis(df, target_col="complaints", index_col="date", output_filepath="report")
+stats = analysis.check_distribution_stats()
+print(stats["full_message"])
+```
+
+#### `check_missing_values()`
+
+Checks for missing values in the target column, reports the count and percentage, and logs recommendations to the HTML report.
+
+**Standalone Example:**
+```python
+from dynamicts.analysis import UnivariateAnalysis
+
+analysis = UnivariateAnalysis(df, target_col="complaints", index_col="date", output_filepath="report")
+missing = analysis.check_missing_values()
+print(missing["message"])
+```
+
+#### `detect_outliers(method="both", plot=True)`
+
+Detects outliers in the target column using IQR, Z-score, or both. Optionally plots and logs the results.
+
+- **method**: "iqr", "zscore", or "both" (default: "both").
+- **plot**: Whether to plot the outliers (default: True).
+
+**Standalone Example:**
+```python
+from dynamicts.analysis import UnivariateAnalysis
+
+analysis = UnivariateAnalysis(df, target_col="complaints", index_col="date", output_filepath="report")
+outliers = analysis.detect_outliers(method="both", plot=True)
+print(f"Outliers detected: {outliers['outliers_detected']}")
+```
+
+#### `run_univariate_analysis(df, output_filepath, target_col, index_col="date")` (static method)
+
+Runs the full univariate analysis pipeline: distribution plot, stats, missing values, and outlier detection. Displays results in a notebook environment.
+
+**Standalone Example:**
+```python
+from dynamicts.analysis import UnivariateAnalysis
+
+results = UnivariateAnalysis.run_univariate_analysis(
+    df=df,
+    output_filepath="report",
+    target_col="complaints",
+    index_col="date"
+)
+```
+
+### Notes
+
+- All plots and messages are logged to HTML reports using the provided `output_filepath`.
+- The DataFrame should be indexed by the time column for proper time series analysis.
+
+---

docs/data_loader.md

@@ -0,0 +1,95 @@
+# DataLoader
+
+> **Note:** We are using `complaints.csv` as an example here, with the following columns: `date`, `complaints`. The `date` column is used as the time index and `complaints` as the target variable.
+
+The `DataLoader` class provides a unified interface for loading and managing time series data from CSV files in your Python projects. It is designed as the first step in your time series analysis workflow, ensuring your time series data is loaded, validated, and ready for further analysis.
+
+## Features
+
+- Loads time series data from CSV files into pandas DataFrames.
+- Standardizes column names to lowercase.
+- Checks if the time series index is regular (uniform intervals).
+- Saves metadata (columns, dtypes, shape, index name) to a JSON file.
+
+## Class: `DataLoader`
+
+### Initialization
+
+```python
+DataLoader(filepath: str, index_col: Optional[Union[str, int]] = None, parse_dates: Union[bool, list] = True)
+```
+
+- **filepath**: Path to the CSV file containing your time series data.
+- **index_col**: Name or position of the column to use as the time index (e.g., a timestamp or date column).
+- **parse_dates**: Whether to parse dates in the index column.
+
+> **Note:** Your CSV must contain a column representing the time axis (e.g., "date"). Set `index_col` to this column's name.
+
+### Methods
+
+#### `load() -> pd.DataFrame`
+
+Loads the time series data from the specified CSV file, standardizes column names, and sets the index name to lowercase.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+df = loader.load()
+print(df.head())
+```
+
+#### `is_regular() -> bool`
+
+Checks if the time series index is regular (i.e., intervals between timestamps are uniform). Returns `True` if regular, `False` otherwise.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+loader.load()  # Must load data first
+is_reg = loader.is_regular()
+print("Is regular:", is_reg)
+```
+
+#### `save_metadata() -> None`
+
+Saves metadata (columns, dtypes, shape, index name) of the loaded DataFrame to a JSON file in the `metadata/` directory.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+loader.load()  # Must load data first
+loader.save_metadata()
+print("Metadata saved.")
+```
+
+#### `run_pipeline() -> Optional[pd.DataFrame]`
+
+Runs the time series data loading pipeline:
+- Loads the data.
+- Checks for regularity.
+- Saves metadata if data is regular.
+- Returns the loaded DataFrame.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+data = loader.run_pipeline()
+if data is not None:
+    print("Time series data loaded successfully!")
+```
+
+### Notes
+
+- The loader logs all actions and errors to a log file in the `logs/` directory.
+- If the time index is not regular, a warning is logged and the data is still returned for inspection.
+- Metadata is saved only if the time series data is regular.
+
+---

docs/lag_correlation.md

@@ -0,0 +1,84 @@
+# Correlation
+
+> **Note:** We are using `complaints.csv` as an example here, with the following columns: `date`, `complaints`. The `date` column is used as the time index and `complaints` as the target variable.
+
+The `Correlation` class provides methods for analyzing and visualizing autocorrelation (ACF) and partial autocorrelation (PACF) in univariate time series data. These tools are essential for understanding lag relationships and dependencies in time series analysis.
+ 
+## Features
+
+- Plots autocorrelation (ACF) for a given time series and number of lags.
+- Plots partial autocorrelation (PACF) for a given time series and number of lags.
+- Supports both instance-based and standalone usage.
+- Optionally logs plots to HTML reports.
+
+## Class: `Correlation`
+
+### Initialization
+
+```python
+Correlation(df: pd.DataFrame = None, target_col: str = None, lags: int = 20, output_filepath: str = None)
+```
+
+- **df**: The time series DataFrame (indexed by the time column).
+- **target_col**: The column name of the univariate time series to analyze.
+- **lags**: Number of lags to use for correlation plots (default: 20).
+- **output_filepath**: Path prefix for saving HTML reports and plots.
+
+> **Note:** Your DataFrame should have a time-based index (e.g., "date", "timestamp").
+
+### Methods
+
+#### `acf_plot(data: pd.Series = None, lags: int = None, save: bool = True, output_filepath: str = None)`
+
+Plots the autocorrelation function (ACF) for the specified time series and number of lags.
+
+- **data**: Optional. A pandas Series to plot. If not provided, uses the instance's DataFrame and target column.
+- **lags**: Optional. Number of lags to plot. Defaults to the instance's `lags`.
+- **save**: Optional. Whether to save the plot to an HTML report.
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.lag_correlation import Correlation
+
+# Instance-based usage
+corr = Correlation(df, target_col="complaints", lags=30, output_filepath="report")
+fig = corr.acf_plot()
+fig.show()
+
+# Standalone usage
+corr = Correlation()
+fig = corr.acf_plot(data=df["complaints"], lags=30, output_filepath="report")
+fig.show()
+```
+
+#### `pacf_plot(data: pd.Series = None, lags: int = None, save: bool = True, output_filepath: str = None)`
+
+Plots the partial autocorrelation function (PACF) for the specified time series and number of lags.
+
+- **data**: Optional. A pandas Series to plot. If not provided, uses the instance's DataFrame and target column.
+- **lags**: Optional. Number of lags to plot. Defaults to the instance's `lags`.
+- **save**: Optional. Whether to save the plot to an HTML report.
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.lag_correlation import Correlation
+
+# Instance-based usage
+corr = Correlation(df, target_col="complaints", lags=30, output_filepath="report")
+fig = corr.pacf_plot()
+fig.show()
+
+# Standalone usage
+corr = Correlation()
+fig = corr.pacf_plot(data=df["complaints"], lags=30, output_filepath="report")
+fig.show()
+```
+
+### Notes
+
+- The DataFrame should be indexed by the time column for proper time series analysis.
+- Plots can be logged to HTML reports if `save=True` and `output_filepath` is provided.
+
+---

docs/stationarity.md

@@ -0,0 +1,82 @@
+# Stationarity
+
+> **Note:** We are using `complaints.csv` as an example here, with the following columns: `date`, `complaints`. The `date` column is used as the time index and `complaints` as the target variable.
+
+The `Stationarity` class provides methods to test and visualize the stationarity of **univariate time series data**. Stationarity is a key assumption in many time series models, and these tools help you assess and transform your data accordingly.
+
+## Features
+
+- Performs the Augmented Dickey-Fuller (ADF) test for stationarity.
+- Plots rolling mean and standard deviation for visual inspection.
+- Supports both instance-based and standalone usage.
+- Optionally logs results and plots to HTML reports.
+
+## Class: `Stationarity`
+
+### Initialization
+
+```python
+Stationarity(df: pd.DataFrame = None, target_col: str = None, window: int = 12, output_filepath: str = None)
+```
+
+- **df**: The time series DataFrame (indexed by the time column).
+- **target_col**: The column name of the univariate time series to analyze.
+- **window**: Window size for rolling statistics (default: 12).
+- **output_filepath**: Path prefix for saving HTML reports and plots.
+
+> **Note:** Your DataFrame should have a time-based index (e.g., "date", "timestamp").
+
+### Methods
+
+#### `adf_test(data: pd.Series = None, verbose: bool = True, save: bool = True, output_filepath: str = None)`
+
+Performs the Augmented Dickey-Fuller test for stationarity on the specified time series.
+
+- **data**: Optional. A pandas Series to test. If not provided, uses the instance's DataFrame and target column.
+- **verbose**: Whether to print and log the test summary (default: True).
+- **save**: Whether to save the results to an HTML report (default: True).
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.stationarity import Stationarity
+
+# Instance-based usage
+stat = Stationarity(df, target_col="complaints", window=12, output_filepath="report")
+adf_result = stat.adf_test()
+
+# Standalone usage
+stat = Stationarity()
+adf_result = stat.adf_test(data=df["complaints"], verbose=True, output_filepath="report")
+```
+
+#### `plot_rolling_stats(data: pd.Series = None, window: int = None, save: bool = True, output_filepath: str = None)`
+
+Plots the rolling mean and standard deviation for the specified time series and window size.
+
+- **data**: Optional. A pandas Series to plot. If not provided, uses the instance's DataFrame and target column.
+- **window**: Optional. Window size for rolling statistics. Defaults to the instance's `window`.
+- **save**: Whether to save the plot to an HTML report (default: True).
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.stationarity import Stationarity
+
+# Instance-based usage
+stat = Stationarity(df, target_col="complaints", window=12, output_filepath="report")
+fig = stat.plot_rolling_stats()
+fig.show()
+
+# Standalone usage
+stat = Stationarity()
+fig = stat.plot_rolling_stats(data=df["complaints"], window=12, output_filepath="report")
+fig.show()
+```
+
+### Notes
+
+- The DataFrame should be indexed by the time column for proper time series analysis.
+- Results and plots can be logged to HTML reports if `save=True` and `output_filepath` is provided.
+
+---

docs/volatility_check.md

@@ -0,0 +1,88 @@
+# VolatilityChecker
+
+> **Note:** We are using `complaints.csv` as an example here, with the following columns: `date`, `complaints`. The `date` column is used as the time index and `complaints` as the target variable.
+
+The `VolatilityChecker` class provides methods for analyzing and visualizing volatility in univariate time series data using ARCH and GARCH models. These tools help you assess the presence and dynamics of volatility clustering in your time series.
+
+## Features
+
+- Computes and plots volatility using ARCH(1) and GARCH(1,1) models.
+- Supports both instance-based and standalone usage.
+- Optionally logs plots and summary statistics to HTML reports.
+
+## Class: `VolatilityChecker`
+
+### Initialization
+
+```python
+VolatilityChecker(df: pd.DataFrame = None, target_col: str = None, output_filepath: str = "Output")
+```
+
+- **df**: The time series DataFrame (indexed by the time column).
+- **target_col**: The column name of the univariate time series to analyze.
+- **output_filepath**: Path prefix for saving HTML reports and plots.
+
+> **Note:** Your DataFrame should have a time-based index (e.g., "date", "timestamp").
+
+### Methods
+
+#### `arch_volatility(data: pd.Series = None, save: bool = True, output_filepath: str = None)`
+
+Computes and plots volatility using an ARCH(1) model.
+
+- **data**: Optional. A pandas Series to analyze. If not provided, uses the instance's DataFrame and target column.
+- **save**: Whether to save the plot and summary to an HTML report (default: True).
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+from dynamicts.volatility_check import VolatilityChecker
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+df = loader.run_pipeline()
+
+# Instance-based usage
+vc = VolatilityChecker(df, target_col="complaints", output_filepath="report")
+fig = vc.arch_volatility()
+fig.show()
+
+# Standalone usage
+vc2 = VolatilityChecker()
+fig2 = vc2.arch_volatility(data=df["complaints"], output_filepath="report")
+fig2.show()
+```
+
+#### `garch_volatility(data: pd.Series = None, save: bool = True, output_filepath: str = None)`
+
+Computes and plots volatility using a GARCH(1,1) model.
+
+- **data**: Optional. A pandas Series to analyze. If not provided, uses the instance's DataFrame and target column.
+- **save**: Whether to save the plot and summary to an HTML report (default: True).
+- **output_filepath**: Optional. Path for saving the report.
+
+**Standalone Example:**
+```python
+from dynamicts.data_loader import DataLoader
+from dynamicts.volatility_check import VolatilityChecker
+
+loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+df = loader.run_pipeline()
+
+# Instance-based usage
+vc = VolatilityChecker(df, target_col="complaints", output_filepath="report")
+fig = vc.garch_volatility()
+fig.show()
+
+# Standalone usage
+vc2 = VolatilityChecker()
+fig2 = vc2.garch_volatility(data=df["complaints"], output_filepath="report")
+fig2.show()
+```
+
+### Notes
+
+- The DataFrame should be indexed by the time column for proper time series analysis.
+- Plots and summary statistics can be logged to HTML reports if `save=True` and `output_filepath` is provided.
+
+---

dynamicts/analysis.py

@@ -0,0 +1,217 @@
+import os
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from scipy import stats
+from scipy.stats import skew, kurtosis
+from IPython.display import display, Markdown
+from datetime import datetime
+
+from dynamicts.report_generator import log_message_to_html_report, log_plot_to_html_report
+
+class UnivariateAnalysis:
+    def __init__(self, df: pd.DataFrame, target_col: str, index_col: str = "date"):
+        self.df = df
+        self.target_col = target_col
+
+        column_map = {col.lower(): col for col in self.df.columns}
+        target_col_lower = self.target_col.lower()
+
+        if target_col_lower not in column_map:
+            raise ValueError(f"Target column '{self.target_col}' not found in dataset columns: {self.df.columns.tolist()}")
+
+        self.target_col = column_map[target_col_lower]
+        self.date_col = self.df.index.name
+
+        # Generate report path ONCE per instance
+        root_dir = os.path.abspath(os.curdir)
+        report_root = os.path.join(root_dir, "reports")
+        os.makedirs(report_root, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        report_name = f"analysis_report_{timestamp}.html"
+        self.report_path = os.path.join(report_root, report_name)
+
+    def plot_distribution(self) -> plt.Figure:
+        y = self.df[self.target_col].dropna()
+        fig, axes = plt.subplots(1, 2, figsize=(14, 5))
+
+        sns.histplot(y, kde=True, ax=axes[0], bins=30, color='cornflowerblue')
+        axes[0].set_title(f"Distribution of {self.target_col}")
+        axes[0].set_xlabel(self.target_col)
+        axes[0].set_ylabel("Frequency")
+
+        sns.boxplot(x=y, ax=axes[1], color="lightcoral")
+        axes[1].set_title(f'Boxplot of {self.target_col}')
+        axes[1].set_xlabel(self.target_col)
+
+        plt.tight_layout()
+        log_plot_to_html_report(fig, title=f"Distribution of {self.target_col}", report_path=self.report_path)
+        plt.close(fig)
+        return fig
+
+    def check_distribution_stats(self):
+        y = self.df[self.target_col].dropna()
+        skewness_val = skew(y)
+        kurtosis_val = kurtosis(y)
+
+        if abs(skewness_val) < 0.5:
+            skew_msg = "approximately_symmetric"
+        elif skewness_val > 0:
+            skew_msg = "right_skewed"
+        else:
+            skew_msg = "left_skewed"
+
+        if kurtosis_val < 0:
+            kurt_msg = "light_tailed (platykurtic)"
+        elif kurtosis_val > 0:
+            kurt_msg = "heavy_tailed (leptokurtic)"
+        else:
+            kurt_msg = "normal_tailed (mesokurtic)"
+
+        full_msg = (
+            f"Skewness of '{self.target_col}': {skewness_val:.4f}\n"
+            f"Kurtosis of '{self.target_col}': {kurtosis_val:.4f}\n"
+            f"→ Distribution is {skew_msg} and {kurt_msg}."
+        )
+
+        log_message_to_html_report(message=full_msg, title=f"Distribution Stats: {self.target_col}", report_path=self.report_path)
+
+        return {
+            "skewness": skewness_val,
+            "kurtosis": kurtosis_val,
+            "skewness_interpretation": skew_msg,
+            "kurtosis_interpretation": kurt_msg,
+            "full_message": full_msg
+        }
+
+    def check_missing_values(self):
+        series = self.df[self.target_col]
+        total_points = len(series)
+        missing_count = series.isna().sum()
+        missing_percentage = (missing_count / total_points) * 100
+
+        msg = f"""
+        Total Observations: {total_points}
+        Missing values in '{self.target_col}': {missing_count} ({missing_percentage:.2f}%)
+        """
+
+        if missing_count > 0:
+            msg += "<b>Recommendation:</b> Consider forward/backward fill or interpolation if your model does not support missing values."
+
+        log_message_to_html_report(message=msg, title=f"Missing Value Analysis for '{self.target_col}'", report_path=self.report_path)
+        return {
+            "total_observations": total_points,
+            "missing_count": missing_count,
+            "missing_percentage": missing_percentage,
+            "message": msg.strip()
+        }
+
+    def detect_outliers(self, method="both", plot=True):
+        y = self.df[self.target_col].dropna()
+
+        Q1 = y.quantile(0.25)
+        Q3 = y.quantile(0.75)
+        IQR = Q3 - Q1
+        iqr_outliers = y[(y < Q1 - 1.5 * IQR) | (y > Q3 + 1.5 * IQR)]
+
+        z_scores = np.abs(stats.zscore(y))
+        z_outliers = y[z_scores > 3]
+
+        if method == "iqr":
+            combined_outliers = iqr_outliers
+            method_label = "IQR"
+        elif method == "zscore":
+            combined_outliers = z_outliers
+            method_label = "Z-Score"
+        else:
+            combined_outliers = y[(y.index.isin(iqr_outliers.index)) | (y.index.isin(z_outliers.index))]
+            method_label = "IQR + Z-Score"
+
+        outlier_count = len(combined_outliers)
+        total = len(y)
+        percentage = (outlier_count / total) * 100
+
+        msg = f"""
+        Outlier Detection using: {method_label}
+        Total Observations: {total}
+        Outliers Detected: {outlier_count} ({percentage:.2f}%)
+
+        <b>Recommendation:</b> Investigate these points manually before deciding to remove or treat them.
+        """
+        log_message_to_html_report(message=msg, title=f"Outlier Detection ({method_label})", report_path=self.report_path)
+
+        fig = None
+        if plot:
+            fig, ax = plt.subplots(figsize=(12, 5))
+            sns.lineplot(x=y.index, y=y, label="Original Data", ax=ax)
+            sns.scatterplot(x=combined_outliers.index, y=combined_outliers, color='red', s=40, label="Outliers", ax=ax)
+            ax.set_title(f"Outliers Detected using {method_label}")
+            ax.set_ylabel(self.target_col)
+            ax.set_xlabel("Date")
+            plt.xticks(rotation=45)
+            plt.tight_layout()
+            log_plot_to_html_report(fig=fig, title=f"{method_label} Outlier Detection for {self.target_col}", report_path=self.report_path)
+            plt.close(fig)
+
+        return {
+            "method": method_label,
+            "total_observations": total,
+            "outliers_detected": outlier_count,
+            "percentage_outliers": percentage,
+            "outlier_indices": combined_outliers.index.tolist(),
+            "outlier_values": combined_outliers.tolist(),
+            "fig": fig
+        }
+
+    def run_univariate_analysis(self, df: pd.DataFrame = None, target_col: str = None, index_col: str = None):
+        """
+        Run univariate analysis using instance attributes by default, or override with provided arguments.
+        """
+        df = df if df is not None else self.df
+        target_col = target_col if target_col is not None else self.target_col
+        index_col = index_col if index_col is not None else self.date_col
+
+        if df is None or target_col is None:
+            raise ValueError("DataFrame and target_col must be provided either as arguments or instance attributes.")
+
+        try:
+            print(f"\nRunning Univariate Time Series Analysis on '{target_col}' ")
+            analysis = UnivariateAnalysis(df=df, target_col=target_col, index_col=index_col)
+            results = {}
+
+            fig_dist = analysis.plot_distribution()
+            display(fig_dist)
+            results["distribution_plot"] = fig_dist
+
+            dist_stats = analysis.check_distribution_stats()
+            display(Markdown(f"### Distribution Stats\n{dist_stats['full_message']}"))
+            results["distribution_stats"] = dist_stats
+
+            missing = analysis.check_missing_values()
+            display(Markdown(f"### Missing Value Info\n{missing['message']}"))
+            results["missing_values"] = missing
+
+            outliers = analysis.detect_outliers(method="both", plot=True)
+            display(Markdown(f"### Outliers Detected: {outliers['outliers_detected']} ({outliers['percentage_outliers']:.2f}%)"))
+            display(outliers["fig"])
+            results["outliers"] = outliers
+
+            display(Markdown("Univariate Time Series Analysis Completed."))
+            return results
+
+        except Exception as e:
+            print(f"Error in univariate analysis: {e}")
+            return None
+
+if __name__ == "__main__":
+    from dynamicts.data_loader import DataLoader
+
+    loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+    df = pd.read_csv("data/complaints.csv")
+    analysis = UnivariateAnalysis(
+        df=df,
+        target_col="complaints",
+        index_col="date"
+    )
+    results = analysis.run_univariate_analysis()

dynamicts/data_loader.py

@@ -0,0 +1,136 @@
+"""
+data_loader.py
+Module to load time series data and provide a shared interface for other modules.
+"""
+import logging
+from typing import Optional, Union
+import pandas as pd
+import json
+import os
+
+
+class DataLoader:
+    """
+    DataLoader is a class for loading and managing time series data from a CSV file.
+    Attributes:
+        filepath (str): Path to the CSV file containing the data.
+        index_col (str or int, optional): Column to use as the row labels of the DataFrame.
+        parse_dates (bool or list, optional): Whether to parse dates in the index column.
+        data (pd.DataFrame or None): Loaded data after calling `load()`.
+    Methods:
+        load():
+            Loads the data from the specified CSV file, saves metadata, and standardizes column names to lowercase.
+            Returns the loaded DataFrame.
+        is_regular():
+            Checks if the time series index is regular (i.e., intervals between timestamps are uniform).
+            Returns True if regular, False otherwise.
+        save_metadata():
+            Saves metadata (columns, dtypes, shape, index name) of the loaded DataFrame to a JSON file
+            with the same name as the CSV file, suffixed with '_meta.json'.
+        run_pipeline():
+            Runs the data loading pipeline: loads data, checks regularity, and renames the first column to 'y' if regular.
+            Returns the processed DataFrame if regular, otherwise None.
+    """
+    
+    def __init__(self, filepath: str, index_col: Optional[Union[str, int]] = None, parse_dates: Union[bool, list] = True):
+        self.filepath = filepath
+        self.index_col = index_col
+        self.parse_dates = parse_dates
+        self.data = None
+
+        # Data paths file name
+        self.base_name = os.path.splitext(os.path.basename(self.filepath))[0]
+
+        base_dir = os.getcwd()
+        log_dir = os.path.join(base_dir, "logs")
+        os.makedirs(log_dir, exist_ok=True)
+        log_filename = os.path.splitext(os.path.basename(__file__))[0] + ".log"
+        log_path = os.path.join(log_dir, log_filename)
+        
+        # Set up logging
+        if not logging.getLogger().hasHandlers():
+            logging.basicConfig(
+                level=logging.INFO,
+                format='%(asctime)s - %(levelname)s - %(message)s',
+                handlers=[
+                    logging.FileHandler(log_path),
+                    logging.StreamHandler()
+                ]
+                )
+
+    def load(self) -> pd.DataFrame:
+        """Load the data from the specified CSV file."""
+        try:
+            self.data = pd.read_csv(self.filepath, index_col=self.index_col, parse_dates=self.parse_dates)
+            self.data.columns = self.data.columns.str.lower()
+            self.data.index.name = self.data.index.name.lower() if self.data.index.name else None
+            # self.save_metadata()
+            return self.data
+        except Exception as e:
+            logging.error(f"Error loading data from {self.filepath}: {e}")
+            raise ValueError(f"Failed to load data from {self.filepath}. Please check the file format and path.") from e
+    
+    def is_regular(self) -> bool:
+        """Check if the time series data is regular."""
+        if self.data.index.isnull().sum() > 0:
+            logging.warning("Data contains null values in the index, Cannot proceed with this data further.")
+            return False
+
+        # Ensure index is a DatetimeIndex
+        if not isinstance(self.data.index, pd.DatetimeIndex):
+            logging.warning("Index is not a DatetimeIndex. Cannot check regularity.")
+            return False
+
+        # Calculate differences between consecutive timestamps
+        diffs = self.data.index.to_series().diff().dropna()
+        if diffs.nunique() == 1:
+            logging.info(f"Data is regular. Index differences are uniform: {diffs.iloc[0]}")
+            return True
+        else:
+            logging.warning("Data is not regular. Index differences are not uniform.")
+            logging.warning(f"Unique differences found: {diffs.unique()}" )
+            return False
+
+
+    def save_metadata(self) -> None:
+        """Save metadata of the DataFrame to a JSON file."""
+
+        # base_name = os.path.splitext(os.path.basename(self.filepath))[0]
+        base_dir = os.getcwd()
+        metadata_dir = os.path.join(base_dir, "metadata")
+        os.makedirs(metadata_dir, exist_ok=True)
+        meta_filename = os.path.splitext(os.path.basename(self.filepath))[0] + "_meta.json"
+        meta_path = os.path.join(metadata_dir, meta_filename)
+
+        metadata = {
+            "columns": list(self.data.columns),
+            "dtypes": {col: str(dtype) for col, dtype in self.data.dtypes.items()},
+            "shape": self.data.shape,
+            "index_name": self.data.index.name,
+        }
+        try:
+            with open(meta_path, "w") as f:
+                json.dump(metadata, f, indent=4)
+        except Exception as e:
+            logging.error(f"Error saving metadata to {meta_path}: {e}")
+            raise ValueError(f"Failed to save metadata to {meta_path}.") from e
+        
+    def run_pipeline(self) -> Optional[pd.DataFrame]:
+        """Run the data loading pipeline."""
+        logging.info("loading data...")
+        self.load()
+        if not self.is_regular():
+            logging.warning("Pipeline completed. Data is loaded but may not be regular.")
+            return self.data   # Return the data anyway for inspection.        
+        logging.info("Data loaded is regular. Further processing may be needed.")
+        self.save_metadata()
+        return self.data
+
+
+# Usage
+if __name__ == "__main__":
+    loader = DataLoader(filepath="sample_data/date_count.csv", index_col="Date")
+    result = loader.run_pipeline()
+    if result is not None:
+        logging.info("Data loaded successfully.")
+ 

dynamicts/dynamic_analysis.py

@@ -0,0 +1,47 @@
+from dynamicts.analysis import UnivariateAnalysis
+from dynamicts.data_loader import DataLoader
+from dynamicts.lag_correlation import Correlation
+
+
+class DynamicTSA:
+    def __init__(self, filepath, target_col, index_col=None, parse_dates = True, lags = 20):
+        self.filepath  = filepath
+        self.target_col = target_col
+        self.index_col = index_col
+        self.parse_dates = parse_dates
+        self.lags = lags
+        self.data = None
+
+    def run(self):
+        # Loading data
+        loader = DataLoader(filepath=self.filepath, index_col=self.index_col, parse_dates=self.parse_dates)
+        df = loader.run_pipeline()
+
+        if df is None:
+            print("Data loading failed or data is not regular.")
+            return
+        
+        # Univariate analysis
+        ua = UnivariateAnalysis(df, target_col=self.target_col, index_col=self.index_col, output_filepath=self.filepath )
+        ua.plot_distribution()
+        ua.check_distribution_stats()
+        ua.check_missing_values()
+        ua.detect_outliers()
+
+        # lag correlation (ACF/PACF)
+        corr = Correlation(df=df, target_col=self.target_col, lags=self.lags, output_filepath=self.filepath)
+        corr = Correlation(df=df, target_col=self.target_col, lags=self.lags, output_filepath=self.filepath)
+        corr.acf_plot()
+        corr.pacf_plot()
+
+        print("Dynamic time series analysis pipeline completed.")
+
+# Example usage:
+if __name__ == "__main__":
+    tsa = DynamicTSA(
+        filepath="data/bitcoin_price.csv",
+        target_col="Close",
+        index_col="Date",
+        lags=30
+    )
+    tsa.run()

dynamicts/lag_correlation.py

@@ -0,0 +1,168 @@
+"""
+lag_correlation.py
+
+This module provides the Correlation class for analyzing and visualizing autocorrelation (ACF)
+and partial autocorrelation (PACF) in time series data. It supports logging results and plots to HTML reports.
+"""
+
+import pandas as pd
+from datetime import datetime
+import os
+from statsmodels.graphics.tsaplots import plot_acf, plot_pacf
+import matplotlib.pyplot as plt
+from dynamicts.report_generator import log_plot_to_html_report, log_message_to_html_report
+from dynamicts.data_loader import DataLoader
+
+class Correlation:
+    """
+    A class for computing and visualizing autocorrelation and partial autocorrelation
+    for time series data.
+    """
+    def __init__(self, df: pd.DataFrame = None, target_col: str = None, lags: int = 20):
+        """
+        Initialize the Correlation class.
+
+        Args:
+            df (pd.DataFrame, optional): DataFrame containing the time series data.
+            target_col (str, optional): Name of the column to analyze.
+            lags (int, optional): Number of lags to use for correlation plots.
+
+        Raises:
+            TypeError: If df is not a pandas DataFrame.
+            ValueError: If target_col is not provided or not found in df.
+        """
+        self.df = df
+        self.target_col = target_col
+        self.lags = lags
+        self.date_col = None  # will be set if df is valid
+
+        # If df is provided, validate it
+        if self.df is not None:
+            if not isinstance(self.df, pd.DataFrame):
+                raise TypeError("Expected a pandas DataFrame for `df`.")
+
+            # Save date_col if index name is present
+            self.date_col = self.df.index.name or "index"
+
+            # If target_col is missing
+            if not self.target_col:
+                raise ValueError("`target_col` must be provided when passing a DataFrame.")
+
+            # Validate column name case-insensitively
+            column_map = {col.lower(): col for col in self.df.columns}
+            target_col_lower = self.target_col.lower()
+
+            if target_col_lower not in column_map:
+                raise ValueError(
+                    f"Target column '{self.target_col}' not found in DataFrame. "
+                    f"Available columns: {self.df.columns.tolist()}"
+                )
+
+            self.target_col = column_map[target_col_lower]
+        # Generate report path ONCE per instance
+        root_dir = os.path.abspath(os.curdir)
+        report_root = os.path.join(root_dir, "reports")
+        os.makedirs(report_root, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        report_name = f"correlation_report_{timestamp}.html"
+        self.report_path = os.path.join(report_root, report_name)
+        
+
+    def acf_plot(self, data: pd.Series = None, lags: int = None, save: bool = True):
+        """
+        Plot the autocorrelation function (ACF) for the given time series.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+            lags (int, optional): Number of lags to plot. Defaults to instance lags.
+            save (bool, optional): Whether to save the plot to an HTML report.
+
+        Returns:
+            matplotlib.figure.Figure: The generated ACF plot.
+
+        Raises:
+            ValueError: If no data is provided.
+        """
+        series = data if data is not None else self.df[self.target_col]
+
+        if series is None:
+            raise ValueError("No data provided for ACF plot. Pass `data` or instantiate with DataFrame and target_col.")
+
+        lags = lags if lags is not None else self.lags
+        title = f"Auto correlation Plot, lags = {lags}"
+
+        fig, ax = plt.subplots(figsize = (14, 8))
+        plot_acf(series, lags=lags, ax=ax)
+        ax.set_title(title)
+
+        if save:
+            log_plot_to_html_report(fig=fig, title=title, report_path=self.report_path)
+        
+        return fig
+    
+
+    def pacf_plot(self, data: pd.Series = None, lags: int = None, save: bool = True):
+        """
+        Plot the partial autocorrelation function (PACF) for the given time series.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+            lags (int, optional): Number of lags to plot. Defaults to instance lags.
+            save (bool, optional): Whether to save the plot to an HTML report.
+
+        Returns:
+            matplotlib.figure.Figure: The generated PACF plot.
+
+        Raises:
+            ValueError: If no data is provided.
+        """
+        series = data if data is not None else self.df[self.target_col]
+
+        if series is None:
+            raise ValueError("No data provided for PACF plot. Pass `data` or instantiate with DataFrame and target_col.")
+        lags = lags if lags is not None else self.lags
+        title = f"Partial Autocorrelation Plot (lags={lags})"
+
+        fig, ax = plt.subplots(figsize = (12, 6))
+        plot_pacf(series, lags=lags, ax=ax)    
+        ax.set_title(title)
+
+        if save:
+            log_plot_to_html_report(fig=fig, title=title, report_path=self.report_path)
+
+        return fig
+    def run_lag_correlation(self, data: pd.Series = None, lags: int = None):
+        """
+        Run both ACF and PACF plots and log them to the report.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+            lags (int, optional): Number of lags to plot. Defaults to instance lags.
+
+        Returns:
+            dict: Dictionary with ACF and PACF figures.
+        """
+        acf_fig = self.acf_plot(data=data, lags=lags, save=True)
+        pacf_fig = self.pacf_plot(data=data, lags=lags, save=True)
+        return {
+            "acf_fig": acf_fig,
+            "pacf_fig": pacf_fig
+        }
+    
+if __name__ == "__main__":
+    # Load the data
+    loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+    df = loader.run_pipeline()
+
+    if df is not None:
+        # ✅ Option 1: Instance-based usage (uses internal config)
+        print("Using instance-based plotting...")
+        corr_instance = Correlation(df=df, target_col="complaints", lags=30)
+        corr_instance.acf_plot()
+        corr_instance.pacf_plot()
+
+        # ✅ Option 2: Standalone-style usage (no target_col needed, just a Series)
+        print("Using standalone-style plotting...")
+        corr_flex = Correlation()  # No args needed
+        # corr_flex.acf_plot(data=df["revenue"], lags=30)
+        # corr_flex.pacf_plot(data=df["revenue"], lags

dynamicts/report_generator.py

@@ -0,0 +1,68 @@
+import base64
+import io
+from datetime import datetime
+import os
+
+def log_plot_to_html_report(fig, title, report_path):
+    """
+    Logs a matplotlib figure to an HTML report file, saving in the root 'reports' directory.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        The matplotlib figure to be saved.
+    title : str
+        The title for the plot section in the report.
+    mod_name : str, optional
+        Module name to use in the report file name.
+    """
+    # Ensure the reports directory exists
+    os.makedirs(os.path.dirname(report_path), exist_ok=True)
+
+    # Save figure to a BytesIO buffer
+    buf = io.BytesIO()
+    fig.savefig(buf, format='png', bbox_inches='tight')
+    buf.seek(0)
+
+    # Convert image to base64 string
+    encoded = base64.b64encode(buf.read()).decode('utf-8')
+    buf.close()
+
+    # HTML content
+    html_block = f"""
+    <h2>{title}</h2>
+    <img src="data:image/png;base64,{encoded}" style="max-width:100%; height:auto;">
+    <p><em>Generated on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</em></p>
+    <hr>
+    """
+
+    # Write or append to HTML file
+    if not os.path.exists(report_path):
+        with open(report_path, "w") as f:
+            f.write("<html><head><title>Time Series Analysis Report</title></head><body>")
+            f.write(html_block)
+    else:
+        with open(report_path, "a") as f:
+            f.write(html_block)
+
+def log_message_to_html_report(message, title, report_path):
+    """
+    Logs a text message to an HTML report file at the given report_path.
+    """
+    # Ensure the reports directory exists
+    os.makedirs(os.path.dirname(report_path), exist_ok=True)
+
+    html_block = f"""
+    <h2>{title}</h2>
+    <p style="font-family: monospace; white-space: pre-wrap;">{message}</p>
+    <p><em>Logged on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</em></p>
+    <hr>
+    """
+
+    if not os.path.exists(report_path):
+        with open(report_path, "w", encoding="utf-8") as f:
+            f.write("<html><head><title>Time Series Analysis Report</title></head><body>")
+            f.write(html_block)
+    else:
+        with open(report_path, "a", encoding="utf-8") as f:
+            f.write(html_block)

dynamicts/report_generator_sh.py

@@ -0,0 +1,152 @@
+import base64
+import io
+from datetime import datetime
+import os
+
+
+class Reports:
+    def __init__(self, fig=None, title: str = None, message: str = None, data_filepath: str = None, report_name: str = "report.html", mod_name: str = "default_mod"):
+        self.fig = fig
+        self.title = title
+        self.message = message
+        self.mod_name = mod_name
+        # Default data_filepath to current file's directory if not provided
+        if data_filepath is None:
+            self.data_filepath = os.path.dirname(__file__)
+        else:
+            self.data_filepath = data_filepath
+
+        # Set up report directory and path
+        base_name = os.path.splitext(os.path.basename(self.data_filepath))[0]
+        root_dir = os.path.abspath(os.curdir)
+        self.report_root = os.path.join(root_dir, "reports")
+        os.makedirs(self.report_root, exist_ok=True)
+        self.report_path = os.path.join(self.report_root, self.mod_name+report_name)
+
+        # Check if the report file exists
+        self.report_exists = os.path.exists(self.report_path)
+
+        # Optionally, create the file if it doesn't exist
+        if not self.report_exists:
+            with open(self.report_path, "w", encoding="utf-8") as f:
+                f.write("")  # Create an empty file
+
+    def log_plot_to_md_report(self, report_name: str = "report.md") -> None:
+        """
+        Logs a matplotlib figure to a Markdown report file, saving in a directory based on the data file name.
+        """
+        # Check if the report file exists, create if not
+        if not os.path.exists(self.report_path):
+            with open(self.report_path, "w", encoding="utf-8") as f:
+                f.write("")
+            self.report_exists = True
+
+        # Save plot to memory
+        buf = io.BytesIO()
+        self.fig.savefig(buf, format="png", bbox_inches="tight")
+        buf.seek(0)
+
+        # Convert to base 64
+        encoded = base64.b64encode(buf.read()).decode("utf-8")
+        buf.close()
+
+        # MD Embed
+        markdown_block = f"""
+    ## {self.title}
+    ![{self.title}](data:image/png;base64,{encoded})
+    <sub>Generated on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</sub>
+    ---
+    """
+
+        # Append to report file
+        with open(self.report_path, "a") as f:
+            f.write(markdown_block)
+
+    def log_plot_to_html_report(self, report_name: str = "report.html") -> None:
+        """
+        Logs a matplotlib figure to an HTML report file, saving in a directory based on the data file name.
+        """
+        # Check if the report file exists, create if not
+        if not os.path.exists(self.report_path):
+            with open(self.report_path, "w") as f:
+                f.write("<html><head><title>Time Series Analysis Report</title></head><body>")
+            self.report_exists = True
+
+        # Save figure to a BytesIO buffer
+        buf = io.BytesIO()
+        self.fig.savefig(buf, format='png', bbox_inches='tight')
+        buf.seek(0)
+
+        # Convert image to base64 string
+        encoded = base64.b64encode(buf.read()).decode('utf-8')
+        buf.close()
+
+        # HTML content
+        html_block = f"""
+    <h2>{self.title}</h2>
+    <img src="data:image/png;base64,{encoded}" style="max-width:100%; height:auto;">
+    <p><em>Generated on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</em></p>
+    <hr>
+    """
+
+        # Write or append to HTML file
+        with open(self.report_path, "a") as f:
+            f.write(html_block)
+
+    def log_message_to_html_report(self, report_name: str = "report.html") -> None:
+        """
+        Logs a text message to an HTML report file, saving in a directory based on the data file name.
+        """
+        # Check if the report file exists, create if not
+        if not os.path.exists(self.report_path):
+            with open(self.report_path, "w", encoding="utf-8") as f:
+                f.write("<html><head><title>Time Series Analysis Report</title></head><body>")
+            self.report_exists = True
+
+        html_block = f"""
+    <h2>{self.title}</h2>
+    <p style="font-family: monospace; white-space: pre-wrap;">{self.message}</p>
+    <p><em>Logged on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}</em></p>
+    <hr>
+    """
+
+        with open(self.report_path, "a", encoding="utf-8") as f:
+            f.write(html_block)
+
+    @staticmethod
+    def append_all_reports(combined_report: str = "combined_report.html") -> None:
+        """
+        Appends the contents of all HTML reports in the reports directory into one combined report.
+        Only runs if the reports directory exists and is not empty.
+        """
+        report_dir = os.path.dirname(os.path.dirname(__file__)) + "/reports"
+        combined_path = os.path.join(report_dir, combined_report)
+
+        # Check if reports directory exists and is not empty
+        if not os.path.isdir(report_dir):
+            print(f"Reports directory '{report_dir}' does not exist.")
+            return
+        report_files = [
+            f for f in os.listdir(report_dir)
+            if f.endswith(".html") and f != combined_report
+        ]
+        if not report_files:
+            print(f"No HTML reports found in '{report_dir}'.")
+            return
+
+        contents = []
+        for report_file in report_files:
+            path = os.path.join(report_dir, report_file)
+            if os.path.exists(path):
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    # Remove opening and closing HTML/body tags to avoid nesting
+                    content = content.replace("<html>", "").replace("</html>", "")
+                    content = content.replace("<body>", "").replace("</body>", "")
+                    contents.append(f"<h1>{report_file}</h1>\n" + content)
+
+        # Write combined content to new file
+        with open(combined_path, "w", encoding="utf-8") as f:
+            f.write("<html><head><title>Combined Report</title></head><body>\n")
+            f.write("<hr>\n".join(contents))
+            f.write("\n</body></html>")

dynamicts/stationarity.py

@@ -0,0 +1,281 @@
+"""
+stationarity.py
+---------------
+Provides tools for stationarity diagnostics and visualization for time series data,
+including rolling statistics, Augmented Dickey-Fuller (ADF) and KPSS tests, and seasonal decomposition.
+"""
+
+import os
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from IPython.display import display, Markdown
+from datetime import datetime
+from statsmodels.tsa.stattools import adfuller, kpss
+from statsmodels.tsa.seasonal import seasonal_decompose
+from dynamicts.report_generator import log_plot_to_html_report, log_message_to_html_report
+
+class Stationaritychecker:
+    def __init__(self, df: pd.DataFrame, target_col: str, window: int = 7) -> None:
+        """
+        Initialize the Stationaritychecker with a DataFrame, target column, and window size.
+
+        Args:
+            df (pd.DataFrame): The DataFrame containing the time series data.
+            target_col (str): The column to analyze for stationarity.
+            window (int): Window size for rolling calculations (default: 7).
+        """
+        # Clean the target column: remove % if present and convert to float
+        series = df[target_col].replace('%', '', regex=True)
+        series = pd.to_numeric(series, errors='coerce')
+        self.series = series
+        self.window = window
+
+        # Generate report path ONCE per instance
+        root_dir = os.path.abspath(os.curdir)
+        report_root = os.path.join(root_dir, "reports")
+        os.makedirs(report_root, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        report_name = f"stationarity_report_{timestamp}.html"
+        self.report_path = os.path.join(report_root, report_name)
+
+    def rolling_statistics(self, window=None) -> dict:
+        """
+        Compute and plot rolling mean, standard deviation, and covariance for a time series.
+
+        Args:
+            window (int): Window size for rolling calculations (default: self.window).
+
+        Returns:
+            dict: Dictionary containing rolling statistics, the figure, and a summary message.
+        """
+        try:
+            win = window if window is not None else self.window
+            roll_mean = self.series.rolling(win).mean()
+            roll_std = self.series.rolling(win).std()
+            roll_cov = self.series.rolling(win).cov(self.series.shift(1))
+
+            fig, ax = plt.subplots(figsize=(15, 6))
+            ax.plot(self.series.index, self.series, label="Original", alpha=0.5)
+            ax.plot(roll_mean.index, roll_mean, label="Rolling Mean", color='blue')
+            ax.plot(roll_std.index, roll_std, label="Rolling Std Dev", color='green')
+            ax.plot(roll_cov.index, roll_cov, label="Rolling Covariance", color='purple')
+            ax.set_title(f"Rolling Statistics (Window={win})")
+            ax.legend()
+            plt.xticks(rotation=45)
+            plt.tight_layout()
+
+            # Use .name if Series, else fallback
+            series_name = getattr(self.series, 'name', None)
+            if not series_name:
+                series_name = 'series'
+            log_plot_to_html_report(fig, title=f"Rolling Statistics of {series_name}", report_path=self.report_path)
+            plt.close(fig)
+
+            msg = f"""
+            Rolling statistics over window = {win} computed for:
+            1. Mean
+            2. Standard Deviation
+            3. Covariance (with lagged series)
+
+            <b>Tip:</b> Rolling metrics help identify trends, volatility, and local stability.
+            """
+            log_message_to_html_report(message=msg.strip(), title="Rolling Statistics Summary", report_path=self.report_path)
+
+            return {
+                "window": win,
+                "rolling_mean": roll_mean,
+                "rolling_std": roll_std,
+                "rolling_cov": roll_cov,
+                "fig": fig,
+                "message": msg.strip()
+            }
+        except Exception as e:
+            log_message_to_html_report(f"Error in rolling_statistics: {e}", title="Rolling Statistics Error", report_path=self.report_path)
+            print(f"Exception in rolling_statistics: {e}")
+            return {}
+
+    def adf_test(self, autolag='AIC'):
+        """
+        Perform Augmented Dickey-Fuller test and return results as a dictionary.
+
+        Args:
+            autolag (str): Method to use when automatically determining the lag (default: 'AIC').
+
+        Returns:
+            dict: Results of the ADF test.
+        """
+        try:
+            result = adfuller(self.series.dropna(), autolag=autolag)
+            output = {
+                'ADF Statistic': result[0],
+                'p-value': result[1],
+                'Num Lags Used': result[2],
+                'Num Observations Used': result[3],
+                'Critical Values': result[4],
+                'IC Best': result[5]
+            }
+            return output
+        except Exception as e:
+            log_message_to_html_report(f"Error in adf_test: {e}", title="ADF Test Error", report_path=self.report_path)
+            print(f"Exception in adf_test: {e}")
+            return {}
+
+    def kpss_test(self, regression='c', lags='auto'):
+        """
+        Perform KPSS test and return results as a dictionary.
+
+        Args:
+            regression (str): Type of regression for the test ('c' or 'ct').
+            lags (str or int): Number of lags to use (default: 'auto').
+
+        Returns:
+            dict: Results of the KPSS test.
+        """
+        try:
+            result = kpss(self.series.dropna(), regression=regression, lags=lags)
+            output = {
+                'KPSS Statistic': result[0],
+                'p-value': result[1],
+                'Num Lags Used': result[2],
+                'Critical Values': result[3]
+            }
+            return output
+        except Exception as e:
+            log_message_to_html_report(f"Error in kpss_test: {e}", title="KPSS Test Error", report_path=self.report_path)
+            print(f"Exception in kpss_test: {e}")
+            return {}
+
+    def print_adf_summary(self, autolag='AIC'):
+        """
+        Return a Markdown-formatted summary of the ADF test results.
+
+        Args:
+            autolag (str): Method for lag selection.
+
+        Returns:
+            str: Markdown-formatted summary.
+        """
+        try:
+            result = self.adf_test(autolag)
+            if not result:
+                return "ADF test failed. See logs for details."
+            summary_md = f"""
+**Augmented Dickey-Fuller Test Results**
+
+- **ADF Statistic:** `{result['ADF Statistic']:.4f}`
+- **p-value:** `{result['p-value']:.4g}`
+- **Num Lags Used:** `{result['Num Lags Used']}`
+- **Num Observations Used:** `{result['Num Observations Used']}`
+
+**Critical Values:**
+"""
+            for key, value in result['Critical Values'].items():
+                summary_md += f"\n- `{key}`: `{value:.4f}`"
+            summary_md += f"\n- **IC Best:** `{result['IC Best']:.4f}`"
+
+            if result["p-value"] <= 0.05:
+                summary_md += "\n\n**-->** ✅ **Reject the null hypothesis:** The time series is **stationary**."
+            else:
+                summary_md += "\n\n**-->** ⚠️ **Fail to reject the null hypothesis:** The time series is **non-stationary**."
+            log_message_to_html_report(message=summary_md.strip(), title="ADF Test Summary", report_path=self.report_path)
+            return summary_md
+        except Exception as e:
+            log_message_to_html_report(f"Error in print_adf_summary: {e}", title="ADF Summary Error", report_path=self.report_path)
+            print(f"Exception in print_adf_summary: {e}")
+            return "ADF summary failed. See logs for details."
+
+    def plot_seasonal_decompose(
+        self,
+        model: str = 'additive',
+        period: int = 12,
+        title: str = 'Seasonal Decomposition'
+    ) -> plt.Figure:
+        """
+        Plot and log the seasonal decomposition of a time series.
+
+        Args:
+            model (str): 'additive' or 'multiplicative'.
+            period (int): The period for decomposition (e.g., 12 for monthly data).
+            title (str): Plot title.
+
+        Returns:
+            plt.Figure: The matplotlib figure object.
+        """
+        try:
+            decomposition = seasonal_decompose(self.series.dropna(), model=model, period=period)
+            fig = decomposition.plot()
+            fig.set_size_inches(10, 8)
+            plt.suptitle(title)
+            plt.tight_layout()
+            log_plot_to_html_report(fig, title=f"Seasonal Decomposition", report_path=self.report_path)
+            plt.close(fig)
+            return fig
+        except Exception as e:
+            log_message_to_html_report(f"Error in plot_seasonal_decompose: {e}", title="Seasonal Decompose Error", report_path=self.report_path)
+            print(f"Exception in plot_seasonal_decompose: {e}")
+            return None
+
+    def run_stationarity_pipeline(self, window: int = 12, adf_autolag: str = 'AIC', decompose_model: str = 'additive', decompose_period: int = None):
+        """
+        Run a pipeline: rolling average visual, ADF summary, and seasonal decomposition.
+        Args:
+            window: int, window for rolling statistics.
+            adf_autolag: str, autolag parameter for ADF test.
+            decompose_model: str, 'additive' or 'multiplicative' for seasonal decomposition.
+            decompose_period: int, period for seasonal decomposition.
+        """
+        try:
+            print("="*60)
+            print("**1. Augmented Dickey-Fuller Test**".center(60))
+            print("="*60)
+            display(Markdown("### 1. Augmented Dickey-Fuller Test"))
+            display(Markdown(self.print_adf_summary(autolag=adf_autolag)))
+
+            print("\n" + "="*60)
+            print("**2. Seasonal Decomposition Visual**".center(60))
+            print("="*60)
+            display(Markdown("### 2. Seasonal Decomposition Visual"))
+            display(self.plot_seasonal_decompose(model=decompose_model, period=decompose_period))
+
+            print("\n" + "="*60)
+            print("**3. Rolling Statistics Visual**".center(60))
+            print("="*60)
+            display(Markdown("### 3. Rolling Statistics Visual"))
+            rolling_stats = self.rolling_statistics(window=window)
+            display(Markdown(rolling_stats.get('message', '')))
+            display(rolling_stats.get('fig', None))
+        except Exception as e:
+            log_message_to_html_report(f"Error in stationarity_pipeline: {e}", title="Stationarity Pipeline Error", report_path=self.report_path)
+            print(f"Exception in stationarity_pipeline: {e}")
+
+if __name__ == "__main__":
+    import pandas as pd
+
+    # Example: Load a time series from CSV
+    # Replace with your actual file and column names
+    df = pd.read_csv("data/complaints.csv", parse_dates=["date"], index_col="date")
+    # Clean the column if needed (remove % and convert to float)
+    df["complaints"] = pd.to_numeric(df["complaints"].replace('%', '', regex=True), errors='coerce')
+    series = df["complaints"]
+
+    # Create an instance of Stationaritychecker
+    checker = Stationaritychecker(series, window=12)
+
+    # Run rolling statistics
+    rolling_stats = checker.rolling_statistics()
+    print("Rolling statistics computed and logged.")
+
+    # Run ADF test and print summary
+    adf_summary = checker.print_adf_summary()
+    print(adf_summary)
+
+    # Run KPSS test
+    kpss_result = checker.kpss_test()
+    print("KPSS test result:", kpss_result)
+
+    # Plot and log seasonal decomposition
+    checker.plot_seasonal_decompose(model='additive', period=12)
+
+    # Or run the full pipeline
+    # checker.run_stationarity_pipeline(window=12, adf_autolag='AIC', decompose_model='additive', decompose_period

dynamicts/volatility_check.py

@@ -0,0 +1,195 @@
+"""
+volatility_check.py
+
+This module provides the VolatilityChecker class for analyzing and visualizing time series volatility
+using ARCH and GARCH models. It supports logging results and plots to HTML reports.
+"""
+
+import os
+from datetime import datetime
+import pandas as pd
+import matplotlib.pyplot as plt
+from arch import arch_model
+from dynamicts.report_generator import log_plot_to_html_report, log_message_to_html_report
+
+class VolatilityChecker:
+    """
+    A class for checking and visualizing volatility in time series data using ARCH and GARCH models.
+    """
+
+    def __init__(self, df: pd.DataFrame = None, target_col: str = None):
+        """
+        Initialize the VolatilityChecker.
+
+        Args:
+            df (pd.DataFrame, optional): DataFrame containing the time series data.
+            target_col (str, optional): Name of the column to analyze for volatility.
+
+        Raises:
+            TypeError: If df is not a pandas DataFrame.
+            ValueError: If target_col is not provided or not found in df.
+            RuntimeError: For any other initialization errors.
+        """
+        self.df = None
+        self.series = None
+
+        # Generate report path ONCE per instance
+        root_dir = os.path.abspath(os.curdir)
+        report_root = os.path.join(root_dir, "reports")
+        os.makedirs(report_root, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        report_name = f"volatility_report_{timestamp}.html"
+        self.report_path = os.path.join(report_root, report_name)
+
+        try:
+            if df is not None:
+                if not isinstance(df, pd.DataFrame):
+                    raise TypeError("Expected a pandas DataFrame for `df`.")
+
+                if not target_col:
+                    raise ValueError("`target_col` must be provided when passing a DataFrame.")
+
+                column_map = {col.lower(): col for col in df.columns}
+                target_col_lower = target_col.lower()
+
+                if target_col_lower not in column_map:
+                    raise ValueError(f"Column '{target_col}' not found. Available: {list(df.columns)}")
+
+                self.df = df
+                self.series = df[column_map[target_col_lower]].pct_change().dropna() * 100
+        except Exception as e:
+            raise RuntimeError(f"Initialization failed in VolatilityChecker: {str(e)}") from e
+
+    def arch_volatility(self, data: pd.Series = None, save: bool = True):
+        """
+        Compute and plot volatility using an ARCH(1) model.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+            save (bool, optional): Whether to save the plot and summary to an HTML report.
+
+        Returns:
+            matplotlib.figure.Figure: The generated volatility plot.
+
+        Raises:
+            RuntimeError: If computation fails.
+        """
+        try:
+            series = data.pct_change().dropna() * 100 if data is not None else self.series
+            if series is None:
+                raise ValueError("No time series data provided. Use `data=` or initialize the class with a DataFrame.")
+
+            model = arch_model(series, vol="ARCH", p=1)
+            res = model.fit(disp='off')
+            cond_vol = res.conditional_volatility
+
+            # Plot
+            fig, ax = plt.subplots(figsize=(14, 6))
+            ax.plot(cond_vol, label="ARCH(1) Volatility", color='orange')
+            ax.set_title("ARCH(1) Estimated Volatility")
+            ax.set_ylabel("Volatility")
+            ax.legend()
+
+            if save:
+                log_plot_to_html_report(fig, title="ARCH Volatility", report_path=self.report_path)
+
+                message = f"""ARCH(1) Volatility Report:
+                            - Mean: {cond_vol.mean():.4f}%
+                            - Max: {cond_vol.max():.4f}%
+                            - Min: {cond_vol.min():.4f}%
+                            - Std Dev: {cond_vol.std():.4f}%
+                            - Spikes (>1.5×mean): {(cond_vol > 1.5 * cond_vol.mean()).sum()}
+                            """
+                log_message_to_html_report(message, title="ARCH Volatility Summary", report_path=self.report_path)
+
+            return fig
+
+        except Exception as e:
+            raise RuntimeError(f"ARCH volatility computation failed: {str(e)}") from e
+
+    def garch_volatility(self, data: pd.Series = None, save: bool = True):
+        """
+        Compute and plot volatility using a GARCH(1,1) model.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+            save (bool, optional): Whether to save the plot and summary to an HTML report.
+
+        Returns:
+            matplotlib.figure.Figure: The generated volatility plot.
+
+        Raises:
+            RuntimeError: If computation fails.
+        """
+        try:
+            series = data.pct_change().dropna() * 100 if data is not None else self.series
+            if series is None:
+                raise ValueError("No time series data provided. Use `data=` or initialize the class with a DataFrame.")
+
+            model = arch_model(series, vol="GARCH", p=1, q=1)
+            res = model.fit(disp='off')
+            cond_vol = res.conditional_volatility
+
+            # Plot
+            fig, ax = plt.subplots(figsize=(14, 6))
+            ax.plot(cond_vol, label="GARCH(1,1) Volatility", color='purple')
+            ax.set_title("GARCH(1,1) Estimated Volatility")
+            ax.set_ylabel("Volatility")
+            ax.legend()
+
+            if save:
+                log_plot_to_html_report(fig, title="GARCH Volatility", report_path=self.report_path)
+
+                message = f"""GARCH(1,1) Volatility Report:
+                            - Mean: {cond_vol.mean():.4f}%
+                            - Max: {cond_vol.max():.4f}%
+                            - Min: {cond_vol.min():.4f}%
+                            - Std Dev: {cond_vol.std():.4f}%
+                            - Spikes (>1.5×mean): {(cond_vol > 1.5 * cond_vol.mean()).sum()}
+                            """
+                log_message_to_html_report(message, title="GARCH Volatility Summary", report_path=self.report_path)
+
+            return fig
+
+        except Exception as e:
+            raise RuntimeError(f"GARCH volatility computation failed: {str(e)}") from e
+    def run_volatility_pipeline(self, data: pd.Series = None):
+        """
+        Run both ARCH and GARCH volatility analysis and log results to the report.
+
+        Args:
+            data (pd.Series, optional): Time series data to analyze. If None, uses initialized data.
+
+        Returns:
+            dict: Dictionary with ARCH and GARCH volatility figures.
+        """
+        print("="*60)
+        print("**1. ARCH(1) Volatility Analysis**".center(60))
+        print("="*60)
+        arch_fig = self.arch_volatility(data=data, save=True)
+
+        print("\n" + "="*60)
+        print("**2. GARCH(1,1) Volatility Analysis**".center(60))
+        print("="*60)
+        garch_fig = self.garch_volatility(data=data, save=True)
+
+        return {
+            "arch_fig": arch_fig,
+            "garch_fig": garch_fig
+        }
+
+if __name__ == "__main__":
+    from dynamicts.data_loader import DataLoader
+
+    loader = DataLoader(filepath="data/complaints.csv", index_col="date")
+    df = loader.run_pipeline()
+
+    # Option 1: Use instance-based approach
+    vc = VolatilityChecker(df=df, target_col="complaints")
+    vc.arch_volatility()
+    vc.garch_volatility()
+
+    # Option 2: Use flexible function-style
+    vc2 = VolatilityChecker()
+    # vc2.arch_volatility(data=df["revenue"])
+    # vc2.garch_volatility(data=df["revenue"])

tests/integration/test_int.py

@@ -0,0 +1,3 @@
+# Dummy test cases
+def test_null():
+    assert True

tests/unit/test_unit.py

@@ -0,0 +1,117 @@
+# Import the necessary libraries
+import os
+import json
+import pytest
+import pandas as pd
+from dynamicts.data_loader import DataLoader
+from dynamicts.analysis import UnivariateAnalysis
+
+# Dummy test cases
+def test_null():
+    assert True
+    
+# Constants
+data_url = "https://raw.githubusercontent.com/Chinar-Quantum-AI-Ltd/public_datasets/main/bitcoin_price.csv"
+
+loader = DataLoader(filepath=data_url, index_col="Date")
+
+# tEST FOR DATA loader
+def test_load_success():
+    df = loader.load()
+    # check datframe loaded 
+    assert isinstance(df, pd.DataFrame)
+    # columns are lower case
+    assert all(col == col.lower() for col in df.columns)
+    # index is lower case
+    assert df.index.name == "date"
+    
+def test_load_failure():
+    url = "https://raw.githubusercontent.com/Chinar-Quantum-AI-Ltd/public_datasets/main/price.csv" # invalid url for testing
+    loader = DataLoader(
+        filepath=url, index_col="Date"
+    )
+    with pytest.raises(ValueError):
+        loader.load()
+        
+def test_is_regular():
+    # loader = DataLoader(
+    #     filepath=data_url,
+    #     index_col="Date"
+    # )
+    loader.load()
+    assert loader.is_regular() is True
+    
+def test_is_regular_false(tmp_path):
+    # Create irregular CSV
+    irregular = tmp_path / "irregular.csv"
+    # create dummy irregular data
+    dts = pd.to_datetime(["2021-01-01", "2021-01-02", "2021-01-04", "2021-01-07"]) 
+    df_irreg = pd.DataFrame({"date": dts, "y": [1,2,3,4]}).set_index("date")
+    df_irreg.to_csv(irregular)
+    loader = DataLoader(filepath=str(irregular), index_col="date")
+    loader.load()
+    assert loader.is_regular() is False
+    
+def test_save_metadata(tmp_path, monkeypatch):
+    # Monkey patch workingh dir to temp path for clean metadata
+    monkeypatch.chdir(tmp_path)
+    # loader = DataLoader(
+    #     filepath=data_url,
+    #     index_col="Date"
+    # )
+    df = loader.load()
+    # Save metadata (writes to ./metadata/<filename>_meta.json)
+    loader.save_metadata()
+
+    # Verify expected file exists
+    expected_filename = os.path.splitext(os.path.basename(data_url))[0] + "_meta.json"
+    meta_path = tmp_path / "metadata" / expected_filename
+
+    assert meta_path.exists()
+
+    # Check metadata content
+    with open(meta_path) as f:
+        meta = json.load(f)
+
+    assert meta["columns"] == list(df.columns)
+    assert meta["shape"] == list(df.shape) or tuple(df.shape)
+    assert meta["index_name"] == df.index.name
+
+# # Some Test cases for analysis.py script
+
+# # Tests for univariate analysis module
+# def test_ditribution_stats_and_missing(monkeypatch, tmp_path):
+#     analysis = UnivariateAnalysis(
+#         filepath=data_url,
+#         target_col="Close",
+#         index_col="Date"
+#         )
+#     # test distribution stats
+#     stats = analysis.check_distribution_stats()
+#     assert "skewness" in stats
+#     assert "kurtosis" in stats
+#     assert isinstance(stats["skewness"], float)
+#     assert isinstance(stats["kurtosis"], float)
+    
+# #     # test missing values
+# #     missing = analysis.check_missing_values()
+# #     assert "missing_count" in missing
+# #     assert "missing_percentage" in missing
+# #     assert isinstance(missing["missing_percentage"], float)
+    
+# def test_outlier_detection_and_rolling():
+#     analysis = UnivariateAnalysis(
+#         filepath=data_url,
+#         target_col="Close",
+#         index_col="Date"
+#         )
+#     # tests for outlier detection
+#     outliers = analysis.detect_outliers(method="both", plot=False)
+#     assert "outliers_detected" in outliers
+#     assert outliers["outliers_detected"] >= 0
+    
+#     # test for rolling stat
+#     rolling = analysis.measure_rolling_statistics(window=7)
+#     assert "rolling_mean" in rolling
+#     assert isinstance(rolling["rolling_mean"], pd.Series)
+#     assert rolling["rolling_mean"].shape == analysis.df["close"].shape