tscli-darts 0.1.0__tar.gz

tscli_darts-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: tscli-darts
+Version: 0.1.0
+Summary: A DARTS-first CLI for time series analysis, preprocessing, and forecasting
+Author: Senhores do Tempo
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Senhores-do-Tempo/tscli
+Project-URL: Repository, https://github.com/Senhores-do-Tempo/tscli
+Project-URL: Issues, https://github.com/Senhores-do-Tempo/tscli/issues
+Keywords: time-series,forecasting,darts,cli,analytics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: darts>=0.30.0
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typer>=0.12.3
+Provides-Extra: classical
+Requires-Dist: pytorch-lightning>=2.6.0; extra == "classical"
+Provides-Extra: autoarima
+Requires-Dist: statsforecast>=2.0.0; extra == "autoarima"
+Provides-Extra: full
+Requires-Dist: pytorch-lightning>=2.6.0; extra == "full"
+Requires-Dist: statsforecast>=2.0.0; extra == "full"
+
+# tscli
+
+`tscli` is a command-line tool for time series analysis and forecasting built around [DARTS](https://unit8co.github.io/darts/).
+
+It is designed for a simple workflow:
+
+- load a CSV
+- clean common formatting issues
+- inspect and analyze the series
+- compare models on a holdout window
+- generate and export forecasts
+
+## What It Does
+
+- works directly from CSV files
+- detects and fixes common time-series formatting issues
+- supports a clean `date + target` workflow
+- benchmarks multiple models with `MAE`, `RMSE`, and `MAPE`
+- exports cleaned datasets, forecasts, benchmark tables, and plots
+- provides an interactive terminal mode
+
+## Install
+
+Local development install:
+
+```bash
+pip install -e .
+```
+
+When published to PyPI, the standard install will be:
+
+```bash
+pip install tscli-darts
+```
+
+Optional extras:
+
+- Classical DARTS models such as `theta` and `exponential-smoothing`
+
+```bash
+pip install -e .[classical]
+```
+
+- AutoARIMA support
+
+```bash
+pip install -e .[autoarima]
+```
+
+- Everything
+
+```bash
+pip install -e .[full]
+```
+
+## Typical Workflow
+
+### 1. Inspect the raw CSV
+
+Use this first to confirm the time column, target column, inferred frequency, and any preprocessing fixes.
+
+```bash
+python -m tscli inspect .\sales.csv --time-col Month --target-col Sales
+```
+
+### 2. Clean the dataset
+
+If the CSV has shorthand dates, duplicate timestamps, formatted numeric values, or other simple issues, save a normalized version.
+
+```bash
+python -m tscli clean .\sales.csv --time-col Month --target-col Sales --output .\cleaned_sales.csv
+```
+
+### 3. Analyze the time series
+
+Get quick descriptive statistics and recent observations before forecasting.
+
+```bash
+python -m tscli analyze .\cleaned_sales.csv --time-col Month --target-col Sales
+```
+
+### 4. Benchmark models
+
+Run several models against a holdout window, compare metrics, and optionally export the score table, forecast, and plot.
+
+```bash
+python -m tscli benchmark .\cleaned_sales.csv --time-col Month --target-col Sales --horizon 12 --models all --scores-output .\scores.csv --forecast-output .\best_forecast.csv --plot-output .\benchmark.png
+```
+
+### 5. Generate a forecast
+
+Forecast future periods with a chosen model and optionally export the forecast and chart.
+
+```bash
+python -m tscli forecast .\cleaned_sales.csv --time-col Month --target-col Sales --model naive-drift --horizon 12 --output .\forecast.csv --plot-output .\forecast.png
+```
+
+### 6. Use interactive mode
+
+Run the full workflow from a menu-driven terminal interface.
+
+```bash
+python -m tscli interactive .\cleaned_sales.csv --time-col Month --target-col Sales
+```
+
+## Commands
+
+- `inspect`: summarize the dataset and show preprocessing fixes
+- `clean`: normalize and save a cleaned CSV
+- `analyze`: print descriptive statistics and recent observations
+- `forecast`: generate future values from one model
+- `benchmark`: compare several models on a holdout window
+- `models`: list supported forecasting models
+- `interactive`: launch the terminal menu workflow
+
+## Forecasting Models
+
+Supported models:
+
+- `naive-last`
+- `naive-drift`
+- `naive-seasonal`
+- `moving-average`
+- `weighted-moving-average`
+- `exp-smoothing`
+- `seasonal-average`
+- `seasonal-median`
+- `linear-trend`
+- `quadratic-trend`
+- `arima`
+- `sarima`
+- `theta`
+- `exponential-smoothing`
+- `auto-arima`
+
+## Example Dataset
+
+The bundled `examples/sales.csv` shows a shorthand monthly sales format like:
+
+```csv
+Month,Sales
+1-01,266.0
+1-02,145.9
+1-03,183.1
+```
+
+`tscli` will detect and normalize that `Month` column into proper first-of-month datetimes.
+
+## Notes
+
+- The CSV should include a target column and optionally a time column.
+- If no time column is provided, `tscli` builds a synthetic integer index.
+- If DARTS cannot infer a frequency automatically, forecasting still uses the ordered observations.
+- Some classical DARTS models depend on optional libraries; when unavailable, `forecast` explains the missing requirement and `benchmark` skips the model.
+- `arima` and `sarima` remain DARTS-first models, with fallback behavior only when the DARTS classical path is unavailable.
+
+## Packaging
+
+To build distributable artifacts locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+This will generate source and wheel distributions in `dist/`.

tscli_darts-0.1.0/README.md

@@ -0,0 +1,166 @@
+# tscli
+
+`tscli` is a command-line tool for time series analysis and forecasting built around [DARTS](https://unit8co.github.io/darts/).
+
+It is designed for a simple workflow:
+
+- load a CSV
+- clean common formatting issues
+- inspect and analyze the series
+- compare models on a holdout window
+- generate and export forecasts
+
+## What It Does
+
+- works directly from CSV files
+- detects and fixes common time-series formatting issues
+- supports a clean `date + target` workflow
+- benchmarks multiple models with `MAE`, `RMSE`, and `MAPE`
+- exports cleaned datasets, forecasts, benchmark tables, and plots
+- provides an interactive terminal mode
+
+## Install
+
+Local development install:
+
+```bash
+pip install -e .
+```
+
+When published to PyPI, the standard install will be:
+
+```bash
+pip install tscli-darts
+```
+
+Optional extras:
+
+- Classical DARTS models such as `theta` and `exponential-smoothing`
+
+```bash
+pip install -e .[classical]
+```
+
+- AutoARIMA support
+
+```bash
+pip install -e .[autoarima]
+```
+
+- Everything
+
+```bash
+pip install -e .[full]
+```
+
+## Typical Workflow
+
+### 1. Inspect the raw CSV
+
+Use this first to confirm the time column, target column, inferred frequency, and any preprocessing fixes.
+
+```bash
+python -m tscli inspect .\sales.csv --time-col Month --target-col Sales
+```
+
+### 2. Clean the dataset
+
+If the CSV has shorthand dates, duplicate timestamps, formatted numeric values, or other simple issues, save a normalized version.
+
+```bash
+python -m tscli clean .\sales.csv --time-col Month --target-col Sales --output .\cleaned_sales.csv
+```
+
+### 3. Analyze the time series
+
+Get quick descriptive statistics and recent observations before forecasting.
+
+```bash
+python -m tscli analyze .\cleaned_sales.csv --time-col Month --target-col Sales
+```
+
+### 4. Benchmark models
+
+Run several models against a holdout window, compare metrics, and optionally export the score table, forecast, and plot.
+
+```bash
+python -m tscli benchmark .\cleaned_sales.csv --time-col Month --target-col Sales --horizon 12 --models all --scores-output .\scores.csv --forecast-output .\best_forecast.csv --plot-output .\benchmark.png
+```
+
+### 5. Generate a forecast
+
+Forecast future periods with a chosen model and optionally export the forecast and chart.
+
+```bash
+python -m tscli forecast .\cleaned_sales.csv --time-col Month --target-col Sales --model naive-drift --horizon 12 --output .\forecast.csv --plot-output .\forecast.png
+```
+
+### 6. Use interactive mode
+
+Run the full workflow from a menu-driven terminal interface.
+
+```bash
+python -m tscli interactive .\cleaned_sales.csv --time-col Month --target-col Sales
+```
+
+## Commands
+
+- `inspect`: summarize the dataset and show preprocessing fixes
+- `clean`: normalize and save a cleaned CSV
+- `analyze`: print descriptive statistics and recent observations
+- `forecast`: generate future values from one model
+- `benchmark`: compare several models on a holdout window
+- `models`: list supported forecasting models
+- `interactive`: launch the terminal menu workflow
+
+## Forecasting Models
+
+Supported models:
+
+- `naive-last`
+- `naive-drift`
+- `naive-seasonal`
+- `moving-average`
+- `weighted-moving-average`
+- `exp-smoothing`
+- `seasonal-average`
+- `seasonal-median`
+- `linear-trend`
+- `quadratic-trend`
+- `arima`
+- `sarima`
+- `theta`
+- `exponential-smoothing`
+- `auto-arima`
+
+## Example Dataset
+
+The bundled `examples/sales.csv` shows a shorthand monthly sales format like:
+
+```csv
+Month,Sales
+1-01,266.0
+1-02,145.9
+1-03,183.1
+```
+
+`tscli` will detect and normalize that `Month` column into proper first-of-month datetimes.
+
+## Notes
+
+- The CSV should include a target column and optionally a time column.
+- If no time column is provided, `tscli` builds a synthetic integer index.
+- If DARTS cannot infer a frequency automatically, forecasting still uses the ordered observations.
+- Some classical DARTS models depend on optional libraries; when unavailable, `forecast` explains the missing requirement and `benchmark` skips the model.
+- `arima` and `sarima` remain DARTS-first models, with fallback behavior only when the DARTS classical path is unavailable.
+
+## Packaging
+
+To build distributable artifacts locally:
+
+```bash
+python -m pip install build
+python -m build
+```
+
+This will generate source and wheel distributions in `dist/`.

tscli_darts-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tscli-darts"
+version = "0.1.0"
+description = "A DARTS-first CLI for time series analysis, preprocessing, and forecasting"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+  { name = "Senhores do Tempo" }
+]
+keywords = [
+  "time-series",
+  "forecasting",
+  "darts",
+  "cli",
+  "analytics",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "darts>=0.30.0",
+  "matplotlib>=3.9.0",
+  "numpy>=1.26.0",
+  "pandas>=2.2.0",
+  "rich>=13.7.0",
+  "tqdm>=4.66.0",
+  "typer>=0.12.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/Senhores-do-Tempo/tscli"
+Repository = "https://github.com/Senhores-do-Tempo/tscli"
+Issues = "https://github.com/Senhores-do-Tempo/tscli/issues"
+
+[project.optional-dependencies]
+classical = [
+  "pytorch-lightning>=2.6.0",
+]
+autoarima = [
+  "statsforecast>=2.0.0",
+]
+full = [
+  "pytorch-lightning>=2.6.0",
+  "statsforecast>=2.0.0",
+]
+
+[project.scripts]
+tscli = "tscli.main:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

tscli_darts-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tscli_darts-0.1.0/src/tscli/__init__.py

@@ -0,0 +1,5 @@
+"""tscli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

tscli_darts-0.1.0/src/tscli/__main__.py

@@ -0,0 +1,5 @@
+from tscli.main import main
+
+
+if __name__ == "__main__":
+    main()

tscli_darts-0.1.0/src/tscli/analysis.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pandas as pd
+
+from tscli.data import LoadedSeries
+
+
+@dataclass
+class SeriesSummary:
+    row_count: int
+    start: str
+    end: str
+    missing_target: int
+    mean: float
+    median: float
+    minimum: float
+    maximum: float
+    std_dev: float
+    inferred_frequency: str
+    trend_direction: str
+
+
+def summarize_series(dataset: LoadedSeries) -> SeriesSummary:
+    frame = dataset.frame.copy()
+    target = frame[dataset.target_col]
+
+    inferred_frequency = "not available"
+    if dataset.time_col != "__index__":
+        inferred = pd.infer_freq(frame[dataset.time_col])
+        if inferred:
+            inferred_frequency = inferred
+
+    clean_target = target.dropna()
+    if clean_target.empty:
+        raise ValueError("The target series is empty after dropping missing values.")
+
+    trend_delta = clean_target.iloc[-1] - clean_target.iloc[0]
+    if trend_delta > 0:
+        trend_direction = "upward"
+    elif trend_delta < 0:
+        trend_direction = "downward"
+    else:
+        trend_direction = "flat"
+
+    return SeriesSummary(
+        row_count=len(frame),
+        start=str(frame[dataset.time_col].iloc[0]),
+        end=str(frame[dataset.time_col].iloc[-1]),
+        missing_target=int(target.isna().sum()),
+        mean=float(clean_target.mean()),
+        median=float(clean_target.median()),
+        minimum=float(clean_target.min()),
+        maximum=float(clean_target.max()),
+        std_dev=float(clean_target.std(ddof=0)),
+        inferred_frequency=inferred_frequency,
+        trend_direction=trend_direction,
+    )
+
+
+def recent_observations(dataset: LoadedSeries, rows: int = 5) -> pd.DataFrame:
+    return dataset.frame[[dataset.time_col, dataset.target_col]].tail(rows).copy()

tscli_darts-0.1.0/src/tscli/data.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+import pandas as pd
+
+from tscli.preprocessing import (
+    PreprocessingReport,
+    clean_numeric_column,
+    finalize_time_series,
+    normalize_columns,
+    parse_time_column,
+)
+
+
+@dataclass
+class LoadedSeries:
+    source: Path
+    frame: pd.DataFrame
+    time_col: str
+    target_col: str
+    report: PreprocessingReport
+
+
+def load_csv(csv_path: Path, time_col: str | None, target_col: str) -> LoadedSeries:
+    frame = pd.read_csv(csv_path)
+    report = PreprocessingReport()
+    frame = normalize_columns(frame, report)
+    if target_col not in frame.columns:
+        raise ValueError(f"Target column '{target_col}' was not found in the CSV.")
+
+    resolved_time_col = time_col
+    if resolved_time_col is None:
+        for candidate in ("date", "datetime", "timestamp", "ds", "time"):
+            if candidate in frame.columns:
+                resolved_time_col = candidate
+                break
+
+    if resolved_time_col is not None:
+        if resolved_time_col not in frame.columns:
+            raise ValueError(f"Time column '{resolved_time_col}' was not found in the CSV.")
+        frame = parse_time_column(frame, resolved_time_col, report)
+        if frame[resolved_time_col].isna().any():
+            raise ValueError(
+                f"Time column '{resolved_time_col}' contains values that could not be parsed as datetime."
+            )
+    else:
+        resolved_time_col = "__index__"
+        frame[resolved_time_col] = pd.RangeIndex(start=0, stop=len(frame), step=1)
+        report.add_fix("Created a synthetic integer time index because no time column was provided.")
+
+    frame = clean_numeric_column(frame, target_col, report)
+    if frame[target_col].isna().all():
+        raise ValueError(f"Target column '{target_col}' does not contain numeric values.")
+    frame = finalize_time_series(frame, resolved_time_col, target_col, report)
+
+    return LoadedSeries(
+        source=csv_path,
+        frame=frame,
+        time_col=resolved_time_col,
+        target_col=target_col,
+        report=report,
+    )