macrotrace 0.1.0rc1__py3-none-any.whl

macrotrace/__init__.py

@@ -0,0 +1,39 @@
+"""Macrotrace top-level package exports."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+try:
+    __version__ = version("macrotrace")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+__all__ = [
+    "MTTimeSeries",
+    "MTObservation",
+    "MTSeriesMetadata",
+    "MTTimeSeriesPlotter",
+    "VintageComparison",
+    "__version__",
+]
+
+_LAZY_IMPORTS = {
+    "MTTimeSeries": ("macrotrace.models.mt.time_series", "MTTimeSeries"),
+    "MTObservation": ("macrotrace.models.mt.observation", "MTObservation"),
+    "MTSeriesMetadata": ("macrotrace.models.mt.series_metadata", "MTSeriesMetadata"),
+    "MTTimeSeriesPlotter": ("macrotrace.models.mt.plotter", "MTTimeSeriesPlotter"),
+    "VintageComparison": ("macrotrace.models.mt.analysis", "VintageComparison"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily expose heavy model imports at package level."""
+    target = _LAZY_IMPORTS.get(name)
+    if target is None:
+        raise AttributeError(f"module 'macrotrace' has no attribute {name!r}")
+    module_name, attr = target
+    from importlib import import_module
+
+    return getattr(import_module(module_name), attr)

macrotrace/_paths.py

@@ -0,0 +1,37 @@
+"""Path resolution for macrotrace's SQLite files.
+
+Resolution order for both files: explicit argument, then environment
+variable, then default in the current working directory. If
+``MACROTRACE_DB`` is set but ``MACROTRACE_CACHE`` is not, the cache
+defaults to sitting next to the database file.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+DB_ENV_VAR = "MACROTRACE_DB"
+CACHE_ENV_VAR = "MACROTRACE_CACHE"
+
+DEFAULT_DB_NAME = "MacroTrace.db"
+DEFAULT_CACHE_NAME = "MacroTraceRequestCache.sqlite"
+
+
+def resolve_db_path(arg: Optional[str] = None) -> str:
+    if arg is not None:
+        return arg
+    return os.environ.get(DB_ENV_VAR) or DEFAULT_DB_NAME
+
+
+def resolve_cache_path(arg: Optional[str] = None) -> str:
+    if arg is not None:
+        return arg
+    env_value = os.environ.get(CACHE_ENV_VAR)
+    if env_value:
+        return env_value
+    db_env = os.environ.get(DB_ENV_VAR)
+    if db_env:
+        return str(Path(db_env).resolve().parent / DEFAULT_CACHE_NAME)
+    return DEFAULT_CACHE_NAME

macrotrace/cli.py

@@ -0,0 +1,73 @@
+"""Top-level Macrotrace command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+
+def _run_ons_explorer(args: argparse.Namespace) -> int:
+    from macrotrace.ons_cli.cli import main as ons_main
+
+    return ons_main(args.args)
+
+
+def _run_ons_tui(args: argparse.Namespace) -> int:
+    from macrotrace.ons_cli.tui import main as ons_tui_main
+
+    return ons_tui_main(args.args)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="macrotrace",
+        description="Macrotrace command-line tools.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    ons_parser = subparsers.add_parser(
+        "ons",
+        help="ONS explorer commands.",
+        description="ONS explorer commands.",
+    )
+    ons_subparsers = ons_parser.add_subparsers(dest="ons_command", required=True)
+
+    ons_subparsers.add_parser(
+        "explorer",
+        help="Run the interactive ONS explorer CLI.",
+        description="Run the interactive ONS explorer CLI.",
+    )
+    ons_subparsers.add_parser(
+        "tui",
+        help="Run the Textual ONS explorer TUI.",
+        description="Run the Textual ONS explorer TUI.",
+    )
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    parser = build_parser()
+
+    if not argv:
+        parser.parse_args(argv)
+
+    if argv == ["--help"] or argv == ["-h"]:
+        parser.parse_args(argv)
+
+    if argv[0] != "ons":
+        parser.parse_args(argv)
+
+    if len(argv) == 1 or argv[1] in {"-h", "--help"}:
+        parser.parse_args(argv)
+
+    if argv[1] == "explorer":
+        return _run_ons_explorer(argparse.Namespace(args=argv[2:]))
+
+    if argv[1] == "tui":
+        return _run_ons_tui(argparse.Namespace(args=argv[2:]))
+
+    parser.parse_args(argv)
+    return 2

macrotrace/graphing.py

@@ -0,0 +1,183 @@
+MACROTRACE_COLORWAY = [
+    "#4c72b0",
+    "#dd8452",
+    "#55a868",
+    "#c44e52",
+    "#8172b3",
+    "#937860",
+    "#da8bc3",
+    "#8c8c8c",
+    "#ccb974",
+    "#64b5cd",
+]
+
+MACROTRACE_DIVERGING_COLORSCALE = [
+    [0.0, MACROTRACE_COLORWAY[0]],
+    [0.5, "#ffffff"],
+    [1.0, MACROTRACE_COLORWAY[1]],
+]
+
+MACROTRACE_PLOTLY_LAYOUT_TEMPLATE = {
+    "layout": {
+        "annotationdefaults": {"arrowcolor": "#4368a7"},
+        "autotypenumbers": "strict",
+        "coloraxis": {
+            "colorbar": {
+                "outlinewidth": 0,
+                "tickcolor": "#242424",
+                "ticklen": 8,
+                "ticks": "outside",
+                "tickwidth": 2,
+            }
+        },
+        "colorscale": {
+            "diverging": MACROTRACE_DIVERGING_COLORSCALE,
+            "sequential": [
+                [0.0, "#020419"],
+                [0.06274509803921569, "#180f29"],
+                [0.12549019607843137, "#2f1739"],
+                [0.18823529411764706, "#471c48"],
+                [0.25098039215686274, "#611e52"],
+                [0.3137254901960784, "#7b1e59"],
+                [0.3764705882352941, "#961b5b"],
+                [0.4392156862745098, "#b11658"],
+                [0.5019607843137255, "#cb1a4f"],
+                [0.5647058823529412, "#df2f43"],
+                [0.6274509803921569, "#ec4c3d"],
+                [0.6901960784313725, "#f26b49"],
+                [0.7529411764705882, "#f4875f"],
+                [0.8156862745098039, "#f5a27a"],
+                [0.8784313725490196, "#f6bc99"],
+                [0.9411764705882353, "#f7d4bb"],
+                [1.0, "#faeadc"],
+            ],
+            "sequentialminus": [
+                [0.0, "#020419"],
+                [0.06274509803921569, "#180f29"],
+                [0.12549019607843137, "#2f1739"],
+                [0.18823529411764706, "#471c48"],
+                [0.25098039215686274, "#611e52"],
+                [0.3137254901960784, "#7b1e59"],
+                [0.3764705882352941, "#961b5b"],
+                [0.4392156862745098, "#b11658"],
+                [0.5019607843137255, "#cb1a4f"],
+                [0.5647058823529412, "#df2f43"],
+                [0.6274509803921569, "#ec4c3d"],
+                [0.6901960784313725, "#f26b49"],
+                [0.7529411764705882, "#f4875f"],
+                [0.8156862745098039, "#f5a27a"],
+                [0.8784313725490196, "#f6bc99"],
+                [0.9411764705882353, "#f7d4bb"],
+                [1.0, "#faeadc"],
+            ],
+        },
+        "colorway": MACROTRACE_COLORWAY,
+        "font": {
+            "color": "#242424",
+            "family": "CMU Serif, Old Standard TT, Georgia, Times New Roman, Times, serif",
+        },
+        "geo": {
+            "bgcolor": "white",
+            "lakecolor": "white",
+            "landcolor": "#d3efde",
+            "showlakes": True,
+            "showland": True,
+            "subunitcolor": "white",
+        },
+        "hoverlabel": {"align": "left"},
+        "hovermode": "closest",
+        "paper_bgcolor": "white",
+        "plot_bgcolor": "#eaeaf2",
+        "polar": {
+            "angularaxis": {
+                "gridcolor": "white",
+                "linecolor": "white",
+                "showgrid": True,
+                "ticks": "",
+            },
+            "bgcolor": "#eaeaf2",
+            "radialaxis": {
+                "gridcolor": "white",
+                "linecolor": "white",
+                "showgrid": True,
+                "ticks": "",
+            },
+        },
+        "scene": {
+            "xaxis": {
+                "backgroundcolor": "#eaeaf2",
+                "gridcolor": "white",
+                "gridwidth": 2,
+                "linecolor": "white",
+                "showbackground": True,
+                "showgrid": True,
+                "ticks": "",
+                "zerolinecolor": "white",
+            },
+            "yaxis": {
+                "backgroundcolor": "#eaeaf2",
+                "gridcolor": "white",
+                "gridwidth": 2,
+                "linecolor": "white",
+                "showbackground": True,
+                "showgrid": True,
+                "ticks": "",
+                "zerolinecolor": "white",
+            },
+            "zaxis": {
+                "backgroundcolor": "#eaeaf2",
+                "gridcolor": "white",
+                "gridwidth": 2,
+                "linecolor": "white",
+                "showbackground": True,
+                "showgrid": True,
+                "ticks": "",
+                "zerolinecolor": "white",
+            },
+        },
+        "shapedefaults": {
+            "fillcolor": "#4367a7",
+            "line": {"width": 3},
+            "opacity": 0.5,
+        },
+        "ternary": {
+            "aaxis": {
+                "gridcolor": "white",
+                "linecolor": "white",
+                "showgrid": True,
+                "ticks": "",
+            },
+            "baxis": {
+                "gridcolor": "white",
+                "linecolor": "white",
+                "showgrid": True,
+                "ticks": "",
+            },
+            "bgcolor": "#eaeaf2",
+            "caxis": {
+                "gridcolor": "white",
+                "linecolor": "white",
+                "showgrid": True,
+                "ticks": "",
+            },
+        },
+        "xaxis": {
+            "automargin": True,
+            "gridcolor": "white",
+            "linecolor": "white",
+            "showgrid": True,
+            "ticks": "",
+            "title": {"standoff": 15},
+            "zerolinecolor": "white",
+        },
+        "yaxis": {
+            "automargin": True,
+            "gridcolor": "white",
+            "linecolor": "white",
+            "showgrid": True,
+            "ticks": "",
+            "title": {"standoff": 15},
+            "zerolinecolor": "white",
+        },
+    }
+}

macrotrace/models/__init__.py

@@ -0,0 +1,31 @@
+from macrotrace.models.mt.observation import MTObservation
+from macrotrace.models.mt.series_metadata import MTSeriesMetadata
+from macrotrace.models.mt.time_series import MTTimeSeries
+from macrotrace.models.mt.analysis import VintageComparison
+from macrotrace.models.mt.plotter import MTTimeSeriesPlotter
+from macrotrace.models.db import (
+    LOCAL_DATABASE,
+    Dataset,
+    DatasetDimension,
+    Release,
+    ReleaseDimension,
+    Series,
+    SeriesDimensionFilter,
+    Observation,
+)
+
+__all__ = [
+    "MTObservation",
+    "MTSeriesMetadata",
+    "MTTimeSeries",
+    "VintageComparison",
+    "MTTimeSeriesPlotter",
+    "LOCAL_DATABASE",
+    "Dataset",
+    "DatasetDimension",
+    "Release",
+    "ReleaseDimension",
+    "Series",
+    "SeriesDimensionFilter",
+    "Observation",
+]

macrotrace/models/db.py

@@ -0,0 +1,265 @@
+import datetime
+from peewee import (
+    SQL,
+    DateTimeField,
+    FloatField,
+    ForeignKeyField,
+    Model,
+    SqliteDatabase,
+    TextField,
+)
+from playhouse.sqlite_ext import JSONField
+import pandas as pd
+
+LOCAL_DATABASE = SqliteDatabase(
+    None,
+    pragmas=(
+        ("cache_size", -1024 * 32),  # 32MB page-cache.
+        ("journal_mode", "wal"),
+        ("foreign_keys", 1),
+    ),
+)
+
+
+def is_valid_dateoffset(value: str) -> bool:
+    """
+    Checks if a string is a valid pandas date offset.
+    We are using this to ensure that frequency fields conform to pandas offset strings.
+    Certain export and processing functions depend on this format such as to_darts_timeseries.
+
+    Args:
+        value (str): The string to check.
+
+    Returns:
+        bool: True if the string is a valid pandas date offset, False otherwise.
+    """
+    try:
+        pd.tseries.frequencies.to_offset(value)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+class StrictDateTimeField(DateTimeField):
+    """DateTimeField that enforces timezone-aware datetime objects in ISO 8601 format."""
+
+    def db_value(self, value):
+        if value is None:
+            return None
+        if not isinstance(value, datetime.datetime):
+            raise ValueError(f"Value must be a datetime object, got {type(value)}")
+        if value.tzinfo is None:
+            raise ValueError("Datetime must be timezone-aware (include tzinfo).")
+        return value.isoformat()
+
+    def python_value(self, value):
+        if value is None:
+            return None
+        if isinstance(value, datetime.datetime):
+            return value
+        try:
+            # Parse ISO 8601 format
+            parsed = datetime.datetime.fromisoformat(value)
+            if parsed.tzinfo is None:
+                raise ValueError("Parsed datetime is missing timezone information.")
+            return parsed
+        except (ValueError, AttributeError) as e:
+            raise ValueError(
+                f"Invalid datetime format. Expected ISO 8601 with timezone: {e}"
+            )
+
+
+class FrequencyField(TextField):
+    def db_value(self, value):
+        if value is not None and not is_valid_dateoffset(value):
+            raise ValueError(f"Invalid pandas frequency offset: {value}")
+        return super().db_value(value)
+
+
+class DataBaseModel(Model):
+    class Meta:
+        database = LOCAL_DATABASE
+
+
+class Dataset(DataBaseModel):
+    """Identity of a dataset; versioning lives in DatasetVersion."""
+
+    source = TextField()
+    dataset_id = TextField()
+
+    class Meta:
+        constraints = [SQL("UNIQUE(source, dataset_id)")]
+
+    def __repr__(self):
+        return f"Dataset(source={self.source}, dataset_id={self.dataset_id})"
+
+
+class DatasetDimension(DataBaseModel):
+    """
+    Identity of a dataset dimension.
+    """
+
+    dataset = ForeignKeyField(
+        Dataset,
+        backref="dimensions",
+        on_delete="CASCADE",
+    )
+    # This is the ID used by the source to identify the dimension
+    # This should NOT change as the dimension is versioned via valid_from and valid_to
+    dataset_dimension_id = TextField()
+    title = TextField()
+    type = TextField(
+        choices=[
+            ("text", "text"),
+            ("numeric", "numeric"),
+            ("boolean", "boolean"),
+        ]
+    )
+    frequency = FrequencyField(null=True)
+    description = TextField(null=True)
+    units = TextField(null=True)
+    seasonal_adjustment = TextField(null=True)
+    # 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)
+    )
+
+    class Meta:
+        constraints = [
+            SQL("UNIQUE(dataset_id, dataset_dimension_id, valid_from)"),
+            SQL("CHECK(type IN ('text', 'numeric', 'boolean'))"),
+            SQL("CHECK(valid_to IS NULL OR valid_to > valid_from)"),
+        ]
+
+    def __repr__(self):
+        return (
+            f"DatasetDimension(dataset={self.dataset.dataset_id}, title={self.title})"
+        )
+
+
+class Release(DataBaseModel):
+    """
+    A release of data in a dataset at a point in time.
+    It is not versioned itself as releases are theoretically immutable once created.
+    """
+
+    dataset = ForeignKeyField(
+        Dataset,
+        backref="releases",
+        on_delete="CASCADE",
+    )
+    release_date = StrictDateTimeField()
+    additional_metadata = JSONField(null=True)
+    created_at = StrictDateTimeField(
+        default=datetime.datetime.now(tz=datetime.timezone.utc)
+    )
+
+    class Meta:
+        constraints = [SQL("UNIQUE(dataset_id, release_date)")]
+
+    def __repr__(self):
+        return (
+            f"Release(dataset={self.dataset.dataset_id}, "
+            f"release_date={self.release_date})"
+        )
+
+
+class ReleaseDimension(DataBaseModel):
+    """
+    Association table for many-to-many relationship between Release and DatasetDimension.
+    Tracks which dimensions are included in each release.
+    """
+
+    release = ForeignKeyField(
+        Release,
+        backref="release_dimensions",
+        on_delete="CASCADE",
+    )
+    dimension = ForeignKeyField(
+        DatasetDimension,
+        backref="release_dimensions",
+        on_delete="CASCADE",
+    )
+    created_at = StrictDateTimeField(
+        default=datetime.datetime.now(tz=datetime.timezone.utc)
+    )
+
+    class Meta:
+        constraints = [SQL("UNIQUE(release_id, dimension_id)")]
+
+    def __repr__(self):
+        return (
+            f"ReleaseDimension(release={self.release.release_date}, "
+            f"dimension={self.dimension.title})"
+        )
+
+
+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)
+    )
+
+    def __repr__(self):
+        return (
+            f"Series(dataset = {self.dataset.dataset_id}, series_key={self.series_key})"
+        )
+
+
+class SeriesDimensionFilter(DataBaseModel):
+    series = ForeignKeyField(
+        Series,
+        backref="dimension_selections",
+        on_delete="CASCADE",
+    )
+    dimension = ForeignKeyField(
+        DatasetDimension,
+        on_delete="CASCADE",
+    )
+    # For numeric or boolean dimensions
+    # Store as text, cast as needed based on dimension.type
+    value = TextField()
+
+    class Meta:
+        constraints = [
+            SQL("UNIQUE(series_id, dimension_id, value)"),
+        ]
+
+    def __repr__(self):
+        return (
+            f"SeriesDimensionFilter(series={self.series.series_key}, "
+            f"dimension={self.dimension.title}, value={self.value})"
+        )
+
+
+class Observation(DataBaseModel):
+    series = ForeignKeyField(
+        Series,
+        backref="observations",
+        on_delete="CASCADE",
+    )
+    release = ForeignKeyField(
+        Release,
+        backref="observations",
+        on_delete="CASCADE",
+    )
+
+    observation_timestamp = StrictDateTimeField()
+    value = FloatField(null=True)  # null if the observation is missing
+    created_at = StrictDateTimeField(
+        default=datetime.datetime.now(tz=datetime.timezone.utc)
+    )
+
+    class Meta:
+        constraints = [SQL("UNIQUE(release_id, observation_timestamp)")]
+
+    def __repr__(self):
+        return (
+            f"Observation(series={self.series.series_key}, "
+            f"release={self.release.release_date}, "
+            f"observation_timestamp={self.observation_timestamp}, "
+            f"value={self.value})"
+        )

macrotrace/models/mt/__init__.py

@@ -0,0 +1,8 @@
+"""MacroTrace models for time series data."""
+
+from macrotrace.models.mt.time_series import MTTimeSeries
+from macrotrace.models.mt.analysis import VintageComparison
+from macrotrace.models.mt.series_metadata import MTSeriesMetadata
+from macrotrace.models.mt.observation import MTObservation
+
+__all__ = ["MTTimeSeries", "VintageComparison", "MTSeriesMetadata", "MTObservation"]