demetrapy

demetrapy exposes JDemetra+ X13 and TRAMO/SEATS through Python, pandas, a command-line interface, and a Streamlit dashboard. It supports monthly through yearly data, calendars, regressors, outliers, ARIMA models, and forecasts.

Installation

demetrapy requires Python 3.11 or later and Java 8 or later.

python -m pip install demetrapy
demetrapy check

New users can follow the five-minute quickstart from installation through validation and the first adjustment.

For development from a clone:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

The first calculation downloads the pinned demetra-tstoolkit 2.2.6 JAR from Maven Central and stores it in ~/.cache/demetrapy. Set DEMETRAPY_JAR to the path of a local copy when automatic download is not suitable. The Windows guide covers Command Prompt and offline setup.

Python interface

For a pandas object with a regular DatetimeIndex, adjust_dataframe() infers the observation frequency and adjusts each column separately:

import pandas as pd

from demetrapy import adjust_dataframe

data = pd.DataFrame(
	{"production": observations},
	index=pd.date_range("2015-01-01", periods=len(observations), freq="MS"),
)

result = adjust_dataframe(data, method="x13", spec="RSA4")
adjusted = result.seasonally_adjusted["production"]

The lower-level adjust() function accepts one regular sequence and an explicit starting period:

from demetrapy import adjust

result = adjust(
    values,
    frequency="Quarterly",
    start_year=2005,
    start_period=1,
    method="tramoseats",
    spec="RSA4",
)
adjusted = result.seasonally_adjusted.values

For quarterly data, adjust_dataframe() and adjust_csv() infer frequency from regular dates. Raw sequences have no dates, so pass frequency="Quarterly" and a one-based start_period. See the quarterly example.

Both functions always return a stable result object. Their components attribute exposes six named series used in routine work:

Use to_compact_dict() or to_compact_frame() when the short aliases are needed. Forecasts preserve their own future domain under result.forecasts; to_forecast_dict() provides y_f, ycal_f, sa_f, t_f, s_f, and i_f when a forecast horizon is active:

seasonal_forecast = result.forecasts.seasonal
forecast_values = result.to_forecast_dict()

Pandas results also provide to_forecast_frame() and to_combined_frame(). For example, result.to_combined_frame(compact=True)[("sales", "sa")] returns one seasonally adjusted series spanning history and forecast dates.

Choose a configuration style

These interfaces run the same engine. Choose one style per call:

Method-specific objects prevent X11 and SEATS settings from being mixed:

from demetrapy import TramoSeatsConfig, X13Config, adjust_dataframe

x13 = X13Config(spec="RSA4", forecast_horizon=12)
tramoseats = TramoSeatsConfig(
  spec="RSAfull",
  seats={"prediction_length": 12},
)

x13_result = adjust_dataframe(data, config=x13)
tramoseats_result = adjust_dataframe(data, config=tramoseats)

The equivalent direct-keyword call is:

x13_result = adjust_dataframe(
  data,
  method="x13",
  spec="RSA4",
  forecast_horizon=12,
)

The same settings can instead live in JSON for adjust_csv() or the CLI. Existing code does not need to migrate.

Set detailed=True to additionally populate the full JDemetra+ result dictionary, diagnostics, processing messages, backcasts, and fitted ARIMA model:

detailed = adjust(
    values,
    frequency="Monthly",
    start_year=2015,
    forecast_horizon=12,
    detailed=True,
)

print(detailed.arima_model.notation)
forecast = detailed.series["final.sa_f"]

Command line

The command-line interface reads a regular CSV file with date and value columns:

date,value
2019-01-01,101.2
2019-02-01,103.8

The default calculation is monthly X13 with the RSA4 preset:

demetrapy input.csv --output adjusted.csv

A JSON file records a fuller specification:

demetrapy \
  --data input.csv \
	--config examples/configs/tramoseats_full.json \
  --output adjusted.csv

The output contains y, ycal, sa, t, s, and i. See the usage guide for all options.

Validate a configuration without starting Java, or create a starter template:

demetrapy validate config.json --data input.csv
demetrapy init-config --method tramoseats --output config.json

Python callers can process the same files directly:

from demetrapy import adjust_csv

result = adjust_csv("input.csv", config="config.json", output="adjusted.csv")

For reproducible operational runs, opt in to a JSON audit manifest and append-only history without storing observation values:

result = adjust_csv("input.csv", output="adjusted.csv", audit="audit/")

Specifications and regressors

The package constructs an isolated JDemetra+ processing context for each calculation. Preset defaults remain those of JDemetra+ unless an option is overridden explicitly.

UserDefined calendar variables use a separate pool; each target selects the columns used by its equation.

See the configuration reference for supported values.

Inspection

A static summary plot can be produced from the command line:

demetrapy --data input.csv --plot-output adjustment.png

The local dashboard is included in the standard installation:

demetrapy-dashboard

It accepts CSV and JSON files, includes built-in sample datasets, and provides interactive results, diagnostics, model details, and downloads.

Examples

See the example guide, or run every example:

python examples/run_all.py

Reproducibility and compatibility

See compatibility for supported Python, Java, and JDemetra+ versions. CI tests both engines on Linux, Windows, and macOS.

python -m unittest discover -s tests

demetrapy is an independent interface to JDemetra+ and is not an official publication of the JDemetra+ project.