dfm-python 0.1.0__tar.gz → 0.1.1__tar.gz

dfm_python-0.1.1/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

dfm_python-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ywcpar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{dfm_python-0.1.0 → dfm_python-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfm-python
-Version: 0.1.0
+Version: 0.1.1
 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,6 +8,7 @@ Project-URL: Repository, https://github.com/yourusername/dfm-python
 Project-URL: Issues, https://github.com/yourusername/dfm-python/issues
 Author: DFM Python Contributors
 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
@@ -97,6 +98,67 @@ factors = Res.Z  # Extracted factors
 loadings = Res.C  # Factor loadings
 ```
 
+### Complete Example with Sample Data
+
+The package includes sample data and configuration files for testing. Here's a complete working example:
+
+```python
+from dfm_python import load_config, load_data, dfm
+import pandas as pd
+import numpy as np
+
+# Load configuration (YAML or CSV format)
+config = load_config('config/example_config.yaml')
+# Alternative: config = load_config('spec/example_spec.csv')
+
+# Load sample data
+X, Time, Z = load_data(
+    'data/sample_data.csv', 
+    config, 
+    sample_start=pd.Timestamp('2000-01-01')
+)
+
+print(f"Data shape: {X.shape}")
+print(f"Time range: {Time[0]} to {Time[-1]}")
+print(f"Number of series: {len(config.series)}")
+
+# Estimate DFM model
+print("\nEstimating DFM model...")
+Res = dfm(X, config, threshold=1e-4, max_iter=1000)
+
+# Access results
+print(f"\nExtracted {Res.Z.shape[1]} factors")
+print(f"Factor loadings shape: {Res.C.shape}")
+print(f"Transition matrix shape: {Res.A.shape}")
+
+# Display factor estimates
+factors = Res.Z  # Factor estimates (T x r)
+loadings = Res.C  # Factor loadings (N x r)
+transition = Res.A  # Transition matrix
+covariance = Res.Q  # Factor covariance
+
+print(f"\nFirst few factor values:")
+print(factors[:5, :])
+```
+
+**Expected Output:**
+```
+Loading data...
+Data shape: (128, 10)
+Time range: 2000-05-01 00:00:00 to 2010-12-01 00:00:00
+Number of series: 10
+
+Estimating DFM model...
+Extracted 4 factors
+Factor loadings shape: (10, 4)
+Transition matrix shape: (4, 4)
+
+First few factor values:
+[[ 0.123 -0.045  0.012  0.008]
+ [ 0.145 -0.032  0.015  0.011]
+ ...]
+```
+
 ### Configuration
 
 The DFM module uses a configuration object (`DFMConfig`) that defines:
@@ -107,21 +169,32 @@ The DFM module uses a configuration object (`DFMConfig`) that defines:
 
 #### YAML Configuration Example
 
+The package includes a sample configuration file (`config/example_config.yaml`) that demonstrates the full configuration structure:
+
 ```yaml
-# config.yaml
+# config/example_config.yaml
 model:
   series:
-    series_1:
-      frequency: "m"
-      transformation: "pch"
-      blocks: [Global]
-    series_2:
+    gdp_real:
+      series_name: "Real GDP (Quarterly)"
       frequency: "q"
       transformation: "pca"
-      blocks: [Global, Investment]
+      category: "GDP"
+      units: "Index (2000=100)"
+      blocks: [Global, Consumption, Investment]
+    
+    consumption:
+      series_name: "Consumption (Monthly)"
+      frequency: "m"
+      transformation: "pch"
+      category: "Consumption"
+      units: "Index (2000=100)"
+      blocks: [Global, Consumption]
   
   blocks:
     Global:
+      factors: 2
+    Consumption:
       factors: 1
     Investment:
       factors: 1
@@ -134,27 +207,39 @@ dfm:
 
 #### CSV Configuration Example
 
+The package also includes a CSV configuration file (`spec/example_spec.csv`) for simpler setups:
+
 ```csv
-SeriesID,Frequency,Transformation,Block_Global,Block_Investment
-series_1,m,pch,1,0
-series_2,q,pca,1,1
+series_id,series_name,frequency,transformation,category,units,Block_Global,Block_Consumption,Block_Investment
+gdp_real,Real GDP (Quarterly),q,pca,GDP,Index (2000=100),1,1,1
+consumption,Consumption (Monthly),m,pch,Consumption,Index (2000=100),1,1,0
+investment,Investment (Monthly),m,pch,Investment,Index (2000=100),1,0,1
 ```
 
+**Note:** The first block (Global) must always have value `1` for all series, as it represents the common factor that all series load on.
+
 ### Data Format
 
 CSV data files should have:
 - First column: Date (YYYY-MM-DD format)
-- Subsequent columns: One per series (matching SeriesID from config)
-- Column names: Match SeriesID from configuration
+- Subsequent columns: One per series (matching `series_id` from config)
+- Column names: Must match `series_id` from configuration exactly
+
+The package includes sample data (`data/sample_data.csv`) with 10 time series spanning 2000-2010:
 
-Example:
 ```csv
-Date,series_1,series_2
-2000-01-01,100.0,50.0
-2000-02-01,101.0,51.0
+Date,gdp_real,gdp_nominal,consumption,investment,exports,imports,unemployment,industrial_production,retail_sales,consumer_confidence
+2000-01-01,100.0,105.0,98.5,95.0,102.0,100.5,5.2,98.0,97.5,100.0
+2000-02-01,100.2,105.3,98.7,95.2,102.2,100.7,5.1,98.3,97.8,100.2
 ...
 ```
 
+**Important Notes:**
+- Date column must be named `Date` (case-sensitive)
+- Series column names must exactly match `series_id` values in the configuration
+- Missing values should be represented as empty cells or `NaN`
+- The data supports mixed frequencies (monthly and quarterly series are handled automatically)
+
 ## Core Components
 
 ### DFMConfig
@@ -239,6 +324,45 @@ The DFM module is designed to be **generic and application-agnostic**:
 
 This separation allows the core module to be used in any context while keeping application-specific code separate.
 
+## Testing with Sample Data
+
+The package includes sample data and configuration files for testing and demonstration:
+
+- **Data**: `data/sample_data.csv` - 10 time series from 2000-2010
+- **Config (YAML)**: `config/example_config.yaml` - Full configuration example
+- **Config (CSV)**: `spec/example_spec.csv` - Simplified CSV configuration
+
+To test the package with sample data:
+
+```python
+from dfm_python import load_config, load_data, dfm
+import pandas as pd
+
+# Load sample configuration
+config = load_config('config/example_config.yaml')
+
+# Load sample data
+X, Time, Z = load_data('data/sample_data.csv', config)
+
+# Estimate model
+result = dfm(X, config, threshold=1e-4)
+
+# Check results
+print(f"Factors extracted: {result.Z.shape[1]}")
+print(f"Factor loadings shape: {result.C.shape}")
+print(f"Number of series: {result.C.shape[0]}")
+print(f"Number of time periods: {result.Z.shape[0]}")
+```
+
+You can also run the test suite:
+
+```bash
+# From project root
+python -m pytest src/test/
+# Or run specific test
+python src/test/test_synthetic.py
+```
+
 ## Requirements
 
 - Python >= 3.12

{dfm_python-0.1.0 → dfm_python-0.1.1}/README.md

@@ -56,6 +56,67 @@ factors = Res.Z  # Extracted factors
 loadings = Res.C  # Factor loadings
 ```
 
+### Complete Example with Sample Data
+
+The package includes sample data and configuration files for testing. Here's a complete working example:
+
+```python
+from dfm_python import load_config, load_data, dfm
+import pandas as pd
+import numpy as np
+
+# Load configuration (YAML or CSV format)
+config = load_config('config/example_config.yaml')
+# Alternative: config = load_config('spec/example_spec.csv')
+
+# Load sample data
+X, Time, Z = load_data(
+    'data/sample_data.csv', 
+    config, 
+    sample_start=pd.Timestamp('2000-01-01')
+)
+
+print(f"Data shape: {X.shape}")
+print(f"Time range: {Time[0]} to {Time[-1]}")
+print(f"Number of series: {len(config.series)}")
+
+# Estimate DFM model
+print("\nEstimating DFM model...")
+Res = dfm(X, config, threshold=1e-4, max_iter=1000)
+
+# Access results
+print(f"\nExtracted {Res.Z.shape[1]} factors")
+print(f"Factor loadings shape: {Res.C.shape}")
+print(f"Transition matrix shape: {Res.A.shape}")
+
+# Display factor estimates
+factors = Res.Z  # Factor estimates (T x r)
+loadings = Res.C  # Factor loadings (N x r)
+transition = Res.A  # Transition matrix
+covariance = Res.Q  # Factor covariance
+
+print(f"\nFirst few factor values:")
+print(factors[:5, :])
+```
+
+**Expected Output:**
+```
+Loading data...
+Data shape: (128, 10)
+Time range: 2000-05-01 00:00:00 to 2010-12-01 00:00:00
+Number of series: 10
+
+Estimating DFM model...
+Extracted 4 factors
+Factor loadings shape: (10, 4)
+Transition matrix shape: (4, 4)
+
+First few factor values:
+[[ 0.123 -0.045  0.012  0.008]
+ [ 0.145 -0.032  0.015  0.011]
+ ...]
+```
+
 ### Configuration
 
 The DFM module uses a configuration object (`DFMConfig`) that defines:
@@ -66,21 +127,32 @@ The DFM module uses a configuration object (`DFMConfig`) that defines:
 
 #### YAML Configuration Example
 
+The package includes a sample configuration file (`config/example_config.yaml`) that demonstrates the full configuration structure:
+
 ```yaml
-# config.yaml
+# config/example_config.yaml
 model:
   series:
-    series_1:
-      frequency: "m"
-      transformation: "pch"
-      blocks: [Global]
-    series_2:
+    gdp_real:
+      series_name: "Real GDP (Quarterly)"
       frequency: "q"
       transformation: "pca"
-      blocks: [Global, Investment]
+      category: "GDP"
+      units: "Index (2000=100)"
+      blocks: [Global, Consumption, Investment]
+    
+    consumption:
+      series_name: "Consumption (Monthly)"
+      frequency: "m"
+      transformation: "pch"
+      category: "Consumption"
+      units: "Index (2000=100)"
+      blocks: [Global, Consumption]
   
   blocks:
     Global:
+      factors: 2
+    Consumption:
       factors: 1
     Investment:
       factors: 1
@@ -93,27 +165,39 @@ dfm:
 
 #### CSV Configuration Example
 
+The package also includes a CSV configuration file (`spec/example_spec.csv`) for simpler setups:
+
 ```csv
-SeriesID,Frequency,Transformation,Block_Global,Block_Investment
-series_1,m,pch,1,0
-series_2,q,pca,1,1
+series_id,series_name,frequency,transformation,category,units,Block_Global,Block_Consumption,Block_Investment
+gdp_real,Real GDP (Quarterly),q,pca,GDP,Index (2000=100),1,1,1
+consumption,Consumption (Monthly),m,pch,Consumption,Index (2000=100),1,1,0
+investment,Investment (Monthly),m,pch,Investment,Index (2000=100),1,0,1
 ```
 
+**Note:** The first block (Global) must always have value `1` for all series, as it represents the common factor that all series load on.
+
 ### Data Format
 
 CSV data files should have:
 - First column: Date (YYYY-MM-DD format)
-- Subsequent columns: One per series (matching SeriesID from config)
-- Column names: Match SeriesID from configuration
+- Subsequent columns: One per series (matching `series_id` from config)
+- Column names: Must match `series_id` from configuration exactly
+
+The package includes sample data (`data/sample_data.csv`) with 10 time series spanning 2000-2010:
 
-Example:
 ```csv
-Date,series_1,series_2
-2000-01-01,100.0,50.0
-2000-02-01,101.0,51.0
+Date,gdp_real,gdp_nominal,consumption,investment,exports,imports,unemployment,industrial_production,retail_sales,consumer_confidence
+2000-01-01,100.0,105.0,98.5,95.0,102.0,100.5,5.2,98.0,97.5,100.0
+2000-02-01,100.2,105.3,98.7,95.2,102.2,100.7,5.1,98.3,97.8,100.2
 ...
 ```
 
+**Important Notes:**
+- Date column must be named `Date` (case-sensitive)
+- Series column names must exactly match `series_id` values in the configuration
+- Missing values should be represented as empty cells or `NaN`
+- The data supports mixed frequencies (monthly and quarterly series are handled automatically)
+
 ## Core Components
 
 ### DFMConfig
@@ -198,6 +282,45 @@ The DFM module is designed to be **generic and application-agnostic**:
 
 This separation allows the core module to be used in any context while keeping application-specific code separate.
 
+## Testing with Sample Data
+
+The package includes sample data and configuration files for testing and demonstration:
+
+- **Data**: `data/sample_data.csv` - 10 time series from 2000-2010
+- **Config (YAML)**: `config/example_config.yaml` - Full configuration example
+- **Config (CSV)**: `spec/example_spec.csv` - Simplified CSV configuration
+
+To test the package with sample data:
+
+```python
+from dfm_python import load_config, load_data, dfm
+import pandas as pd
+
+# Load sample configuration
+config = load_config('config/example_config.yaml')
+
+# Load sample data
+X, Time, Z = load_data('data/sample_data.csv', config)
+
+# Estimate model
+result = dfm(X, config, threshold=1e-4)
+
+# Check results
+print(f"Factors extracted: {result.Z.shape[1]}")
+print(f"Factor loadings shape: {result.C.shape}")
+print(f"Number of series: {result.C.shape[0]}")
+print(f"Number of time periods: {result.Z.shape[0]}")
+```
+
+You can also run the test suite:
+
+```bash
+# From project root
+python -m pytest src/test/
+# Or run specific test
+python src/test/test_synthetic.py
+```
+
 ## Requirements
 
 - Python >= 3.12