dfm-python 0.5.3__tar.gz → 0.5.5__tar.gz

{dfm_python-0.5.3 → dfm_python-0.5.5}/MANIFEST.in

@@ -1,12 +1,11 @@
-# Include only the DFM module (src/nowcasting)
+# Include only the DFM module (src/dfm_python)
 # Exclude all application-specific code (adapters, database, scripts, config, etc.)
 
 include README.md
-include LICENSE
 include pyproject.toml
 
-# Include only the nowcasting package
-recursive-include src/nowcasting *.py
+# Include only the dfm_python package
+recursive-include src/dfm_python *.py
 
 # Exclude application-specific directories
 prune adapters

{dfm_python-0.5.3 → dfm_python-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.5.3
+Version: 0.5.5
 Summary: Dynamic Factor Model (DFM) estimation and nowcasting in Python
 Project-URL: Homepage, https://github.com/yourusername/dfm-python
 Project-URL: Documentation, https://github.com/yourusername/dfm-python#readme
@@ -8,7 +8,6 @@ Project-URL: Repository, https://github.com/yourusername/dfm-python
 Project-URL: Issues, https://github.com/yourusername/dfm-python/issues
 Author: Minkey Chang
 License: MIT
-License-File: LICENSE
 Keywords: dfm,dynamic-factor-model,econometrics,forecasting,nowcasting,time-series
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -330,6 +329,95 @@ result.confidence_interval  # Confidence interval
 result.factors_at_view     # Factor state at view date
 ```
 
+## Mixed-Frequency Data Handling
+
+### Clock Frequency and Target Series
+
+The package supports mixed-frequency data where the **clock frequency** (the frequency at which factors evolve) can differ from the **target series frequency**. The clock must always be the **minimum frequency** among all series (i.e., the fastest frequency).
+
+### Supported Frequency Combinations
+
+| Frequencies | Clock | Target | Status | Description |
+|------------|-------|--------|--------|-------------|
+| `[d]` | `d` | `d` | ✅ | All daily series |
+| `[d, w]` | `d` | `d` | ✅ | Daily clock, weekly series (7-day uniform average) |
+| `[w, m]` | `w` | `m` | ✅ | Weekly clock, monthly series (4-week uniform average) |
+| `[m]` | `m` | `m` | ✅ | All monthly series |
+| `[m, q]` | `m` | `q` | ✅ | Monthly clock, quarterly series (5-month tent kernel) |
+
+### Weekly Clock with Monthly Series
+
+When `clock='w'` and target series is `frequency='m'`:
+
+**Data Structure:**
+- All data is organized at weekly frequency (T × N, where T is weekly time points)
+- Weekly series: Full weekly observations (week-over-week changes)
+- Monthly series: 3-4 NaN values per month, 1 observation per month (week-over-week changes)
+
+**Model Interpretation:**
+- **Weekly data**: Week-over-week changes (전월비 증감)
+- **Monthly data**: 4-week uniform average of weekly changes (주간 전월비 증감의 4주 평균)
+- **DFM factors**: Weekly frequency, week-over-week changes
+- **Monthly observation**: Connected to 4 weekly state variables via uniform weights `[1, 1, 1, 1]`
+
+**Tent Kernel:**
+```python
+('m', 'w'): np.array([1, 1, 1, 1])  # 4-week uniform average
+# Normalized: [0.25, 0.25, 0.25, 0.25]
+```
+
+**Prediction:**
+- `predict(horizon=4)` returns 4 weekly forecasts (clock frequency)
+- Monthly series predictions are also at weekly frequency
+- **To get monthly forecast**: Average the 4 weekly predictions for that month
+- The monthly prediction equals the average of 4 weekly factors (due to uniform average constraint)
+
+**Mathematical Relationship:**
+```
+Monthly observation = c × (f_t + f_{t-1} + f_{t-2} + f_{t-3})
+                     = c × 4 × mean(f_t, f_{t-1}, f_{t-2}, f_{t-3})
+                     = mean(f_t, f_{t-1}, f_{t-2}, f_{t-3})  (when c = 0.25)
+```
+
+Where:
+- `f_t` is the weekly factor at time t
+- `c` is the loading coefficient (constrained to be uniform via R_mat)
+- The constraint `R_mat @ Cc = q` ensures `Cc[0] = Cc[1] = Cc[2] = Cc[3]` (uniform average)
+
+### Monthly Clock with Quarterly Series
+
+When `clock='m'` and target series is `frequency='q'`:
+
+**Tent Kernel:**
+```python
+('q', 'm'): np.array([1, 2, 3, 2, 1])  # 5-month tent kernel
+# Normalized: [0.111, 0.222, 0.333, 0.222, 0.111]
+```
+
+**Model Interpretation:**
+- Quarterly observation = weighted average of 5 monthly factors (tent shape, peaking at middle month)
+- This is the traditional DFM case (quarterly → monthly)
+
+### Prediction Behavior
+
+**Important Notes:**
+1. **Predictions are always at clock frequency**: `predict(horizon=4)` with `clock='w'` returns 4 weekly forecasts
+2. **No NaN in predictions**: All series (including slower-frequency ones) get predictions at clock frequency
+3. **Aggregation for target frequency**: To get target-frequency forecasts, aggregate clock-frequency predictions:
+   - Monthly target with weekly clock: Average 4 weekly predictions per month
+   - Quarterly target with monthly clock: Apply tent kernel `[1, 2, 3, 2, 1]` to 5 monthly predictions
+
+**Example:**
+```python
+# clock='w', target='m', predict(horizon=4)
+X_forecast = model.predict(horizon=4)  # Returns (4 × N) weekly forecasts
+
+# Get monthly forecast for target series
+monthly_idx = 2  # Index of monthly target series
+weekly_forecasts = X_forecast[:, monthly_idx]  # 4 weekly values
+monthly_forecast = np.mean(weekly_forecasts)  # Average to get monthly value
+```
+
 ## Architecture
 
 ### Core Modules
@@ -390,10 +478,16 @@ pytest src/test/test_trainer.py -v
 
 ## Project Status
 
-**Version**: 0.5.1  
+**Version**: 0.5.4  
 **Status**: Stable  
 **Python**: 3.10+  
 
+### What's New in 0.5.4
+
+- **Version consistency**: Unified version numbers across all files
+- **Documentation updates**: Updated README and package documentation
+- **Stability improvements**: Enhanced numerical stability and error handling
+
 ### What's New in 0.5.1
 
 - **New `update()` method**: Replaces legacy `nowcast()` with flexible `update().predict()` pattern

{dfm_python-0.5.3 → dfm_python-0.5.5}/README.md

@@ -274,6 +274,95 @@ result.confidence_interval  # Confidence interval
 result.factors_at_view     # Factor state at view date
 ```
 
+## Mixed-Frequency Data Handling
+
+### Clock Frequency and Target Series
+
+The package supports mixed-frequency data where the **clock frequency** (the frequency at which factors evolve) can differ from the **target series frequency**. The clock must always be the **minimum frequency** among all series (i.e., the fastest frequency).
+
+### Supported Frequency Combinations
+
+| Frequencies | Clock | Target | Status | Description |
+|------------|-------|--------|--------|-------------|
+| `[d]` | `d` | `d` | ✅ | All daily series |
+| `[d, w]` | `d` | `d` | ✅ | Daily clock, weekly series (7-day uniform average) |
+| `[w, m]` | `w` | `m` | ✅ | Weekly clock, monthly series (4-week uniform average) |
+| `[m]` | `m` | `m` | ✅ | All monthly series |
+| `[m, q]` | `m` | `q` | ✅ | Monthly clock, quarterly series (5-month tent kernel) |
+
+### Weekly Clock with Monthly Series
+
+When `clock='w'` and target series is `frequency='m'`:
+
+**Data Structure:**
+- All data is organized at weekly frequency (T × N, where T is weekly time points)
+- Weekly series: Full weekly observations (week-over-week changes)
+- Monthly series: 3-4 NaN values per month, 1 observation per month (week-over-week changes)
+
+**Model Interpretation:**
+- **Weekly data**: Week-over-week changes (전월비 증감)
+- **Monthly data**: 4-week uniform average of weekly changes (주간 전월비 증감의 4주 평균)
+- **DFM factors**: Weekly frequency, week-over-week changes
+- **Monthly observation**: Connected to 4 weekly state variables via uniform weights `[1, 1, 1, 1]`
+
+**Tent Kernel:**
+```python
+('m', 'w'): np.array([1, 1, 1, 1])  # 4-week uniform average
+# Normalized: [0.25, 0.25, 0.25, 0.25]
+```
+
+**Prediction:**
+- `predict(horizon=4)` returns 4 weekly forecasts (clock frequency)
+- Monthly series predictions are also at weekly frequency
+- **To get monthly forecast**: Average the 4 weekly predictions for that month
+- The monthly prediction equals the average of 4 weekly factors (due to uniform average constraint)
+
+**Mathematical Relationship:**
+```
+Monthly observation = c × (f_t + f_{t-1} + f_{t-2} + f_{t-3})
+                     = c × 4 × mean(f_t, f_{t-1}, f_{t-2}, f_{t-3})
+                     = mean(f_t, f_{t-1}, f_{t-2}, f_{t-3})  (when c = 0.25)
+```
+
+Where:
+- `f_t` is the weekly factor at time t
+- `c` is the loading coefficient (constrained to be uniform via R_mat)
+- The constraint `R_mat @ Cc = q` ensures `Cc[0] = Cc[1] = Cc[2] = Cc[3]` (uniform average)
+
+### Monthly Clock with Quarterly Series
+
+When `clock='m'` and target series is `frequency='q'`:
+
+**Tent Kernel:**
+```python
+('q', 'm'): np.array([1, 2, 3, 2, 1])  # 5-month tent kernel
+# Normalized: [0.111, 0.222, 0.333, 0.222, 0.111]
+```
+
+**Model Interpretation:**
+- Quarterly observation = weighted average of 5 monthly factors (tent shape, peaking at middle month)
+- This is the traditional DFM case (quarterly → monthly)
+
+### Prediction Behavior
+
+**Important Notes:**
+1. **Predictions are always at clock frequency**: `predict(horizon=4)` with `clock='w'` returns 4 weekly forecasts
+2. **No NaN in predictions**: All series (including slower-frequency ones) get predictions at clock frequency
+3. **Aggregation for target frequency**: To get target-frequency forecasts, aggregate clock-frequency predictions:
+   - Monthly target with weekly clock: Average 4 weekly predictions per month
+   - Quarterly target with monthly clock: Apply tent kernel `[1, 2, 3, 2, 1]` to 5 monthly predictions
+
+**Example:**
+```python
+# clock='w', target='m', predict(horizon=4)
+X_forecast = model.predict(horizon=4)  # Returns (4 × N) weekly forecasts
+
+# Get monthly forecast for target series
+monthly_idx = 2  # Index of monthly target series
+weekly_forecasts = X_forecast[:, monthly_idx]  # 4 weekly values
+monthly_forecast = np.mean(weekly_forecasts)  # Average to get monthly value
+```
+
 ## Architecture
 
 ### Core Modules
@@ -334,10 +423,16 @@ pytest src/test/test_trainer.py -v
 
 ## Project Status
 
-**Version**: 0.5.1  
+**Version**: 0.5.4  
 **Status**: Stable  
 **Python**: 3.10+  
 
+### What's New in 0.5.4
+
+- **Version consistency**: Unified version numbers across all files
+- **Documentation updates**: Updated README and package documentation
+- **Stability improvements**: Enhanced numerical stability and error handling
+
 ### What's New in 0.5.1
 
 - **New `update()` method**: Replaces legacy `nowcast()` with flexible `update().predict()` pattern

dfm_python-0.5.5/lightning_logs/ddfm/version_14/metrics.csv

@@ -0,0 +1,2 @@
+epoch,step,train_loss_epoch
+0,0,0.9185971021652222

dfm_python-0.5.5/lightning_logs/ddfm/version_15/metrics.csv

@@ -0,0 +1,2 @@
+epoch,step,train_loss_epoch
+0,0,0.851776123046875

dfm_python-0.5.5/lightning_logs/dfm/version_230/metrics.csv

@@ -0,0 +1,2 @@
+em_iteration_epoch,epoch,loglik_epoch,step,train/em_iteration,train/loglik,train/loglik_change
+38.0,0,1164.719482421875,0,19.5,-2481.600830078125,3379.77783203125

dfm_python-0.5.5/lightning_logs/dfm/version_231/metrics.csv

@@ -0,0 +1,2 @@
+em_iteration_epoch,epoch,loglik_epoch,step,train/em_iteration,train/loglik,train/loglik_change
+11.0,0,-223.8029022216797,0,6.0,-225.65797424316406,6.871443271636963

dfm_python-0.5.5/lightning_logs/dfm/version_234/metrics.csv

@@ -0,0 +1,2 @@
+em_iteration_epoch,epoch,loglik_epoch,step,train/em_iteration,train/loglik,train/loglik_change
+100.0,0,404.97576904296875,0,50.5,417.7572937011719,3.9930291175842285

dfm_python-0.5.5/lightning_logs/dfm/version_235/metrics.csv

@@ -0,0 +1,2 @@
+em_iteration_epoch,epoch,loglik_epoch,step,train/em_iteration,train/loglik,train/loglik_change
+100.0,0,404.97576904296875,0,50.5,417.7572937011719,3.9930291175842285

dfm_python-0.5.5/lightning_logs/dfm/version_236/metrics.csv

@@ -0,0 +1,2 @@
+em_iteration_epoch,epoch,loglik_epoch,step,train/em_iteration,train/loglik,train/loglik_change
+100.0,0,404.97576904296875,0,50.5,417.7572937011719,3.9930291175842285

{dfm_python-0.5.3 → dfm_python-0.5.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dfm-python"
-version = "0.5.3"
+version = "0.5.5"
 description = "Dynamic Factor Model (DFM) estimation and nowcasting in Python"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -65,6 +65,10 @@ all = [
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.metadata]
+# Prevent automatic license-file field addition
+allow-direct-references = false
+
 [tool.hatch.build.targets.wheel]
 # Include DFM module
 # All application-specific code (adapters, database, scripts, etc.) is automatically excluded
@@ -78,6 +82,11 @@ exclude = [
     "test_venv/**",
 ]
 
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+]
+
 [project.urls]
 Homepage = "https://github.com/yourusername/dfm-python"
 Documentation = "https://github.com/yourusername/dfm-python#readme"

{dfm_python-0.5.3 → dfm_python-0.5.5}/src/dfm_python/__init__.py

@@ -65,7 +65,7 @@ Note: DFMConfig and SeriesConfig are internal implementation details.
 For detailed documentation, see the README.md file and the tutorial notebooks/scripts.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.5"
 
 # ============================================================================
 # PUBLIC API DEFINITION
@@ -85,8 +85,8 @@ __version__ = "0.5.2"
 # Configuration (from config/ subpackage)
 from .config import (
     DEFAULT_BLOCK_NAME,
-    ConfigSource, YamlSource, DictSource, HydraSource,
-    MergedConfigSource, make_config_source,
+    ConfigSource, YamlSource, HydraSource,
+    make_config_source,
 )
 # Internal imports (for backward compatibility, but not recommended)
 from .config import DFMConfig, SeriesConfig  # Internal use only
@@ -102,7 +102,9 @@ from .utils.time import calculate_rmse
 # Users can import these directly from dfm_python
 from .lightning import (
     DFMDataModule,
+    DDFMDataModule,  # DDFM-specific DataModule
     DFMDataset,  # Dataset class (usually not needed directly)
+    DDFMDataset,  # DDFM Dataset class (usually not needed directly)
     KalmanFilter,  # Module class
     EMAlgorithm,  # Module class
 )
@@ -122,8 +124,8 @@ __all__ = [
     # Constants
     'DEFAULT_BLOCK_NAME',
     # Config sources
-    'ConfigSource', 'YamlSource', 'DictSource', 'HydraSource',
-    'MergedConfigSource', 'make_config_source',
+    'ConfigSource', 'YamlSource', 'HydraSource',
+    'make_config_source',
     # Low-level API (functional interface - advanced usage)
     'BaseResult', 'DFMResult', 'DDFMResult', 'calculate_rmse', 'diagnose_series', 'print_series_diagnosis',
 ]
@@ -137,7 +139,9 @@ __all__.extend([
 # Lightning modules (mandatory dependency)
 __all__.extend([
     'DFMDataModule',
+    'DDFMDataModule',  # DDFM-specific DataModule
     'DFMDataset',  # Dataset class (usually not needed directly)
+    'DDFMDataset',  # DDFM Dataset class (usually not needed directly)
     'KalmanFilter',  # Module class
     'EMAlgorithm',  # Module class
 ])