demetrapy 0.1.0__tar.gz

demetrapy-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: demetrapy
+Version: 0.1.0
+Summary: A Python CLI for seasonal adjustment with JDemetra+ core
+Project-URL: Documentation, https://github.com/SermetPekin/seasonal-pri/blob/main/USAGE.md
+Project-URL: Issues, https://github.com/SermetPekin/seasonal-pri/issues
+Project-URL: Repository, https://github.com/SermetPekin/seasonal-pri
+Keywords: seasonal-adjustment,jdemetra,x13,tramo-seats,time-series
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: JPype1<2,>=1.5
+Provides-Extra: examples
+Requires-Dist: pandas<4,>=2; extra == "examples"
+Provides-Extra: plots
+Requires-Dist: pandas<4,>=2; extra == "plots"
+Requires-Dist: matplotlib<4,>=3.8; extra == "plots"
+Provides-Extra: dashboard
+Requires-Dist: pandas<4,>=2; extra == "dashboard"
+Requires-Dist: matplotlib<4,>=3.8; extra == "dashboard"
+Requires-Dist: plotly<7,>=6; extra == "dashboard"
+Requires-Dist: streamlit<2,>=1.40; extra == "dashboard"
+
+# demetrapy
+
+[![CI](https://github.com/SermetPekin/seasonal-pri/actions/workflows/ci.yml/badge.svg)](https://github.com/SermetPekin/seasonal-pri/actions/workflows/ci.yml)
+
+A Python command-line interface for seasonal adjustment with
+[JDemetra+ core](https://github.com/jdemetra/jdemetra-core). It calls the real
+X13 and TRAMO/SEATS implementations through JPype and does not require Maven or
+a Demetra+ desktop installation.
+
+## Requirements
+
+- Python 3.9 or newer
+- Java 8 or newer
+
+## Install
+
+Windows users should follow the [Windows usage guide](WINDOWS_USAGE.md), which
+also covers proxy-restricted and fully offline JAR installation.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+The pinned `demetra-tstoolkit` 2.2.6 JAR is downloaded from Maven Central on
+the first run and cached in `~/.cache/demetrapy`. Set `DEMETRAPY_JAR` to
+use a local JAR instead.
+
+## Use
+
+Input is a regular monthly, quarterly, half-yearly, or yearly CSV series:
+
+```csv
+date,value
+2019-01-01,101.2
+2019-02-01,103.8
+```
+
+Run with defaults (`Monthly`, `RSA4`):
+
+```bash
+demetrapy input.csv --output adjusted.csv
+```
+
+The equivalent fully named form is:
+
+```bash
+demetrapy --data input.csv --config examples/config.json --output adjusted.csv
+```
+
+Or provide a JSON configuration. The full example includes TRAMO/SEATS,
+calendar effects, user regressors, outliers, interventions, and ramps:
+
+```bash
+demetrapy input.csv --config examples/config.json --output adjusted.csv
+demetrapy input.csv --config examples/full_config.json --output adjusted.csv
+```
+
+See the [usage guide](USAGE.md) for the complete input, configuration, output,
+and Python API reference, or the [Windows usage guide](WINDOWS_USAGE.md) for
+Command Prompt instructions.
+
+The supported runtime matrix and result stability policy are documented in
+[COMPATIBILITY.md](COMPATIBILITY.md).
+See [CONFIGURATION.md](CONFIGURATION.md) for processing order, compatible
+option groups, defaults, ARIMA controls, calendars, X11, SEATS, and detailed
+result semantics.
+
+The result contains the original (`y`), seasonally adjusted (`sa`), trend
+(`t`), seasonal (`s`), and irregular (`i`) series.
+
+Configuration supports X13 and TRAMO/SEATS presets, preprocessing and
+decomposition overrides, built-in and custom calendars, CSV-backed user
+variables, prespecified and automatically detected outliers, interventions,
+ramps, and fixed coefficients.
+
+The same engine is available from Python:
+
+```python
+from demetrapy import adjust
+
+result = adjust(values, frequency="Monthly", start_year=2019, spec="RSA4")
+seasonally_adjusted = result["sa"]
+```
+
+Opt into the complete JDemetra result dictionary, scalar diagnostics, and
+processing messages with `detailed=True`. Returned time series retain their
+own frequency and starting period, including forecasts and backcasts.
+Detailed results also expose the fitted ARIMA orders and whether automatic
+model selection was used through `result.arima_model`.
+See [automatic_arima_example.py](examples/automatic_arima_example.py) and
+[explicit_arima_example.py](examples/explicit_arima_example.py) for runnable
+examples with both processing engines.
+The [full TRAMO/SEATS UserDefined calendar example](examples/full_tramoseats_user_calendar_example.py)
+combines a separate calendar pool, explicit seasonal ARIMA model, all supported
+TRAMO estimation controls, outlier detection, forecasts, and SEATS options.
+The [quarterly example](examples/quarterly_example.py) demonstrates frequency
+inference and compares X13 with TRAMO/SEATS using a seasonal period of four.
+
+```python
+detailed = adjust(
+	values,
+	frequency="Monthly",
+	start_year=2019,
+	forecast_horizon=12,
+	detailed=True,
+)
+forecast = detailed.series["final.sa_f"]
+```
+
+See [examples/dataframe_user_variables_example.py](examples/dataframe_user_variables_example.py)
+for a pandas example that keeps observations and a broad user-defined calendar
+pool in separate DataFrames. `adjust_dataframe()` infers their frequency and
+domains, validates coverage, and lets each target select different calendar
+columns using the same semantics as GUI `Trading Days > UserDefined`.
+The [retail operations case study](examples/RETAIL_CASE_STUDY.md) turns that
+example into a reproducible multi-target adjustment and forecasting workflow.
+
+To run X13 and TRAMO/SEATS against the same deterministic series, compare every
+compact component, and write aligned results to `method_comparison.csv`:
+
+```bash
+python examples/compare_methods.py
+```
+
+## Plots and Dashboard
+
+Install optional visualization support:
+
+```bash
+python -m pip install -e ".[plots]"
+demetrapy --data input.csv --plot-output adjustment.png
+```
+
+For an interactive local interface with CSV uploads, multi-series controls,
+calendar mappings, Plotly charts, diagnostics, messages, and downloads:
+
+```bash
+python -m pip install -e ".[dashboard]"
+demetrapy-dashboard
+```
+
+## Test
+
+```bash
+python -m unittest discover -s tests
+```
+
+CI runs the complete suite on Linux, Windows, and macOS with representative
+Python 3.9-3.13 and Java 11/17 combinations.

demetrapy-0.1.0/README.md

@@ -0,0 +1,151 @@
+# demetrapy
+
+[![CI](https://github.com/SermetPekin/seasonal-pri/actions/workflows/ci.yml/badge.svg)](https://github.com/SermetPekin/seasonal-pri/actions/workflows/ci.yml)
+
+A Python command-line interface for seasonal adjustment with
+[JDemetra+ core](https://github.com/jdemetra/jdemetra-core). It calls the real
+X13 and TRAMO/SEATS implementations through JPype and does not require Maven or
+a Demetra+ desktop installation.
+
+## Requirements
+
+- Python 3.9 or newer
+- Java 8 or newer
+
+## Install
+
+Windows users should follow the [Windows usage guide](WINDOWS_USAGE.md), which
+also covers proxy-restricted and fully offline JAR installation.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e .
+```
+
+The pinned `demetra-tstoolkit` 2.2.6 JAR is downloaded from Maven Central on
+the first run and cached in `~/.cache/demetrapy`. Set `DEMETRAPY_JAR` to
+use a local JAR instead.
+
+## Use
+
+Input is a regular monthly, quarterly, half-yearly, or yearly CSV series:
+
+```csv
+date,value
+2019-01-01,101.2
+2019-02-01,103.8
+```
+
+Run with defaults (`Monthly`, `RSA4`):
+
+```bash
+demetrapy input.csv --output adjusted.csv
+```
+
+The equivalent fully named form is:
+
+```bash
+demetrapy --data input.csv --config examples/config.json --output adjusted.csv
+```
+
+Or provide a JSON configuration. The full example includes TRAMO/SEATS,
+calendar effects, user regressors, outliers, interventions, and ramps:
+
+```bash
+demetrapy input.csv --config examples/config.json --output adjusted.csv
+demetrapy input.csv --config examples/full_config.json --output adjusted.csv
+```
+
+See the [usage guide](USAGE.md) for the complete input, configuration, output,
+and Python API reference, or the [Windows usage guide](WINDOWS_USAGE.md) for
+Command Prompt instructions.
+
+The supported runtime matrix and result stability policy are documented in
+[COMPATIBILITY.md](COMPATIBILITY.md).
+See [CONFIGURATION.md](CONFIGURATION.md) for processing order, compatible
+option groups, defaults, ARIMA controls, calendars, X11, SEATS, and detailed
+result semantics.
+
+The result contains the original (`y`), seasonally adjusted (`sa`), trend
+(`t`), seasonal (`s`), and irregular (`i`) series.
+
+Configuration supports X13 and TRAMO/SEATS presets, preprocessing and
+decomposition overrides, built-in and custom calendars, CSV-backed user
+variables, prespecified and automatically detected outliers, interventions,
+ramps, and fixed coefficients.
+
+The same engine is available from Python:
+
+```python
+from demetrapy import adjust
+
+result = adjust(values, frequency="Monthly", start_year=2019, spec="RSA4")
+seasonally_adjusted = result["sa"]
+```
+
+Opt into the complete JDemetra result dictionary, scalar diagnostics, and
+processing messages with `detailed=True`. Returned time series retain their
+own frequency and starting period, including forecasts and backcasts.
+Detailed results also expose the fitted ARIMA orders and whether automatic
+model selection was used through `result.arima_model`.
+See [automatic_arima_example.py](examples/automatic_arima_example.py) and
+[explicit_arima_example.py](examples/explicit_arima_example.py) for runnable
+examples with both processing engines.
+The [full TRAMO/SEATS UserDefined calendar example](examples/full_tramoseats_user_calendar_example.py)
+combines a separate calendar pool, explicit seasonal ARIMA model, all supported
+TRAMO estimation controls, outlier detection, forecasts, and SEATS options.
+The [quarterly example](examples/quarterly_example.py) demonstrates frequency
+inference and compares X13 with TRAMO/SEATS using a seasonal period of four.
+
+```python
+detailed = adjust(
+	values,
+	frequency="Monthly",
+	start_year=2019,
+	forecast_horizon=12,
+	detailed=True,
+)
+forecast = detailed.series["final.sa_f"]
+```
+
+See [examples/dataframe_user_variables_example.py](examples/dataframe_user_variables_example.py)
+for a pandas example that keeps observations and a broad user-defined calendar
+pool in separate DataFrames. `adjust_dataframe()` infers their frequency and
+domains, validates coverage, and lets each target select different calendar
+columns using the same semantics as GUI `Trading Days > UserDefined`.
+The [retail operations case study](examples/RETAIL_CASE_STUDY.md) turns that
+example into a reproducible multi-target adjustment and forecasting workflow.
+
+To run X13 and TRAMO/SEATS against the same deterministic series, compare every
+compact component, and write aligned results to `method_comparison.csv`:
+
+```bash
+python examples/compare_methods.py
+```
+
+## Plots and Dashboard
+
+Install optional visualization support:
+
+```bash
+python -m pip install -e ".[plots]"
+demetrapy --data input.csv --plot-output adjustment.png
+```
+
+For an interactive local interface with CSV uploads, multi-series controls,
+calendar mappings, Plotly charts, diagnostics, messages, and downloads:
+
+```bash
+python -m pip install -e ".[dashboard]"
+demetrapy-dashboard
+```
+
+## Test
+
+```bash
+python -m unittest discover -s tests
+```
+
+CI runs the complete suite on Linux, Windows, and macOS with representative
+Python 3.9-3.13 and Java 11/17 combinations.

demetrapy-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "demetrapy"
+version = "0.1.0"
+description = "A Python CLI for seasonal adjustment with JDemetra+ core"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = ["JPype1>=1.5,<2"]
+keywords = ["seasonal-adjustment", "jdemetra", "x13", "tramo-seats", "time-series"]
+classifiers = [
+	"Development Status :: 3 - Alpha",
+	"Environment :: Console",
+	"Intended Audience :: Financial and Insurance Industry",
+	"Intended Audience :: Science/Research",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3 :: Only",
+	"Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.urls]
+Documentation = "https://github.com/SermetPekin/seasonal-pri/blob/main/USAGE.md"
+Issues = "https://github.com/SermetPekin/seasonal-pri/issues"
+Repository = "https://github.com/SermetPekin/seasonal-pri"
+
+[project.optional-dependencies]
+examples = ["pandas>=2,<4"]
+plots = ["pandas>=2,<4", "matplotlib>=3.8,<4"]
+dashboard = [
+	"pandas>=2,<4",
+	"matplotlib>=3.8,<4",
+	"plotly>=6,<7",
+	"streamlit>=1.40,<2",
+]
+
+[project.scripts]
+demetrapy = "demetrapy.cli:main"
+demetrapy-dashboard = "demetrapy.dashboard:launch"
+
+[tool.setuptools.packages.find]
+where = ["src"]

demetrapy-0.1.0/setup.cfg

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

demetrapy-0.1.0/src/demetrapy/__init__.py

@@ -0,0 +1,28 @@
+"""Python access to JDemetra+ seasonal adjustment."""
+
+from .engine import (
+	COMPACT_COMPONENTS,
+	RESULT_SCHEMA_VERSION,
+	AdjustmentResult,
+	ArimaModel,
+	OutputSeries,
+	ProcessingMessage,
+	adjust,
+)
+from .dataframe import DataFrameAdjustmentResult, adjust_dataframe
+from .interactive import plot_adjustment_interactive
+from .plotting import plot_adjustment
+
+__all__ = [
+	"AdjustmentResult",
+	"ArimaModel",
+	"COMPACT_COMPONENTS",
+	"DataFrameAdjustmentResult",
+	"OutputSeries",
+	"ProcessingMessage",
+	"RESULT_SCHEMA_VERSION",
+	"adjust",
+	"adjust_dataframe",
+	"plot_adjustment",
+	"plot_adjustment_interactive",
+]

demetrapy-0.1.0/src/demetrapy/cli.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+import argparse
+import csv
+import sys
+from dataclasses import replace
+from datetime import date
+from pathlib import Path
+from typing import Sequence, TextIO
+
+from .config import AdjustmentConfig
+from .engine import COMPACT_COMPONENTS, AdjustmentResult, adjust
+from .plotting import plot_adjustment
+
+PERIODS_PER_YEAR = {"Monthly": 12, "Quarterly": 4, "HalfYearly": 2, "Yearly": 1}
+
+
+def _read_csv(
+    path: Path, config: AdjustmentConfig
+) -> tuple[list[str], list[float], dict[str, list[float]]]:
+    with path.open(newline="", encoding="utf-8-sig") as stream:
+        reader = csv.DictReader(stream)
+        columns = reader.fieldnames or []
+        variable_columns = config.user_variable_columns()
+        required = {config.date_column, config.value_column, *variable_columns}
+        if not required.issubset(columns):
+            raise ValueError(f"CSV must contain columns: {', '.join(sorted(required))}")
+        dates: list[str] = []
+        values: list[float] = []
+        user_values = {column: [] for column in variable_columns}
+        for row_number, row in enumerate(reader, start=2):
+            dates.append(row[config.date_column])
+            try:
+                values.append(float(row[config.value_column]))
+                for column in variable_columns:
+                    user_values[column].append(float(row[column]))
+            except (TypeError, ValueError) as error:
+                raise ValueError(f"invalid number on CSV row {row_number}") from error
+    if not values:
+        raise ValueError("CSV contains no observations")
+    return dates, values, user_values
+
+
+def _start(dates: Sequence[str], frequency: str) -> tuple[int, int]:
+    try:
+        first = date.fromisoformat(dates[0])
+        periods = PERIODS_PER_YEAR[frequency]
+    except (ValueError, KeyError) as error:
+        raise ValueError(
+            "the first date must be ISO YYYY-MM-DD and frequency must be "
+            f"one of {', '.join(PERIODS_PER_YEAR)}"
+        ) from error
+    return first.year, ((first.month - 1) * periods // 12) + 1
+
+
+def _write_csv(
+    stream: TextIO, dates: Sequence[str], result: dict[str, list[float]]
+) -> None:
+    writer = csv.writer(stream)
+    names = list(result)
+    writer.writerow(["date", *names])
+    writer.writerows(
+        [current_date, *(result[name][index] for name in names)]
+        for index, current_date in enumerate(dates)
+    )
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="demetrapy",
+        description="Seasonally adjust a regular CSV series with JDemetra+ core.",
+    )
+    parser.add_argument(
+        "input", nargs="?", type=Path, help="CSV containing date and value columns"
+    )
+    parser.add_argument(
+        "-d", "--data", type=Path, help="CSV data file (alternative to positional input)"
+    )
+    parser.add_argument("-c", "--config", type=Path, help="JSON adjustment configuration")
+    parser.add_argument("-o", "--output", type=Path, help="output CSV (default: stdout)")
+    parser.add_argument("--method", choices=("x13", "tramoseats"), help="processing method")
+    parser.add_argument("--spec", help="JDemetra+ preset, such as RSA4 or RSAfull")
+    parser.add_argument(
+        "--frequency", choices=tuple(PERIODS_PER_YEAR), help="observation frequency"
+    )
+    parser.add_argument("--date-column", help="CSV date column")
+    parser.add_argument("--value-column", help="CSV value column")
+    parser.add_argument("--plot", action="store_true", help="display an overview plot")
+    parser.add_argument("--plot-output", type=Path, help="save an overview plot as PNG")
+    return parser
+
+
+def run(argv: Sequence[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.input and args.data:
+            raise ValueError("provide the data file either positionally or with --data, not both")
+        input_path = args.data or args.input
+        if input_path is None:
+            raise ValueError("a data file is required; use --data FILE or a positional path")
+        config = AdjustmentConfig.load(args.config)
+        overrides = {
+            name: getattr(args, name)
+            for name in ("method", "spec", "frequency", "date_column", "value_column")
+            if getattr(args, name) is not None
+        }
+        if overrides:
+            config = replace(config, **overrides)
+        dates, values, user_values = _read_csv(input_path, config)
+        start_year, start_period = _start(dates, config.frequency)
+        wants_plot = args.plot or args.plot_output is not None
+        engine_options = config.engine_options(user_values)
+        if wants_plot:
+            engine_options["detailed"] = True
+        engine_result = adjust(
+            values,
+            start_year=start_year,
+            start_period=start_period,
+            **engine_options,
+        )
+        if isinstance(engine_result, AdjustmentResult):
+            result = {
+                name: list(engine_result.series[f"final.{name}"].values)
+                for name in COMPACT_COMPONENTS
+            }
+        else:
+            result = engine_result
+        if any(len(series) != len(dates) for series in result.values()):
+            raise RuntimeError("JDemetra+ returned an unexpected output length")
+        if args.output:
+            with args.output.open("w", newline="", encoding="utf-8") as stream:
+                _write_csv(stream, dates, result)
+        else:
+            _write_csv(sys.stdout, dates, result)
+        if wants_plot:
+            figure = plot_adjustment(
+                engine_result,
+                index=dates,
+                title=input_path.stem,
+            )
+            if args.plot_output:
+                figure.savefig(args.plot_output, dpi=150)
+            if args.plot:
+                import matplotlib.pyplot as plt
+
+                plt.show()
+        return 0
+    except (ImportError, OSError, ValueError, RuntimeError) as error:
+        print(f"demetrapy: {error}", file=sys.stderr)
+        return 2
+
+
+def main() -> None:
+    raise SystemExit(run())

demetrapy-0.1.0/src/demetrapy/config.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AdjustmentConfig:
+    frequency: str = "Monthly"
+    method: str = "x13"
+    spec: str = "RSA4"
+    date_column: str = "date"
+    value_column: str = "value"
+    decomposition_mode: str | None = None
+    seasonal_filter: str | None = None
+    henderson_filter_length: int | None = None
+    lower_sigma: float | None = None
+    upper_sigma: float | None = None
+    forecast_horizon: int | None = None
+    backcast_horizon: int | None = None
+    benchmarking: bool = False
+    calendar: dict[str, Any] | None = None
+    user_variables: list[dict[str, Any]] = field(default_factory=list)
+    outliers: list[dict[str, Any]] = field(default_factory=list)
+    interventions: list[dict[str, Any]] = field(default_factory=list)
+    ramps: list[dict[str, Any]] = field(default_factory=list)
+    fixed_coefficients: dict[str, float | list[float]] = field(default_factory=dict)
+    preprocessing: dict[str, Any] | None = None
+    outlier_detection: dict[str, Any] | None = None
+    seats: dict[str, Any] | None = None
+
+    @classmethod
+    def load(cls, path: str | Path | None) -> "AdjustmentConfig":
+        if path is None:
+            return cls()
+        with Path(path).open(encoding="utf-8") as stream:
+            payload: Any = json.load(stream)
+        if not isinstance(payload, dict):
+            raise ValueError("config must be a JSON object")
+        try:
+            return cls(**payload)
+        except TypeError as error:
+            raise ValueError(f"invalid config: {error}") from error
+
+    def engine_options(
+        self, user_values: dict[str, list[float]] | None = None
+    ) -> dict[str, object]:
+        options = asdict(self)
+        options.pop("date_column")
+        options.pop("value_column")
+        variables = []
+        for definition in options["user_variables"]:
+            variable = dict(definition)
+            column = variable.pop("column", None)
+            if "values" not in variable:
+                if column is None or user_values is None or column not in user_values:
+                    raise ValueError(
+                        f"user variable '{variable.get('name', '')}' needs a CSV column or values"
+                    )
+                variable["values"] = user_values[column]
+            variables.append(variable)
+        options["user_variables"] = variables
+        return options
+
+    def user_variable_columns(self) -> list[str]:
+        return [
+            str(variable["column"])
+            for variable in self.user_variables
+            if "values" not in variable and "column" in variable
+        ]