nowcastbox 0.1.0__py3-none-any.whl

nowcastbox/__init__.py

@@ -0,0 +1,268 @@
+"""NowcastBox: nowcasting with dynamic factor models in Python.
+
+The most used objects are available at the top level (``nb.MixedFreqDFM``,
+``nb.prepare_panel``, ``nb.select_factors``, ``nb.pseudo_real_time``, ``nb.nowcast``,
+``nb.news_decomposition``, ``nb.PseudoRealTimeBacktest``, ``nb.nowcast_distribution``,
+``nb.run_diagnostics``, ``nb.NowcastReport``, ``nb.load_brazil_nowcast``,
+``nb.select_blocks``, ``nb.run_pipeline``...); the subpackages (``nb.preprocessing``,
+``nb.statespace``, ``nb.models``, ``nb.selection``, ``nb.vintages``,
+``nb.data_sources``, ``nb.datasets``, ``nb.news``, ``nb.density``, ``nb.evaluation``,
+``nb.benchmarks``, ``nb.diagnostics``, ``nb.visualization``, ``nb.reports``,
+``nb.experiment``, ``nb.pipeline``, ``nb.cli``, ``nb.simulate``) hold the complete API.
+
+Production use (innovation I10): ``nb.run_pipeline("nowcast.yaml")`` or the
+``nowcastbox run nowcast.yaml`` command line, with versioned snapshots
+(``nb.SnapshotStore``).
+
+Fitted results also expose the wave-2 tools as methods: ``res.news(old, new, period)``,
+``res.nowcast_tracker(...)``, ``res.level_contributions()``, ``res.distribution()``,
+``res.diagnostics()`` and ``res.plot(kind)``.
+
+Examples
+--------
+>>> import nowcastbox as nb
+>>> isinstance(nb.__version__, str)
+True
+>>> from nowcastbox.models.two_step import simulate_two_step_example
+>>> data = simulate_two_step_example(random_state=0)
+>>> res = nb.TwoStepDFM(n_factors=1).fit(data, target="gdp")
+>>> list(res.nowcast.columns)[:3]
+['observed', 'in_sample', 'out_of_sample']
+"""
+
+from nowcastbox import (
+    benchmarks,
+    cli,
+    core,
+    data_sources,
+    datasets,
+    density,
+    diagnostics,
+    evaluation,
+    experiment,
+    models,
+    news,
+    pipeline,
+    preprocessing,
+    reports,
+    selection,
+    simulate,
+    statespace,
+    utils,
+    vintages,
+    visualization,
+)
+from nowcastbox.__version__ import __version__
+from nowcastbox.api import nowcast
+from nowcastbox.core import (
+    AggregationType,
+    BaseBenchmark,
+    BaseNowcaster,
+    ConvergenceWarning,
+    DataQualityWarning,
+    FactorResults,
+    FormulaError,
+    Frequency,
+    MixedFrequencyData,
+    ModelNotFittedError,
+    NowcastBoxError,
+    NowcastBoxWarning,
+    NowcastDataError,
+    NowcastResults,
+    SeriesCategory,
+    SeriesMetadata,
+    as_mixed_frequency_data,
+    parse_formula,
+)
+from nowcastbox.datasets import (
+    Dataset,
+    list_datasets,
+    load_brazil_calendar,
+    load_brazil_nowcast,
+    load_brazil_vintages,
+    load_dataset,
+    load_nyfed,
+    load_simulated_dfm,
+    load_us_fred_md,
+    load_us_grs_like,
+)
+from nowcastbox.density import NowcastDistribution, nowcast_distribution
+from nowcastbox.diagnostics import DiagnosticsReport, run_diagnostics
+from nowcastbox.evaluation import BacktestResults, PseudoRealTimeBacktest, scoring
+from nowcastbox.experiment import NowcastExperiment
+from nowcastbox.models import (
+    BridgeEquation,
+    BridgeResults,
+    MixedFreqDFM,
+    MixedFreqDFMResults,
+    TwoStepDFM,
+    TwoStepResults,
+)
+from nowcastbox.news import (
+    LevelContributions,
+    NewsResults,
+    NowcastTracker,
+    level_contributions,
+    news_decomposition,
+    nowcast_tracker,
+)
+from nowcastbox.pipeline import NowcastSpec, PipelineRun, SnapshotStore, run_pipeline
+from nowcastbox.preprocessing import (
+    CalendarAggregation,
+    Compose,
+    Diff,
+    Identity,
+    Log,
+    PctChange,
+    Scale,
+    TemporalAggregation,
+    Transform,
+    apply_transforms,
+    calendar_aggregation,
+    invert_transforms,
+    month_to_quarter,
+    prepare_panel,
+    quarter_to_month,
+)
+from nowcastbox.reports import NowcastReport
+from nowcastbox.selection import (
+    FactorSelectionResult,
+    SelectionPath,
+    ShockSelectionResult,
+    ValidationSettings,
+    hard_threshold,
+    select_blocks,
+    select_factors,
+    select_shocks,
+    select_targeted_predictors,
+    select_variables,
+    soft_threshold,
+)
+from nowcastbox.statespace import (
+    StateSpace,
+    kalman_filter,
+    kalman_smoother,
+    loglikelihood,
+    simulate_state_space,
+)
+from nowcastbox.vintages import (
+    ReleaseCalendar,
+    Vintage,
+    VintageStore,
+    generate_vintages,
+    pseudo_real_time,
+)
+
+__all__ = [
+    "AggregationType",
+    "BacktestResults",
+    "BaseBenchmark",
+    "BaseNowcaster",
+    "BridgeEquation",
+    "BridgeResults",
+    "CalendarAggregation",
+    "Compose",
+    "ConvergenceWarning",
+    "DataQualityWarning",
+    "Dataset",
+    "DiagnosticsReport",
+    "Diff",
+    "FactorResults",
+    "FactorSelectionResult",
+    "FormulaError",
+    "Frequency",
+    "Identity",
+    "LevelContributions",
+    "Log",
+    "MixedFreqDFM",
+    "MixedFreqDFMResults",
+    "MixedFrequencyData",
+    "ModelNotFittedError",
+    "NewsResults",
+    "NowcastBoxError",
+    "NowcastBoxWarning",
+    "NowcastDataError",
+    "NowcastDistribution",
+    "NowcastExperiment",
+    "NowcastReport",
+    "NowcastResults",
+    "NowcastSpec",
+    "NowcastTracker",
+    "PctChange",
+    "PipelineRun",
+    "PseudoRealTimeBacktest",
+    "ReleaseCalendar",
+    "Scale",
+    "SelectionPath",
+    "SeriesCategory",
+    "SeriesMetadata",
+    "ShockSelectionResult",
+    "SnapshotStore",
+    "StateSpace",
+    "TemporalAggregation",
+    "Transform",
+    "TwoStepDFM",
+    "TwoStepResults",
+    "ValidationSettings",
+    "Vintage",
+    "VintageStore",
+    "__version__",
+    "apply_transforms",
+    "as_mixed_frequency_data",
+    "benchmarks",
+    "calendar_aggregation",
+    "cli",
+    "core",
+    "data_sources",
+    "datasets",
+    "density",
+    "diagnostics",
+    "evaluation",
+    "experiment",
+    "generate_vintages",
+    "hard_threshold",
+    "invert_transforms",
+    "kalman_filter",
+    "kalman_smoother",
+    "level_contributions",
+    "list_datasets",
+    "load_brazil_calendar",
+    "load_brazil_nowcast",
+    "load_brazil_vintages",
+    "load_dataset",
+    "load_nyfed",
+    "load_simulated_dfm",
+    "load_us_fred_md",
+    "load_us_grs_like",
+    "loglikelihood",
+    "models",
+    "month_to_quarter",
+    "news",
+    "news_decomposition",
+    "nowcast",
+    "nowcast_distribution",
+    "nowcast_tracker",
+    "parse_formula",
+    "pipeline",
+    "prepare_panel",
+    "preprocessing",
+    "pseudo_real_time",
+    "quarter_to_month",
+    "reports",
+    "run_diagnostics",
+    "run_pipeline",
+    "scoring",
+    "select_blocks",
+    "select_factors",
+    "select_shocks",
+    "select_targeted_predictors",
+    "select_variables",
+    "selection",
+    "simulate",
+    "simulate_state_space",
+    "soft_threshold",
+    "statespace",
+    "utils",
+    "vintages",
+    "visualization",
+]

nowcastbox/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m nowcastbox``: run the command-line interface."""
+
+import sys
+
+from nowcastbox.cli.main import main
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

nowcastbox/__version__.py

@@ -0,0 +1,3 @@
+"""Version information for nowcastbox."""
+
+__version__ = "0.1.0"

nowcastbox/_logging.py

@@ -0,0 +1,87 @@
+"""Package-wide logging helpers.
+
+All modules obtain their logger through :func:`get_logger`, so that every logger is a
+child of the ``"nowcastbox"`` logger. A :class:`logging.NullHandler` is attached to the
+root package logger (library best practice): nothing is printed unless the user
+configures logging or calls :func:`set_log_level`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__all__ = ["LOGGER_NAME", "get_logger", "set_log_level"]
+
+LOGGER_NAME = "nowcastbox"
+
+_package_logger = logging.getLogger(LOGGER_NAME)
+_package_logger.addHandler(logging.NullHandler())
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger in the ``nowcastbox`` hierarchy.
+
+    Parameters
+    ----------
+    name : str, optional
+        Module name, typically ``__name__``. Names that do not start with
+        ``"nowcastbox"`` are prefixed with it. ``None`` returns the package logger.
+
+    Returns
+    -------
+    logging.Logger
+        The requested logger.
+
+    Examples
+    --------
+    >>> from nowcastbox._logging import get_logger
+    >>> get_logger("nowcastbox.models.em").name
+    'nowcastbox.models.em'
+    >>> get_logger("custom").name
+    'nowcastbox.custom'
+    """
+    if name is None or name == LOGGER_NAME:
+        return _package_logger
+    if not name.startswith(LOGGER_NAME + "."):
+        name = f"{LOGGER_NAME}.{name}"
+    return logging.getLogger(name)
+
+
+def set_log_level(level: int | str, *, add_stream_handler: bool = True) -> None:
+    """Set the verbosity of the package logger.
+
+    Parameters
+    ----------
+    level : int or str
+        Logging level, e.g. ``logging.INFO`` or ``"DEBUG"``.
+    add_stream_handler : bool, default True
+        Attach a :class:`logging.StreamHandler` to the package logger if it has none,
+        so that messages are actually shown.
+
+    Raises
+    ------
+    ValueError
+        If ``level`` is a string that is not a valid logging level name.
+
+    Examples
+    --------
+    >>> import logging
+    >>> from nowcastbox._logging import set_log_level, get_logger
+    >>> set_log_level("WARNING", add_stream_handler=False)
+    >>> get_logger().level == logging.WARNING
+    True
+    """
+    if isinstance(level, str):
+        resolved = logging.getLevelName(level.upper())
+        if not isinstance(resolved, int):
+            raise ValueError(f"Unknown logging level {level!r}.")
+        level = resolved
+    _package_logger.setLevel(level)
+    has_stream = any(
+        isinstance(h, logging.StreamHandler) and not isinstance(h, logging.NullHandler)
+        for h in _package_logger.handlers
+    )
+    if add_stream_handler and not has_stream:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(levelname)s: %(message)s"))
+        _package_logger.addHandler(handler)