macrotrace 0.2.0__tar.gz → 0.3.0__tar.gz

{macrotrace-0.2.0 → macrotrace-0.3.0}/.github/workflows/docs.yml

@@ -37,7 +37,7 @@ jobs:
       - name: Deploy dev docs (push to main)
         if: github.ref == 'refs/heads/main'
         run: |
-          uv run mike deploy --push --update-aliases dev
+          uv run mike deploy --push --update-aliases --prop-set hidden=true dev
           if ! uv run mike list 2>/dev/null | grep -qE '^[0-9]'; then
             uv run mike set-default --push dev
           fi
@@ -49,7 +49,7 @@ jobs:
           if [[ "$VERSION" =~ (rc|a|b|dev|alpha|beta) ]]; then
             uv run mike deploy --push "$VERSION"
           else
-            uv run mike deploy --push --update-aliases "$VERSION" latest
+            uv run mike deploy --push --update-aliases --alias-type copy "$VERSION" latest
             uv run mike set-default --push latest
           fi
 

macrotrace-0.3.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/).
+
+## 0.3.0 — 2026-06-15
+
+- **Breaking:** Naive date inputs (`as_of`, the vintage/data windows,
+  `vintage_comparison`) are read on the source's clock instead of UTC.
+  This fixes same-day vintages being silently skipped for FRED,
+  which stamps releases at midnight US Central:
+  `as_of("2018-03-16")` now returns the 2018-03-16 vintage, and a
+  `data_end_date` on a period boundary no longer drops the final observation.
+  Timezone-aware datetimes still compare as exact instants.
+- **Breaking:** Date strings must be `YYYY-MM-DD`; `datetime.date` objects
+  are now accepted. Free-text parsing is gone (along with the `dateutil`
+  dependency), so ambiguous formats like `"03/04/2018"` are rejected instead
+  of guessed.
+- **Fixed:** `created_at` columns stamped each row with the process start
+  time instead of its actual creation time.
+
+## 0.2.2 — 2026-06-12
+
+- **Vintage matching:** `identify_vintage` now interprets a tz-naive index in
+  the source's native timezone (e.g. midnight US Central for FRED) instead of
+  UTC, so plain dates match FRED vintages.
+- **Vintage matching:** Added a `decimals` argument that rounds both sides
+  before comparison, for matching data published at a fixed precision.
+- **Vintage matching:** `VintageMatch.failure_reason` now reports why nothing
+  matched: timestamps no vintage contains (`"coverage"`) vs value
+  disagreements (`"values"`).
+- **Vintage matching:** Numeric/positional indexes are rejected with a clear
+  error, and `pd.PeriodIndex` is supported.
+- **Vintage matching:** When nothing matches, `VintageMatch.alignment_hint`
+  flags timestamps that would match under a wrong timezone localization, a
+  constant time shift, or a month-end vs month-start convention.
+
+## 0.2.1 — 2026-06-11
+
+- **Docs:** RTDSM is now listed as an available source on the documentation
+  homepage — it had been left under "Coming Soon" when 0.2.0 shipped.
+- **Docs:** The version selector now shows the `latest` label next to the
+  release it points at, and the in-development `dev` build is hidden from
+  the selector (it is still reachable directly at `/dev/`).
+
+## 0.2.0 — 2026-06-10
+
+- **Sources:** Added the Federal Reserve Bank of Philadelphia's Real-Time
+  Data Set for Macroeconomists (RTDSM) — vintage-aware ingestion of 115 U.S.
+  macroeconomic series. Each series is parsed from the published full-history spreadsheet; an optional `series_key={"frequency": "Q" | "M"}` selects the vintage frequency, and a monthly refresh throttle avoids re-downloading the same series
+  within a calendar month as requested by the Philadelphia Federal Reserve Bank.
+- **Vintage matching:** Added `MTTimeSeries.identify_vintage(...)`, which
+  recovers which release(s) an undated block of observations came from by
+  comparing it against every stored vintage. Returns a `VintageMatch`
+  (`matched`, `is_ambiguous`, `release_date` / `release_dates`) — useful for
+  pinning down the vintage behind replication-package data.
+- **Time series:** Added `MTTimeSeries.to_series(...)`, the values-only,
+  date-indexed pandas `Series` counterpart to `to_dataframe` (supports the
+  `default`, `first_difference`, and `pct_change` modes). Exposed
+  `VintageMatch` at the package root.
+
+## 0.1.0 — 2026-04-28
+
+First public release.
+
+- **Sources:** vintage-aware ingestion from FRED and ONS, with a local
+  SQLite store (`MacroTrace.db`) and shared request cache.
+- **Time series:** `MTTimeSeries` with `as_of(...)`, vintage- and
+  data-window filtering, `from_dataframe`, and pandas / Darts export.
+- **Analysis:** revision metrics, vintage comparison, decomposition
+  across vintages, biasedness regression, and revision autocorrelation.
+- **Plotting:** Plotly-based vintage, revision, and decomposition plots
+  via `MTTimeSeriesPlotter`.
+- **CLI / TUI:** `macrotrace ons explorer` and `macrotrace ons tui`
+  (the latter via the optional `ons-tui` extra).

{macrotrace-0.2.0 → macrotrace-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macrotrace
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Python library for managing and analyzing macroeconomic time series data with vintage awareness.
 Project-URL: Homepage, https://github.com/john-ramsey/macrotrace
 Project-URL: Repository, https://github.com/john-ramsey/macrotrace
@@ -170,13 +170,9 @@ if match.is_ambiguous:
 elif match.matched:
     print(f"Matches the {match.release_date.date()} vintage")
 else:
-    print("No matching vintage found")
+    print(f"No matching vintage found (failed on: {match.failure_reason})")
 ```
 
-A match is ambiguous when the data is unchanged across consecutive vintages, so
-the values alone cannot pin down a single release; `release_dates` lists every
-consistent vintage in that case.
-
 ## Command-Line Tools
 
 MacroTrace includes command-line tools for exploring ONS datasets:

{macrotrace-0.2.0 → macrotrace-0.3.0}/README.md

@@ -129,13 +129,9 @@ if match.is_ambiguous:
 elif match.matched:
     print(f"Matches the {match.release_date.date()} vintage")
 else:
-    print("No matching vintage found")
+    print(f"No matching vintage found (failed on: {match.failure_reason})")
 ```
 
-A match is ambiguous when the data is unchanged across consecutive vintages, so
-the values alone cannot pin down a single release; `release_dates` lists every
-consistent vintage in that case.
-
 ## Command-Line Tools
 
 MacroTrace includes command-line tools for exploring ONS datasets:

macrotrace-0.3.0/macrotrace/_time.py

@@ -0,0 +1,19 @@
+from datetime import datetime, tzinfo
+from typing import Optional
+
+
+def ensure_timezone(dt: Optional[datetime], tz: tzinfo) -> Optional[datetime]:
+    """
+    Return the datetime made aware in ``tz``, or None.
+
+    Naive datetimes keep their wall clock while aware ones are converted. Uses pytz's
+    ``localize()`` when available so the real historical offset is picked
+    instead of pytz's first entry for the zone (LMT).
+    """
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        if hasattr(tz, "localize"):
+            return tz.localize(dt)
+        return dt.replace(tzinfo=tz)
+    return dt.astimezone(tz)

{macrotrace-0.2.0 → macrotrace-0.3.0}/macrotrace/models/db.py

@@ -40,6 +40,11 @@ def is_valid_dateoffset(value: str) -> bool:
         return False
 
 
+def _utc_now() -> datetime.datetime:
+    """Callable default so each row stamps its own creation time, not the import time."""
+    return datetime.datetime.now(tz=datetime.timezone.utc)
+
+
 class StrictDateTimeField(DateTimeField):
     """DateTimeField that enforces timezone-aware datetime objects in ISO 8601 format."""
 
@@ -122,9 +127,7 @@ class DatasetDimension(DataBaseModel):
     # Validity period for this dimension definition, null valid_to means currently valid
     valid_from = StrictDateTimeField()
     valid_to = StrictDateTimeField(null=True)
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [
@@ -152,9 +155,7 @@ class Release(DataBaseModel):
     )
     release_date = StrictDateTimeField()
     additional_metadata = JSONField(null=True)
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(dataset_id, release_date)")]
@@ -182,9 +183,7 @@ class ReleaseDimension(DataBaseModel):
         backref="release_dimensions",
         on_delete="CASCADE",
     )
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(release_id, dimension_id)")]
@@ -199,9 +198,7 @@ class ReleaseDimension(DataBaseModel):
 class Series(DataBaseModel):
     dataset = ForeignKeyField(Dataset, backref="series", on_delete="CASCADE")
     series_key = JSONField()
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     def __repr__(self):
         return (
@@ -249,9 +246,7 @@ class Observation(DataBaseModel):
 
     observation_timestamp = StrictDateTimeField()
     value = FloatField(null=True)  # null if the observation is missing
-    created_at = StrictDateTimeField(
-        default=datetime.datetime.now(tz=datetime.timezone.utc)
-    )
+    created_at = StrictDateTimeField(default=_utc_now)
 
     class Meta:
         constraints = [SQL("UNIQUE(release_id, observation_timestamp)")]

{macrotrace-0.2.0 → macrotrace-0.3.0}/macrotrace/models/mt/analysis.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING, Union
+import datetime
 import logging
 
 import numpy as np
@@ -510,7 +511,6 @@ class MTTimeSeriesAnalysis:
         darts_ts = self.ts.to_darts_timeseries()
 
         if len(darts_ts) >= (min_train_size + 1):
-
             for i in range(min_train_size, len(darts_ts)):
                 train = darts_ts[:i]
                 test = darts_ts[i : i + 1]
@@ -629,7 +629,10 @@ class MTTimeSeriesAnalysis:
         )
 
     def vintage_comparison(
-        self, vintage_dates: List[str], mode: str = "growth", strategy: str = "all"
+        self,
+        vintage_dates: List[str | datetime.datetime | datetime.date],
+        mode: str = "growth",
+        strategy: str = "all",
     ) -> "VintageComparison":
         """
         Compare vintages across summary measures describing revisions of a
@@ -677,7 +680,9 @@ class MTTimeSeriesAnalysis:
                   period-over-period change in the level changes sign between vintages.
 
         Args:
-            vintage_dates (List[str]): A list of vintage identifiers to compare.
+            vintage_dates (List[str | datetime | date]): The vintages to
+                compare, each resolved through ``as_of()`` — a ``YYYY-MM-DD``
+                string or date for a calendar day, or a datetime for an exact instant.
             mode (str): The mode of comparison ("growth" or "levels").
             strategy (str): The strategy for comparison ("sequential", "final", or "all").
 

{macrotrace-0.2.0 → macrotrace-0.3.0}/macrotrace/models/mt/plotter.py

@@ -1,5 +1,5 @@
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Union
-from datetime import datetime
+from datetime import date, datetime
 import warnings
 
 import numpy as np
@@ -147,9 +147,8 @@ class MTTimeSeriesPlotter:
             go.Figure: Plotly figure showing observation revisions over time.
         """
         if isinstance(observation_datetime, str):
-            observation_datetime = self.ts._parse_string_date(
-                observation_datetime
-            )  # Returns UTC timezone
+            # Resolves to the source's midnight on that day
+            observation_datetime = self.ts._parse_string_date(observation_datetime)
         elif not isinstance(observation_datetime, datetime):
             raise ValueError(
                 f"Invalid observation datetime type: {type(observation_datetime)}. Must be a string or a datetime."
@@ -588,7 +587,7 @@ class MTTimeSeriesPlotter:
 
     def timeseries_comparison(
         self,
-        vintage_dates: List[str | datetime],
+        vintage_dates: List[str | datetime | date],
         chart_type: str = "bar",
         mode: str = "default",
         y_axis_zero_indexed: bool = False,
@@ -597,7 +596,7 @@ class MTTimeSeriesPlotter:
         Plots a comparison of time series vintages.
 
         Args:
-            vintage_dates (List[str | datetime]): List of vintage identifiers. Ex. '2025-11-01'
+            vintage_dates (List[str | datetime | date]): List of vintage identifiers, resolved via ``as_of``. Ex. '2025-11-01'
             chart_type (str, optional): Type of chart to plot. Either "bar" or "line". Defaults to "bar".
             mode (str, optional): The mode for which the dataframe is provided. Supports "default", "first_difference", and "pct_change". Defaults to "default".
             y_axis_zero_indexed (bool, optional): Sets base of the y-axis to zero.
@@ -610,14 +609,6 @@ class MTTimeSeriesPlotter:
                 f"Invalid mode: {mode}. Supported modes are 'default', 'first_difference', and 'pct_change'."
             )
 
-        for vintage_date in vintage_dates:
-            if (not isinstance(vintage_date, str)) and (
-                not isinstance(vintage_date, datetime)
-            ):
-                raise TypeError(
-                    "Vintage dates must be provided as strings or datetime objects."
-                )
-
         fig = go.Figure()
         all_values = []
         hoverinfo = "x+y+name"
@@ -626,7 +617,7 @@ class MTTimeSeriesPlotter:
             df = self.ts.as_of(vintage_date).to_dataframe(mode=mode)
             vintage_date = (
                 vintage_date.strftime("%Y-%m-%d")
-                if isinstance(vintage_date, datetime)
+                if isinstance(vintage_date, date)
                 else vintage_date
             )
             if chart_type == "bar":