pyeconomics 0.1.0__tar.gz

pyeconomics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nathan Ramos, CFA®
+
+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.

pyeconomics-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.1
+Name: pyeconomics
+Version: 0.1.0
+Summary: A library for economic and financial analysis
+Home-page: https://github.com/nathanramoscfa/pyeconomics
+Author: Nathan Ramos, CFA
+Author-email: nathan.ramos.github@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Description-Content-Type: text/markdown
+License-File: LICENSE

pyeconomics-0.1.0/pyeconomics/api.py

@@ -0,0 +1,136 @@
+import datetime
+import logging
+from typing import Optional
+
+import keyring
+import pandas as pd
+from fredapi import Fred
+
+
+class DataSource:
+    """
+    Abstract base class for all data source clients.
+
+    Attributes:
+        api_key (Optional[str]): API key for accessing the data source.
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        self.api_key = api_key
+
+    def fetch_data(self, series_id: str) -> pd.Series:
+        """
+        Abstract method to fetch data from a data source given a series ID.
+
+        Args:
+            series_id (str): The identifier for the data series.
+
+        Returns:
+            pandas.Series: Series containing the requested data.
+
+        Raises:
+            NotImplementedError: If method is not implemented.
+        """
+        raise NotImplementedError(
+            "This method should be overridden by subclasses."
+        )
+
+
+class FredClient(DataSource):
+    """
+    A client for fetching data from the FRED API.
+
+    Inherits from DataSource and implements methods to fetch data from FRED.
+    """
+    _instance = None
+
+    def __new__(cls, api_key: Optional[str] = None):
+        """
+        Ensures a single instance of FredClient.
+
+        Args:
+            api_key (Optional[str]): The FRED API key, retrieved from
+                keyring if None.
+
+        Returns:
+            FredClient: Singleton instance.
+        """
+        if not isinstance(cls._instance, cls):
+            cls._instance = super(FredClient, cls).__new__(cls)
+            api_key = api_key or keyring.get_password(
+                "fred", "api_key")
+            cls._instance.client = Fred(api_key=api_key)
+        return cls._instance
+
+    def fetch_data(self, series_id: str) -> pd.Series:
+        """
+        Fetches data for a given series ID from FRED.
+
+        Args:
+            series_id (str): FRED series ID to fetch data for.
+
+        Returns:
+            pandas.Series: Series containing the requested data.
+
+        Raises:
+            ValueError: If no data is found for series ID.
+            Exception: For fetch operation errors.
+        """
+        try:
+            data = self.client.get_series(series_id)
+            if data.empty:
+                raise ValueError(f"No data found for series ID {series_id}")
+            return data
+        except Exception as e:
+            logging.error(f"Fetching error for {series_id}: {e}")
+            raise
+
+    def get_latest_value(self, series_id: str) -> Optional[float]:
+        """
+        Fetches the latest value for a FRED series ID, considering only dates
+        up to today.
+
+        Args:
+            series_id (str): Identifier for the FRED data series.
+
+        Returns:
+            float: Most recent data point up to today, or None if no data.
+        """
+        try:
+            data = self.fetch_data(series_id)
+            today = datetime.date.today()
+            filtered_data = data[:str(today)]
+            return filtered_data.iloc[-1] if not filtered_data.empty else None
+        except Exception as e:
+            logging.error(f"Error in getting latest value for {series_id}: {e}")
+            raise
+
+    def get_historical_value(
+            self,
+            series_id: str,
+            periods: int = -1
+    ) -> Optional[float]:
+        """
+        Fetches a historical value for a FRED series ID.
+
+        Args:
+            series_id (str): Identifier for the FRED data series.
+            periods (int): Index of period to retrieve (negative for
+                historical).
+
+        Returns:
+            float: Historical data point value, or None if unavailable.
+        """
+        series = self.fetch_data(series_id)
+        return series.iloc[periods] \
+            if not series.empty and len(series) > -periods else None
+
+    @staticmethod
+    def get_data_or_fetch(default, series_id):
+        """Fetches data if default is None using the given FRED series ID."""
+        return fred_client.get_latest_value(
+            series_id) if default is None else default
+
+
+# Global instance of the FredClient
+fred_client = FredClient()

pyeconomics-0.1.0/pyeconomics/fred_data.py

@@ -0,0 +1,28 @@
+import pandas as pd
+
+from .api import fred_client
+
+
+def fetch_historical_fed_funds_rate() -> pd.DataFrame:
+    """
+    Fetches and combines Federal Funds Target Rate historical data.
+
+    Returns:
+        pandas.DataFrame: DataFrame containing the Federal Funds Target Rate
+            historical data.
+
+    Notes:
+        - Prior to 2008-12-15, the Federal Funds Target Rate was a single value.
+        - Post 2008-12-15, the Federal Funds Target Rate is a range.
+        - This function uses the single value up to 2008-12-15, and the upper
+          limit of the range post 2008-12-15.
+    """
+    dfedtar = fred_client.fetch_data('DFEDTAR')
+    dfedtaru = fred_client.fetch_data('DFEDTARU')
+
+    # Use only the upper limit post 2008-12-15
+    df = pd.concat([
+        dfedtar[dfedtar.index <= '2008-12-15'],
+        dfedtaru[dfedtaru.index > '2008-12-15']
+    ])
+    return df

pyeconomics-0.1.0/pyeconomics/taylor_rule.py

@@ -0,0 +1,228 @@
+import pandas as pd
+
+from .api import fred_client
+from .fred_data import fetch_historical_fed_funds_rate
+
+
+def taylor_rule(
+        inflation_series_id: str = 'PCETRIM12M159SFRBDAL',
+        unemployment_rate_series_id: str = 'UNRATE',
+        natural_unemployment_series_id: str = 'NROU',
+        real_interest_rate_series_id: str = 'DFII10',
+        fed_rate_series: pd.Series = None,
+        current_inflation: float = None,
+        current_unemployment_rate: float = None,
+        natural_unemployment_rate: float = None,
+        long_term_real_interest_rate: float = None,
+        fed_rate: float = None,
+        inflation_target: float = 2.0,
+        alpha: float = 0.5,
+        beta: float = 0.5,
+        okun_factor: float = 2.0,
+        rho: float = 0.0,
+        elb: float = 0.125,
+        apply_elb: bool = False,
+        verbose: bool = False
+) -> float:
+    """
+    Computes the Taylor Rule interest rate based on economic indicators.
+
+    Args:
+        inflation_series_id (str): Series ID for inflation data.
+        unemployment_rate_series_id (str): Series ID for unemployment rate.
+        natural_unemployment_series_id (str): Series ID for natural
+            unemployment rate.
+        real_interest_rate_series_id (str): Series ID for long-term real
+            interest rate.
+        fed_rate_series (pd.Series): Series of Federal Funds Target Rate.
+        current_inflation (float): Current inflation rate.
+        current_unemployment_rate (float): Current unemployment rate.
+        natural_unemployment_rate (float): Natural unemployment rate.
+        long_term_real_interest_rate (float): Long-term real interest rate.
+        fed_rate (float): Current Federal Funds Target Rate.
+        inflation_target (float): Target inflation rate.
+        alpha (float): Weight for inflation gap.
+        beta (float): Weight for unemployment gap.
+        okun_factor (float): Multiplier for the unemployment gap.
+        rho (float): Policy inertia coefficient. Defaults to 0.0 which means
+            no inertia and no adjustment is made to Taylor Rule estimate. A
+            value of 1.0 would mean full inertia and immediate central bank
+            adjustment to the Taylor Rule estimate.
+        elb (float): Effective lower bound for interest rates.
+        apply_elb (bool): Whether to apply the effective lower bound
+            constraint to the Taylor Rule estimate.
+        verbose (bool): Whether to print verbose output.
+
+    Returns:
+        float: Taylor Rule interest rate estimate.
+    """
+    # Fetch data if not provided
+    current_inflation = fred_client.get_data_or_fetch(
+        current_inflation, inflation_series_id)
+    current_unemployment_rate = fred_client.get_data_or_fetch(
+        current_unemployment_rate, unemployment_rate_series_id)
+    natural_unemployment_rate = fred_client.get_data_or_fetch(
+        natural_unemployment_rate, natural_unemployment_series_id)
+    long_term_real_interest_rate = fred_client.get_data_or_fetch(
+        long_term_real_interest_rate, real_interest_rate_series_id)
+
+    if fed_rate is None:
+        fed_rate = (fed_rate_series.iloc[-1] if fed_rate_series is not None
+                    else fred_client.get_latest_value('DFEDTARU'))
+
+    if None in (current_inflation, current_unemployment_rate,
+                natural_unemployment_rate, long_term_real_interest_rate,
+                fed_rate):
+        raise ValueError("Required economic data is missing.")
+
+    # Calculate gaps and Taylor Rule estimate
+    inflation_gap = current_inflation - inflation_target
+    unemployment_gap = natural_unemployment_rate - current_unemployment_rate
+
+    taylor_est = (long_term_real_interest_rate +
+                  current_inflation +
+                  alpha * inflation_gap +
+                  beta * okun_factor * unemployment_gap)
+
+    if apply_elb:
+        taylor_est = max(taylor_est, elb)
+
+    adjusted_taylor_rule_interest_rate = (
+        rho * fed_rate + (1 - rho) * taylor_est
+    )
+
+    # Verbose output
+    if verbose:
+        print(f"\n==== Economic Indicators ===================================="
+              f"==")
+        print(f"Current Inflation:                        "
+              f"  {current_inflation:.2f}%")
+        print(f"Current Unemployment Rate:                "
+              f"  {current_unemployment_rate:.2f}%")
+        print(f"Natural Unemployment Rate:                "
+              f"  {natural_unemployment_rate:.2f}%")
+        print(f"Long-Term Real Interest Rate:             "
+              f"  {long_term_real_interest_rate:.2f}%")
+        print(f"Current Fed Rate:                         "
+              f"  {fed_rate:.2f}%")
+        print(f"\n==== Gaps ==================================================="
+              f"==")
+        print(f"Inflation Gap:                            "
+              f"  {inflation_gap:.2f}%")
+        print(f"Unemployment Gap:                         "
+              f"  {unemployment_gap:.2f}%")
+        print(f"\n==== Taylor Rule ============================================"
+              f"==")
+        print(f"  Long-Term Real Interest Rate:           "
+              f"  {long_term_real_interest_rate:.2f}%")
+        print(f"  Current Inflation:                      "
+              f"+ {current_inflation:.2f}%")
+        print(f"  Alpha * Inflation Gap:                  "
+              f"+ {alpha:.2f} * {inflation_gap:.2f}%")
+        print(f"  Beta * Okun Factor * Unemployment Gap:  "
+              f"+ {beta:.2f} * {okun_factor:.2f} * {unemployment_gap:.2f}%")
+        print("---------------------------------------------------------------")
+        print(f"  Taylor Rule:                            "
+              f"  {taylor_est:.2f}%")
+        print(f"\n==== Adjusted Taylor Rule ==================================="
+              f"==")
+        print("  Adjustment Computation:")
+        print(f"  Policy Inertia Coefficient (rho):       "
+              f"  {rho:.2f}")
+        print(f"  Current Fed Rate:                       "
+              f"* {fed_rate:.2f}%")
+        print(f"  Adjustment Coefficient (1 - rho):       "
+              f"+ (1 - {rho:.2f})")
+        print(f"  Taylor Rule Estimate:                   "
+              f"* {taylor_est:.2f}%")
+        print("---------------------------------------------------------------")
+        print(f"  Adjusted Taylor Rule Estimate:          "
+              f"  {adjusted_taylor_rule_interest_rate:.2f}%")
+
+    return round(adjusted_taylor_rule_interest_rate, 2)
+
+
+def historical_taylor_rule(
+        inflation_series_id: str = 'PCETRIM12M159SFRBDAL',
+        unemployment_rate_series_id: str = 'UNRATE',
+        natural_unemployment_series_id: str = 'NROU',
+        real_interest_rate_series_id: str = 'DFII10',
+        inflation_target: float = 2.0,
+        alpha: float = 0.5,
+        beta: float = 0.5,
+        okun_factor: float = 2.0,
+        rho: float = 0.0,
+        elb: float = 0.125,
+        apply_elb: bool = False
+) -> pd.DataFrame:
+    """
+    Computes historical Taylor Rule interest rates using
+    economic indicators up to the last date with available
+    real interest rate data.
+
+    Args:
+        inflation_series_id (str): Series ID for inflation data.
+        unemployment_rate_series_id (str): Series ID for unemployment rate.
+        natural_unemployment_series_id (str): Series ID for natural
+            unemployment rate.
+        real_interest_rate_series_id (str): Series ID for long-term real
+            interest rate.
+        inflation_target (float): Target inflation rate.
+        alpha (float): Weight for inflation gap.
+        beta (float): Weight for unemployment gap.
+        okun_factor (float): Multiplier for the unemployment gap.
+        rho (float): Policy inertia coefficient. Defaults to 0.0 which means
+            no inertia and no adjustment is made to Taylor Rule estimate. A
+            value of 1.0 would mean full inertia and immediate central bank
+            adjustment to the Taylor Rule estimate.
+        elb (float): Effective lower bound for interest rates.
+        apply_elb (bool): Whether to apply the effective lower bound
+            constraint to the Taylor Rule estimate.
+
+    Returns:
+        pd.DataFrame: DataFrame with computed Taylor Rule rates.
+    """
+    # Fetch historical data for all series
+    inflation = fred_client.fetch_data(inflation_series_id)
+    unemployment_rate = fred_client.fetch_data(unemployment_rate_series_id)
+    natural_unemployment = fred_client.fetch_data(
+        natural_unemployment_series_id)
+    real_interest_rate = fred_client.fetch_data(real_interest_rate_series_id)
+    fed_rate = fetch_historical_fed_funds_rate()
+
+    # Combine into a DataFrame and ensure data alignment
+    data = pd.DataFrame({
+        'Inflation': inflation,
+        'UnemploymentRate': unemployment_rate,
+        'NaturalUnemploymentRate': natural_unemployment,
+        'RealInterestRate': real_interest_rate,
+        'FedRate': fed_rate
+    })
+
+    # Determine the cutoff date based on RealInterestRate data
+    last_real_interest_date = data['RealInterestRate'].last_valid_index()
+    data = data.loc[:last_real_interest_date]
+
+    # Handle missing data
+    data.ffill(inplace=True)
+    data.dropna(inplace=True)
+
+    # Calculate gaps and Taylor Rule estimation
+    data['InflationGap'] = data['Inflation'] - inflation_target
+    data['UnemploymentGap'] = (data['NaturalUnemploymentRate'] -
+                               data['UnemploymentRate'])
+    data['TaylorEst'] = (data['RealInterestRate'] +
+                         data['Inflation'] +
+                         alpha * data['InflationGap'] +
+                         beta * okun_factor * data['UnemploymentGap'])
+
+    # Apply effective lower bound constraint
+    if apply_elb:
+        data['AdjustedTaylorRule'] = data['TaylorEst'].apply(
+            lambda x: max(x, elb))
+
+    # Apply policy inertia
+    data['AdjustedTaylorRule'] = (rho * data['FedRate'] +
+                                  (1 - rho) * data['AdjustedTaylorRule'])
+
+    return round(data, 2)

pyeconomics-0.1.0/pyeconomics.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.1
+Name: pyeconomics
+Version: 0.1.0
+Summary: A library for economic and financial analysis
+Home-page: https://github.com/nathanramoscfa/pyeconomics
+Author: Nathan Ramos, CFA
+Author-email: nathan.ramos.github@gmail.com
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Description-Content-Type: text/markdown
+License-File: LICENSE

pyeconomics-0.1.0/pyeconomics.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+setup.py
+pyeconomics/__init__.py
+pyeconomics/api.py
+pyeconomics/balanced_approach_rule.py
+pyeconomics/balanced_approach_shortfalls_rule.py
+pyeconomics/first_difference_rule.py
+pyeconomics/fred_data.py
+pyeconomics/quantity_of_money.py
+pyeconomics/stock_to_flow.py
+pyeconomics/taylor_rule.py
+pyeconomics.egg-info/PKG-INFO
+pyeconomics.egg-info/SOURCES.txt
+pyeconomics.egg-info/dependency_links.txt
+pyeconomics.egg-info/top_level.txt
+tests/__init__.py

pyeconomics-0.1.0/pyeconomics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyeconomics-0.1.0/pyeconomics.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+pyeconomics
+tests

pyeconomics-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyeconomics-0.1.0/setup.py

@@ -0,0 +1,22 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='pyeconomics',
+    version='0.1.0',
+    author='Nathan Ramos, CFA',
+    author_email='nathan.ramos.github@gmail.com',
+    packages=find_packages(),
+    description='A library for economic and financial analysis',
+    long_description=open('README.md').read(),
+    long_description_content_type='text/markdown',
+    url='https://github.com/nathanramoscfa/pyeconomics',
+    install_requires=[
+        # Dependencies, e.g., 'numpy', 'pandas'
+    ],
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Developers',
+        'Programming Language :: Python :: 3',
+        'License :: OSI Approved :: MIT License'
+    ]
+)